@pi-archimedes/image-paste 2.12.0 → 2.14.0

package/README.md

@@ -18,13 +18,13 @@ Or the full suite instead:
 pi install npm:pi-archimedes
 ```
 
-New to Pi? Pi itself is a one-time global install and needs Node.js ≥ 22.19.0. If you need Pi, [its quickstart](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/quickstart.md) starts with `npm install -g --ignore-scripts @earendil-works/pi-coding-agent`. After installing Pi, choose one installation command above, then `cd` into your project, run `pi`, and use `/login` and `/model` inside the session. The [setup section](https://github.com/danielcherubini/pi-archimedes#setup) covers it end to end. `/reload` picks the extension up in a running session.
+New to Pi? Pi itself is a one-time global install and needs Node.js ≥ 22.19.0. If you need Pi, [its quickstart](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/quickstart.md) starts with `npm install -g --ignore-scripts @earendil-works/pi-coding-agent`. After installing Pi, choose one installation command above, then `cd` into your project, run `pi`, and use `/login` and `/model` inside the session. The [setup section](https://github.com/archimedes-codes/pi-archimedes#setup) covers it end to end. `/reload` picks the extension up in a running session.
 
 ## How it works
 
 - **Markers on paste** — pasting inserts a visible `[Image #1]` placeholder at the cursor; each paste gets the next number.
 - **Attachment on submit** — when you send the message, your text is scanned for markers and the matching queued images are attached to it. Delete a marker and its image is not attached — the text is the source of truth.
-- **Inline preview** — a preview of the attached images is sent and rendered in the TUI. Previews appear where your terminal renders inline images; on a terminal that can't show them, the image is still attached — only the preview falls back.
+- **Inline preview** — a preview of the attached images is sent and rendered in the TUI. Previews appear where your terminal renders inline images; on a terminal that can't show them, the image is still attached — only the preview falls back. Turn it off with `/archimedes` → Image Paste Preview, or `archimedes.imagePaste.preview: false`; images still attach.
 - **Same key, wider scope** — the paste key is Pi's own (`app.clipboard.pasteImage`), and taking it means covering everything it did, so with no image on the clipboard the handler falls back to what Pi does: copied **file paths** are inserted at the cursor with Pi's own spacing, and otherwise the clipboard **text** is inserted. One keypress produces one outcome, in that order: image, then paths, then text. Nothing on the clipboard leaves the draft untouched and says nothing, exactly as Pi does.
 - **Size guard** — 20 MiB **per image**, rejected with a clear message before it wastes context or hangs the submit.
 - **Bounded reads** — every clipboard read has a deadline (the same budget Pi gives its own clipboard commands), so a helper that stops answering — an X11/Wayland session that went unresponsive, say — reports `Clipboard paste failed: … timed out` instead of silently taking the paste key out of service for the rest of the session.
@@ -66,12 +66,13 @@ New to Pi? Pi itself is a one-time global install and needs Node.js ≥ 22.19.0.
 |---------|------|---------|-------------|
 | `enabled` | bool | `true` | On/off for the extension, via `/plugins` (suite-managed) |
 | `suppressNativePaste` | bool | `true` | `false` gives the paste key back to Pi: the suite's `app.clipboard.pasteImage` entry is removed from `~/.pi/agent/keybindings.json` (only that entry, only if the file holds nothing else but the suite's own `"$schema"` line) **and** no paste shortcut is registered. It also keeps the first-run offer silent — there is nothing to unbind — without spending `keybindingsPromptDone`, so turning it back on still brings the offer. You get Pi's paste and lose image attach / queue / preview on those keys. Applies at the next `/new` or `/reload`. Anything that is not the strict boolean `false` — `"false"`, `0` — keeps the default. |
+| `preview` | bool | `true` | `false` stops the inline preview of attached images on submit. Images still attach. Also in `/archimedes` → Image Paste Preview. Read on every submit, so no `/reload` needed. Anything that is not the strict boolean `false` keeps the default. |
 | `keybindingsPromptDone` | bool | `false` | Set true once the first-run keybindings.json offer has been answered (accept or decline); delete to re-open the offer |
 
 In the suite on/off is managed by the suite: toggle via `/plugins` (`archimedes.imagePaste.enabled`, default on).
 
 ## Part of the suite
 
