@pi-archimedes/image-paste 2.13.0 → 2.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/image-paste",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/archimedes-codes/pi-archimedes.git"
@@ -20,7 +20,7 @@
     "./settings": "./src/settings.ts"
   },
   "dependencies": {
-    "@pi-archimedes/core": "2.13.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

@@ -172,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);
 
@@ -206,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;
       }
     };
 
@@ -235,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;
@@ -250,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);
         }
@@ -270,9 +290,9 @@ 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 };
@@ -297,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
@@ -332,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 {
@@ -345,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

@@ -31,7 +31,8 @@ vi.mock("./clipboard.js", () => ({
   clipboardTextForEditor: vi.fn(),
 }));
 
-const { registerImagePaste, initImagePasteSession, shutdownImagePaste } = await import("./index.js");
+const { registerImagePaste } = await import("./index.js");
+type ImagePasteSession = ReturnType<typeof registerImagePaste>;
 const { saveImagePastePreview } = await import("./settings.js");
 
 const NAMESPACE = "archimedes.imagePaste";
@@ -50,6 +51,12 @@ interface SubmitResult {
   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 = {
@@ -62,8 +69,9 @@ function registerSession() {
   const notify = vi.fn();
   const ctx = { hasUI: true, ui: { notify, pasteToEditor: vi.fn() } };
 
-  registerImagePaste(pi as never);
-  initImagePasteSession(ctx as never);
+  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;
@@ -74,7 +82,7 @@ function registerSession() {
     return (await input({ text: "[Image #1] look", source: "interactive" })) as SubmitResult;
   }
 
-  return { pi, notify, pasteAndSubmit };
+  return { pi, notify, pasteAndSubmit, session };
 }
 
 /** Register, paste one image through the shortcut, submit it; report what happened. */
@@ -86,7 +94,8 @@ async function pasteAndSubmit() {
 
 beforeEach(() => {
   fs.rmSync(settingsPath(), { force: true });
-  shutdownImagePaste();
+  activeSession?.shutdown();
+  activeSession = null;
   mockReadClipboardImage.mockReset();
   mockReadClipboardImage.mockResolvedValue({ bytes: new Uint8Array([1, 2, 3]), mimeType: "image/png" });
 });
@@ -137,7 +146,8 @@ describe("archimedes.imagePaste.preview", () => {
   it("treats a value that is not the boolean false as on", async () => {
     for (const value of ["false", 0]) {
       writeSettings({ preview: value });
-      shutdownImagePaste();
+      // 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);
     }

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);
+  });
+});