-In [pi-archimedes](https://github.com/danielcherubini/pi-archimedes), image-paste works alongside the framed editor, the status bar, and the todo board; on/off is managed by the suite (`/plugins`, `archimedes.imagePaste.enabled`, default on).
+In [pi-archimedes](https://github.com/archimedes-codes/pi-archimedes), image-paste works alongside the framed editor, the status bar, and the todo board; on/off is managed by the suite (`/plugins`, `archimedes.imagePaste.enabled`, default on).
 
-← [Back to pi-archimedes](https://github.com/danielcherubini/pi-archimedes)
+← [Back to pi-archimedes](https://github.com/archimedes-codes/pi-archimedes)

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@pi-archimedes/image-paste",
-  "version": "2.12.0",
+  "version": "2.14.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/danielcherubini/pi-archimedes.git"
+    "url": "https://github.com/archimedes-codes/pi-archimedes.git"
   },
   "type": "module",
   "keywords": [
@@ -16,10 +16,11 @@
   "main": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./keybinding-offer": "./src/keybinding-offer.ts"
+    "./keybinding-offer": "./src/keybinding-offer.ts",
+    "./settings": "./src/settings.ts"
   },
   "dependencies": {
-    "@pi-archimedes/core": "2.12.0"
+    "@pi-archimedes/core": "2.14.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.86.0",

package/src/default-export.test.ts

@@ -11,10 +11,92 @@ vi.mock("./keybinding-offer.js", () => ({
   suiteMayClaimPasteKey: vi.fn(() => true),
 }));
 
+// The isolation case below drives a real paste through the standalone handlers,
+// so the clipboard readers are mocked (no shelling out) and the settings read is
+// pointed at a scratch dir — `core/settings-io` captures
+// `join(getAgentDir(), "settings.json")` at module load.
+const { tempDir, fs, join, mockReadClipboardImage } = vi.hoisted(() => {
+  const fs = require("node:fs");
+  const { join } = require("node:path");
+  const { tmpdir } = require("node:os");
+  const { randomUUID } = require("node:crypto");
+  const dir = join(tmpdir(), `image-paste-default-export-${randomUUID()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  return { tempDir: dir, fs, join, mockReadClipboardImage: vi.fn() };
+});
+
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+  getAgentDir: () => tempDir,
+  convertToPng: () => undefined,
+}));
+
+vi.mock("./clipboard.js", () => ({
+  readClipboardImage: mockReadClipboardImage,
+  readClipboardFilePaths: vi.fn(async () => null),
+  readClipboardText: vi.fn(async () => null),
+  buildPathInsertion: vi.fn(),
+  clipboardTextForEditor: vi.fn(),
+}));
+
 const { runNativePasteRestore } = await import("./keybinding-offer.js");
 const defaultExport = (await import("./index.js")).default;
 
+type Handler = (...args: unknown[]) => unknown;
+
+interface SubmitResult {
+	action: string;
+	images?: unknown[];
+}
+
+/**
+ * One standalone session: a factory run of its own, with the handlers that run
+ * handed to pi. pi caches the extension MODULE and re-invokes the factory per
+ * session, so two of these are two sessions in one process (#156).
+ */
+function standaloneSession() {
+	const inserted: string[] = [];
+	const on = vi.fn();
+	const registerShortcut = vi.fn();
+	const pi = {
+		on,
+		registerShortcut,
+		registerMessageRenderer: vi.fn(),
+		sendMessage: vi.fn(),
+	} as any;
+	defaultExport(pi);
+
+	const ctx = {
+		hasUI: true,
+		ui: { notify: vi.fn(), pasteToEditor: (text: string) => inserted.push(text), getEditorText: () => "" },
+	};
+	const start = on.mock.calls.find((c: Array<unknown>) => c[0] === "session_start")?.[1] as Handler;
+	const shutdown = on.mock.calls.find((c: Array<unknown>) => c[0] === "session_shutdown")?.[1] as Handler;
+	const input = on.mock.calls.find((c: Array<unknown>) => c[0] === "input")?.[1] as Handler;
+	const press = registerShortcut.mock.calls[0]![1].handler as Handler;
+
+	return {
+		inserted,
+		/** Fire this session's `session_start`. */
+		start: () => start({}, ctx),
+		/** Fire this session's `session_shutdown`. */
+		shutdown: () => shutdown({}, ctx),
+		/** Press this session's paste shortcut. */
+		press: () => press(ctx),
+		/** Submit `text` through this session's `input` handler. */
+		submit: (text: string) => input({ text, source: "interactive" }) as Promise<SubmitResult>,
+	};
+}
+
 describe("image-paste default export (standalone factory)", () => {
+	beforeEach(() => {
+		fs.rmSync(join(tempDir, "settings.json"), { force: true });
+		mockReadClipboardImage.mockReset();
+		mockReadClipboardImage.mockResolvedValue({
+			bytes: new Uint8Array([1, 2, 3]),
+			mimeType: "image/png",
+		});
+	});
+
 	it("is a function that registers paste + per-session lifecycle on the pi extension", () => {
 		expect(typeof defaultExport).toBe("function");
 
@@ -37,19 +119,34 @@ describe("image-paste default export (standalone factory)", () => {
 		);
 	});
 
-	it("resets the per-session queue on session_start and clears it on shutdown", () => {
-		const on = vi.fn();
-		const pi = { on, registerShortcut: vi.fn(), registerMessageRenderer: vi.fn() } as any;
-		defaultExport(pi);
-
-		const startHandler = on.mock.calls.find((c: Array<unknown>) => c[0] === "session_start")?.[1];
-		const shutdownHandler = on.mock.calls.find((c: Array<unknown>) => c[0] === "session_shutdown")?.[1];
-		expect(typeof startHandler).toBe("function");
-		expect(typeof shutdownHandler).toBe("function");
-
-		// Must not throw when wired to a session context
-		expect(() => (startHandler as (...a: unknown[]) => unknown)({}, { hasUI: true })).not.toThrow();
-		expect(() => (shutdownHandler as (...a: unknown[]) => unknown)({}, {})).not.toThrow();
+	it("a session's shutdown clears its OWN queue and leaves another session's intact", async () => {
+		// #156: pi caches the module and re-runs the factory per session, so the
+		// lifecycle handlers of two sessions coexist in one process. The old
+		// module-level state meant a child's `session_shutdown` cleared the MAIN
+		// session's queue (dead paste key, silently) and a child's
+		// `session_start` replaced it (the queued image never attached). Both
+		// halves are asserted here through the standalone wiring; the same
+		// guarantee through the named export is in session-isolation.test.ts.
+		const main = standaloneSession();
+		await main.start();
+		await main.press(); // main's queue now holds "[Image #1]"
+		expect(main.inserted).toEqual(["[Image #1] "]);
+
+		const child = standaloneSession();
+		await child.start();
+		await child.shutdown();
+
+		// The main session's queue survived the child's teardown: its shortcut
+		// reaches the clipboard again rather than returning at the `!queue` guard.
+		await main.press();
+		expect(mockReadClipboardImage).toHaveBeenCalledTimes(2);
+		expect(main.inserted).toEqual(["[Image #1] ", "[Image #2] "]);
+
+		// …and both queued images still attach on the main session's submit — the
+		// child's session_start did not orphan the first one.
+		const result = await main.submit("[Image #1] and [Image #2] look");
+		expect(result.action).toBe("transform");
+		expect(result.images).toHaveLength(2);
 	});
 });
 

package/src/index.ts

@@ -15,6 +15,7 @@ import {
 } from "./clipboard.js";
 import { runNativePasteRestore, suiteMayClaimPasteKey } from "./keybinding-offer.js";
 import { registerImagePreview, sendPreviewMessage } from "./preview.js";
+import { previewEnabled } from "./settings.js";
 import type { ClipboardImage, PendingImage, ImageMarker } from "./types.js";
 
 const MAX_FILE_SIZE_BYTES = 20 * 1024 * 1024; // 20MB
@@ -171,12 +172,32 @@ function getImagePasteShortcuts(): KeyId[] {
   return ["ctrl+v", "alt+v", "ctrl+alt+v"] as KeyId[];
 }
 
-// Module-level state — registered once, queue reset per session
-let _ctx: ExtensionContext | null = null;
-let _queue: ImageQueue | null = null;
-let _pasting = false;
+/**
+ * The per-session handle `registerImagePaste` hands back (#156).
+ *
+ * pi caches an extension MODULE per process but re-invokes the factory with a
+ * fresh `pi` for every session, so state that lives at module scope belongs to
+ * the process, not to a session: a subordinate in-process session (a third-party
+ * subagent child) running its `session_shutdown` used to null the MAIN session's
+ * queue through the package's module-level teardown, and the paste handler
+ * then returned before reading the clipboard — silently, with no message. The
+ * handle is what makes "this session's state" expressible: whoever holds it can
+ * only ever touch the session that created it.
+ */
+export interface ImagePasteSession {
+  /** Adopt this session's ctx and start a fresh queue. Call from session_start. */
+  initSession(ctx: ExtensionContext): void;
+  /** Drop this session's state. Idempotent; touches nothing outside this session. */
+  shutdown(): void;
+}
+
+export function registerImagePaste(pi: ExtensionAPI): ImagePasteSession {
+  // Per-session state — created by THIS factory run, reachable only through the
+  // handle returned below. Never module scope: see ImagePasteSession (#156).
+  let ctxRef: ExtensionContext | null = null;
+  let queue: ImageQueue | null = null;
+  let pasting = false;
 
-export function registerImagePaste(pi: ExtensionAPI): void {
   // Register preview renderer (once)
   registerImagePreview(pi);
 
@@ -205,13 +226,13 @@ export function registerImagePaste(pi: ExtensionAPI): void {
       // bounded (a `spawnSync` timeout per CLI candidate,
       // `NATIVE_READ_TIMEOUT_MS` per native read) — because an unbounded read
       // here would hold the mutex forever and take the key out of service.
-      if (_pasting) return;
-      if (!_queue || !ctx.hasUI) return;
-      _pasting = true;
+      if (pasting) return;
+      if (!queue || !ctx.hasUI) return;
+      pasting = true;
       try {
-        await dispatchClipboardPaste(ctx, _queue);
+        await dispatchClipboardPaste(ctx, queue);
       } finally {
-        _pasting = false;
+        pasting = false;
       }
     };
 
@@ -234,13 +255,13 @@ export function registerImagePaste(pi: ExtensionAPI): void {
     if (event.source === "extension") {
       return { action: "continue" as const };
     }
-    if (!_queue || !_queue.markers.length || !_ctx) {
+    if (!queue || !queue.markers.length || !ctxRef) {
       return { action: "continue" as const };
     }
 
     // ── Marker matching: use consistent key (trimmed text) ──
     let hasMarkers = false;
-    for (const marker of _queue.markers) {
+    for (const marker of queue.markers) {
       if (event.text.includes(markerKey(marker))) {
         hasMarkers = true;
         break;
@@ -249,19 +270,19 @@ export function registerImagePaste(pi: ExtensionAPI): void {
 
     if (!hasMarkers) {
       // No markers found — clear queue (user removed them)
-      _queue.images.length = 0;
-      _queue.markers.length = 0;
-      _queue.nextIndex = 1;
+      queue.images.length = 0;
+      queue.markers.length = 0;
+      queue.nextIndex = 1;
       return { action: "continue" as const };
     }
 
     // Match markers to images using trimmed key
     const imagesToAttach: PendingImage[] = [];
 
-    for (const marker of _queue.markers) {
+    for (const marker of queue.markers) {
       const key = markerKey(marker);
       if (event.text.includes(key)) {
-        const pending = _queue.images.find((img) => img.id === marker.id);
+        const pending = queue.images.find((img) => img.id === marker.id);
         if (pending) {
           imagesToAttach.push(pending);
         }
@@ -269,19 +290,21 @@ export function registerImagePaste(pi: ExtensionAPI): void {
     }
 
     // Clear queue
-    _queue.images.length = 0;
-    _queue.markers.length = 0;
-    _queue.nextIndex = 1;
+    queue.images.length = 0;
+    queue.markers.length = 0;
+    queue.nextIndex = 1;
 
     if (imagesToAttach.length === 0) {
       return { action: "continue" as const };
     }
 
     // Send preview message for TUI display (images are invisible in user messages)
-    try {
-      sendPreviewMessage(pi, imagesToAttach);
-    } catch {
-      // Preview is optional — don't fail the submit
+    if (previewEnabled()) {
+      try {
+        sendPreviewMessage(pi, imagesToAttach);
+      } catch {
+        // Preview is optional — don't fail the submit
+      }
     }
 
     return {
@@ -294,29 +317,30 @@ export function registerImagePaste(pi: ExtensionAPI): void {
       })),
     };
   });
-}
 
-// Called on session_start to initialize/reset the queue
-export function initImagePasteSession(ctx: ExtensionContext): void {
-  _ctx = ctx;
-  _queue = createImageQueue();
-}
-
-// Called on session_shutdown to clear state
-export function shutdownImagePaste(): void {
-  _ctx = null;
-  _queue = null;
-  _pasting = false;
+  return {
+    initSession(ctx: ExtensionContext): void {
+      ctxRef = ctx;
+      queue = createImageQueue();
+    },
+    shutdown(): void {
+      ctxRef = null;
+      queue = null;
+      pasting = false;
+    },
+  };
 }
 
 // ── Default export (for standalone pi.extensions loading) ─────────────────
 
 // Pi's standalone loader requires a default export functioning as the
 // extension factory. Meta imports the named exports directly (register
-// + session lifecycle), so this default export is standalone-only.
+// + the handle it returns), so this default export is standalone-only.
 export default function (pi: ExtensionAPI): void {
-  registerImagePaste(pi);
-  // Session lifecycle: pi requires per-session ctx for image pasting.
+  const session = registerImagePaste(pi);
+  // Session lifecycle: pi requires per-session ctx for image pasting, and the
+  // state now lives in the handle above, so this session can only ever reset
+  // its own queue (#156 — a foreign session's shutdown used to clear this one).
   //
   // Registered at the TOP LEVEL of this factory — never inside another
   // session_start handler, which would accumulate handlers on /reload
@@ -329,7 +353,9 @@ export default function (pi: ExtensionAPI): void {
   // from keybindings.json, and the gate in `registerImagePaste` above stops us
   // claiming the key. Both read the same setting per session.
   pi.on("session_start", async (_event, ctx) => {
-    initImagePasteSession(ctx);
+    // The queue must be live BEFORE the restore: the restore can reload, and a
+    // session that reloaded with no queue would have a dead paste key.
+    session.initSession(ctx);
     // A broken keybindings.json must never fail a session start; the detail
     // goes to the log sink, never the console.
     try {
@@ -342,6 +368,6 @@ export default function (pi: ExtensionAPI): void {
     }
   });
   pi.on("session_shutdown", (_event, _ctx) => {
-    shutdownImagePaste();
+    session.shutdown();
   });
 }

package/src/keybinding-offer.test.ts

@@ -223,7 +223,7 @@ describe("offerKeybindingFix — gate matrix", () => {
       if (mode !== "tui") expect(confirm).not.toHaveBeenCalled();
 
       if (shouldAsk) {
-        // confirm is called with the TITLE FIRST (docs/extensions.md:165)
+        // confirm is called with the TITLE FIRST (confirm(title, message))
         const [title, message] = callArgs(confirm)[0] as [string, string];
         expect(title).toBe("First run");
         expect(typeof message).toBe("string");

package/src/keybinding-offer.ts

@@ -308,7 +308,7 @@ export async function offerKeybindingFix(ctx: ExtensionContext): Promise<boolean
     return false;
   }
 
-  // Gate 5: ask (confirm signature is TITLE first — docs/extensions.md:165)
+  // Gate 5: ask (confirm(title, message): TITLE first — pi's types.d.ts)
   const confirmed = await ctx.ui.confirm(CONFIRM_TITLE, CONFIRM_MESSAGE);
 
   // No, or cancel (Esc/timeout — `confirm` resolves `false` either way counts

package/src/paste-mutex.test.ts

@@ -1,9 +1,10 @@
 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?
+// The mutex is the `pasting` flag in `registerImagePaste` (per session since
+// #156) 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(),
@@ -21,7 +22,7 @@ vi.mock("node:child_process", async (importOriginal) => {
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-import { initImagePasteSession, registerImagePaste } from "./index.js";
+import { 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. */
@@ -64,8 +65,8 @@ function createHarness(): Harness {
     on: () => {},
   } as unknown as ExtensionAPI;
 
-  registerImagePaste(pi);
-  initImagePasteSession(ctx);
+  const session = registerImagePaste(pi);
+  session.initSession(ctx);
   const pressKey = handlers.get("ctrl+v")!;
   return { ctx, press: () => pressKey(ctx), inserted, notifications };
 }
@@ -121,7 +122,7 @@ describe("the ctrl+v mutex against a clipboard that never answers", () => {
       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
+      // `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();

package/src/preview-setting.test.ts

@@ -0,0 +1,174 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// `archimedes.imagePaste.preview: false` skips the inline preview message on
+// submit; the image still attaches and the paste-time notify still fires.
+//
+// Settings: `core/settings-io` captures `join(getAgentDir(), "settings.json")`
+// at module load, hence one scratch dir for the whole file, rewritten per case.
+// Clipboard: the readers are mocked so a paste yields image bytes without
+// shelling out.
+
+const { tempDir, fs, join, mockReadClipboardImage } = vi.hoisted(() => {
+  const fs = require("node:fs");
+  const { join } = require("node:path");
+  const { tmpdir } = require("node:os");
+  const { randomUUID } = require("node:crypto");
+  const dir = join(tmpdir(), `image-paste-preview-setting-${randomUUID()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  return { tempDir: dir, fs, join, mockReadClipboardImage: vi.fn() };
+});
+
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+  getAgentDir: () => tempDir,
+  convertToPng: () => undefined,
+}));
+
+vi.mock("./clipboard.js", () => ({
+  readClipboardImage: mockReadClipboardImage,
+  readClipboardFilePaths: vi.fn(async () => null),
+  readClipboardText: vi.fn(async () => null),
+  buildPathInsertion: vi.fn(),
+  clipboardTextForEditor: vi.fn(),
+}));
+
+const { registerImagePaste } = await import("./index.js");
+type ImagePasteSession = ReturnType<typeof registerImagePaste>;
+const { saveImagePastePreview } = await import("./settings.js");
+
+const NAMESPACE = "archimedes.imagePaste";
+const settingsPath = (): string => join(tempDir, "settings.json");
+
+function writeSettings(imagePaste: Record<string, unknown> | undefined): void {
+  const settings: Record<string, unknown> = {};
+  if (imagePaste !== undefined) settings[NAMESPACE] = imagePaste;
+  fs.writeFileSync(settingsPath(), JSON.stringify(settings), "utf-8");
+}
+
+type Handler = (...args: unknown[]) => unknown;
+
+interface SubmitResult {
+  action: string;
+  images?: unknown[];
+}
+
+// The handle of the most recently registered session. State is per session now
+// (#156), so the resets below drop exactly the session the previous case left
+// behind — the module-level `shutdownImagePaste()` they replace dropped every
+// session's at once, which was the bug.
+let activeSession: ImagePasteSession | null = null;
+
+/** Register once; `pasteAndSubmit()` then drives the same handlers each time. */
+function registerSession() {
+  const pi = {
+    on: vi.fn(),
+    registerShortcut: vi.fn(),
+    registerMessageRenderer: vi.fn(),
+    registerCommand: vi.fn(),
+    sendMessage: vi.fn(),
+  };
+  const notify = vi.fn();
+  const ctx = { hasUI: true, ui: { notify, pasteToEditor: vi.fn() } };
+
+  const session = registerImagePaste(pi as never);
+  session.initSession(ctx as never);
+  activeSession = session;
+
+  const paste = pi.registerShortcut.mock.calls[0]![1].handler as Handler;
+  const input = pi.on.mock.calls.find((call) => call[0] === "input")![1] as Handler;
+
+  /** Paste one image through the shortcut and submit it. */
+  async function pasteAndSubmit(): Promise<SubmitResult> {
+    await paste(ctx);
+    return (await input({ text: "[Image #1] look", source: "interactive" })) as SubmitResult;
+  }
+
+  return { pi, notify, pasteAndSubmit, session };
+}
+
+/** Register, paste one image through the shortcut, submit it; report what happened. */
+async function pasteAndSubmit() {
+  const session = registerSession();
+  const result = await session.pasteAndSubmit();
+  return { pi: session.pi, notify: session.notify, result };
+}
+
+beforeEach(() => {
+  fs.rmSync(settingsPath(), { force: true });
+  activeSession?.shutdown();
+  activeSession = null;
+  mockReadClipboardImage.mockReset();
+  mockReadClipboardImage.mockResolvedValue({ bytes: new Uint8Array([1, 2, 3]), mimeType: "image/png" });
+});
+
+describe("archimedes.imagePaste.preview", () => {
+  it("sends the preview when the setting is absent", async () => {
+    const { pi, result } = await pasteAndSubmit();
+    expect(result.action).toBe("transform");
+    expect(pi.sendMessage).toHaveBeenCalledTimes(1);
+  });
+
+  it("sends the preview when preview is true", async () => {
+    writeSettings({ preview: true });
+    const { pi } = await pasteAndSubmit();
+    expect(pi.sendMessage).toHaveBeenCalledTimes(1);
+  });
+
+  it("skips the preview when preview is false, but still notifies and attaches", async () => {
+    writeSettings({ preview: false });
+    const { pi, notify, result } = await pasteAndSubmit();
+
+    expect(pi.sendMessage).not.toHaveBeenCalled();
+    expect(notify).toHaveBeenCalledWith("Image attached from clipboard.", "info");
+    expect(result.action).toBe("transform");
+    expect(result.images).toHaveLength(1);
+  });
+
+  it("re-reads the setting on each submit through the same registered handler (no /reload)", async () => {
+    const session = registerSession();
+
+    const first = await session.pasteAndSubmit();
+    expect(session.pi.sendMessage).toHaveBeenCalledTimes(1);
+    expect(first.action).toBe("transform");
+    expect(first.images).toHaveLength(1);
+
+    writeSettings({ preview: false });
+    const second = await session.pasteAndSubmit();
+    expect(session.pi.sendMessage).toHaveBeenCalledTimes(1);
+    expect(second.action).toBe("transform");
+    expect(second.images).toHaveLength(1);
+
+    writeSettings({ preview: true });
+    const third = await session.pasteAndSubmit();
+    expect(session.pi.sendMessage).toHaveBeenCalledTimes(2);
+    expect(third.images).toHaveLength(1);
+  });
+
+  it("treats a value that is not the boolean false as on", async () => {
+    for (const value of ["false", 0]) {
+      writeSettings({ preview: value });
+      // Drop the previous iteration's session (its own handle — #156).
+      activeSession?.shutdown();
+      const { pi } = await pasteAndSubmit();
+      expect(pi.sendMessage, `preview=${JSON.stringify(value)}`).toHaveBeenCalledTimes(1);
+    }
+  });
+});
+
+describe("saveImagePastePreview (the /archimedes row)", () => {
+  it("merges preview into the namespace, keeps its other keys, and the next submit obeys it", async () => {
+    writeSettings({ enabled: true, suppressNativePaste: true, keybindingsPromptDone: true });
+    const session = registerSession();
+
+    saveImagePastePreview(false);
+    expect(JSON.parse(fs.readFileSync(settingsPath(), "utf-8"))[NAMESPACE]).toEqual({
+      enabled: true,
+      suppressNativePaste: true,
+      keybindingsPromptDone: true,
+      preview: false,
+    });
+
+    const result = await session.pasteAndSubmit();
+    expect(session.pi.sendMessage).not.toHaveBeenCalled();
+    expect(result.images).toHaveLength(1);
+  });
+});

package/src/session-isolation.test.ts

@@ -0,0 +1,154 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+// ── #156: one module instance, two sessions, no shared queue ────────────────
+//
+// pi caches an extension MODULE per process but re-invokes its factory with a
+// fresh `pi` per session, so a subordinate in-process session (a third-party
+// subagent child) shares the module with the main session. When that child ran
+// its `session_shutdown`, the package's module-level `shutdownImagePaste()`
+// nulled the MAIN session's queue and the paste handler returned at
+// `if (!queue || !ctx.hasUI) return;` before touching the clipboard — silently.
+// Reproduced live against pi 1.5.0 with a control: `alt+v` attached `[Image #1]`
+// before the child's shutdown and produced literally nothing after it.
+//
+// The fix is a handle: `registerImagePaste` creates its state per factory run
+// and hands back `{ initSession, shutdown }`, so a session can only ever drop
+// its own state. This file drives TWO sessions through ONE module instance —
+// which is exactly how pi runs it — and asserts the main session survives both
+// foreign lifecycle events. Assertions come from the `input` handler's return
+// value, so no pi internals are involved.
+//
+// Settings: `core/settings-io` captures `join(getAgentDir(), "settings.json")`
+// at module load, hence one scratch dir for the whole file (absent settings =
+// the defaults: shortcuts claimed, preview on). Clipboard: the readers are
+// mocked so a paste yields image bytes without shelling out.
+
+const { tempDir, fs, join, mockReadClipboardImage } = vi.hoisted(() => {
+  const fs = require("node:fs");
+  const { join } = require("node:path");
+  const { tmpdir } = require("node:os");
+  const { randomUUID } = require("node:crypto");
+  const dir = join(tmpdir(), `image-paste-session-isolation-${randomUUID()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  return { tempDir: dir, fs, join, mockReadClipboardImage: vi.fn() };
+});
+
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+  getAgentDir: () => tempDir,
+  convertToPng: () => undefined,
+}));
+
+vi.mock("./clipboard.js", () => ({
+  readClipboardImage: mockReadClipboardImage,
+  readClipboardFilePaths: vi.fn(async () => null),
+  readClipboardText: vi.fn(async () => null),
+  buildPathInsertion: vi.fn(),
+  clipboardTextForEditor: vi.fn(),
+}));
+
+const { registerImagePaste } = await import("./index.js");
+
+type Handler = (...args: unknown[]) => unknown;
+
+interface SubmitResult {
+  action: string;
+  images?: unknown[];
+}
+
+/**
+ * One session, exactly as pi builds one: a fresh `pi` handle through the same
+ * module instance. `initSession()` / `shutdown()` are the handle's lifecycle
+ * methods (the session's `session_start` / `session_shutdown`); `paste` and
+ * `input` drive the handlers registration handed to pi.
+ */
+function makeSession() {
+  const pi = {
+    on: vi.fn(),
+    registerShortcut: vi.fn(),
+    registerMessageRenderer: vi.fn(),
+    registerCommand: vi.fn(),
+    sendMessage: vi.fn(),
+  };
+  const inserted: string[] = [];
+  const notifications: Array<[string, string | undefined]> = [];
+  // A partial ctx, cast the way paste-mutex.test.ts casts its harness ctx: the
+  // package only ever reads `hasUI` and `ui` from it.
+  const ctx = {
+    hasUI: true,
+    ui: {
+      notify: (message: string, type?: "info" | "warning" | "error") => {
+        notifications.push([message, type]);
+      },
+      pasteToEditor: (text: string) => {
+        inserted.push(text);
+      },
+      getEditorText: () => "",
+    },
+  } as unknown as ExtensionContext;
+
+  const session = registerImagePaste(pi as never);
+
+  const pasteHandler = pi.registerShortcut.mock.calls[0]![1].handler as Handler;
+  const inputHandler = pi.on.mock.calls.find((call) => call[0] === "input")![1] as Handler;
+
+  return {
+    ...session,
+    pi,
+    ctx,
+    inserted,
+    notifications,
+    /** Press the package's paste shortcut for this session. */
+    paste: async (context = ctx) => {
+      await pasteHandler(context);
+    },
+    /** Submit an event through this session's `input` handler. */
+    input: async (event: { text: string; source: string }): Promise<SubmitResult> =>
+      (await inputHandler(event)) as SubmitResult,
+  };
+}
+
+beforeEach(() => {
+  fs.rmSync(join(tempDir, "settings.json"), { force: true });
+  mockReadClipboardImage.mockReset();
+  mockReadClipboardImage.mockResolvedValue({ bytes: new Uint8Array([1, 2, 3]), mimeType: "image/png" });
+});
+
+describe("#156 image-paste session isolation", () => {
+  it("a foreign session's shutdown does not stop the main session's paste", async () => {
+    const main = makeSession(); // registerImagePaste(mainPi) + main.initSession(mainCtx)
+    main.initSession(main.ctx); // main session_start
+
+    const child = makeSession(); // second factory run, same module — pi does this per session
+    child.initSession(child.ctx); // child session_start
+    child.shutdown(); // child session_shutdown (reason: "quit")
+
+    // 1. main's shortcut still reaches the clipboard. Pre-fix this returned at
+    //    the `!queue` guard and the reader never ran — no notify, no marker, no
+    //    message: a dead key.
+    await main.paste(main.ctx);
+
+    expect(mockReadClipboardImage, "the reader never ran for the main session").toHaveBeenCalledTimes(1);
+    expect(main.inserted).toEqual(["[Image #1] "]);
+    expect(main.notifications).toEqual([["Image attached from clipboard.", "info"]]);
+  });
+
+  it("a foreign session_start does not orphan the main session's queued image", async () => {
+    const main = makeSession();
+    main.initSession(main.ctx);
+    await main.paste(main.ctx); // the marker "[Image #1]" is in the editor
+    expect(main.inserted).toEqual(["[Image #1] "]);
+
+    const child = makeSession();
+    child.initSession(child.ctx); // child session_start only — no shutdown
+
+    // 2. main's queued image still attaches on submit. Pre-fix `_queue` was
+    //    reassigned by the child's session_start, so main's marker matched
+    //    nothing and the submit silently dropped the attached image.
+    const result = await main.input({ text: "[Image #1] look", source: "interactive" });
+
+    expect(result.action).toBe("transform");
+    expect(result.images).toHaveLength(1);
+  });
+});

package/src/settings.ts

@@ -0,0 +1,33 @@
+import type { SettingItem } from "@earendil-works/pi-tui";
+
+import { loadConfig, updateConfig } from "@pi-archimedes/core/settings-io";
+
+// Kept free of the package's main entry (clipboard, renderer) so meta's
+// /archimedes panel can import it without loading the lazily-loaded plugin.
+
+const NAMESPACE = "archimedes.imagePaste";
+
+/**
+ * `archimedes.imagePaste.preview`, default on. Only the strict boolean `false`
+ * disables it. Read per call so a settings change applies on the next submit.
+ */
+export function previewEnabled(): boolean {
+  return loadConfig<{ preview: boolean }>(NAMESPACE, { preview: true }).preview !== false;
+}
+
+export function getImagePasteSettingsItems(): SettingItem[] {
+  return [
+    {
+      id: "imagePastePreview",
+      label: "Image Paste Preview",
+      description: "Show an inline preview of pasted images after you submit",
+      currentValue: previewEnabled() ? "On" : "Off",
+      values: ["On", "Off"],
+    },
+  ];
+}
+
+/** Merges `preview` into the namespace; its other keys are kept. */
+export function saveImagePastePreview(on: boolean): void {
+  updateConfig<Record<string, unknown>>(NAMESPACE, {}, (cfg) => ({ ...cfg, preview: on }));
+}