@pi-archimedes/image-paste 2.6.3 → 2.7.1

package/README.md

@@ -42,6 +42,8 @@ New to Pi? Pi itself is a one-time global install and needs Node.js ≥ 22.19.0.
 > ```json
 > { "app.clipboard.pasteImage": [] }
 > ```
+>
+> **First-run offer (once ever, all platforms)** — when installed via the suite, on the first TUI session with image-paste enabled, if `~/.pi/agent/keybindings.json` doesn't exist yet, the suite offers to create it with exactly the snippet above: accepting creates the file and the TUI reloads automatically (the cleared binding applies immediately; if the reload fails, run `/reload`), declining or cancelling (Esc) never asks again — re-open by deleting `archimedes.imagePaste.keybindingsPromptDone` from `~/.pi/agent/settings.json`.
 
 ## Per-platform requirements
 
@@ -49,6 +51,17 @@ New to Pi? Pi itself is a one-time global install and needs Node.js ≥ 22.19.0.
 - **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.
 
+## Settings
+
+`~/.pi/agent/settings.json`, under `archimedes.imagePaste` (strict JSON):
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `enabled` | bool | `true` | On/off for the extension, via `/plugins` (suite-managed) |
+| `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).

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@pi-archimedes/image-paste",
-  "version": "2.6.3",
+  "version": "2.7.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/danielcherubini/pi-archimedes.git"
+  },
   "type": "module",
   "keywords": [
     "pi-package"
@@ -10,6 +14,13 @@
     "src"
   ],
   "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./keybinding-offer": "./src/keybinding-offer.ts"
+  },
+  "dependencies": {
+    "@pi-archimedes/core": "2.7.1"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.1.0",
     "@earendil-works/pi-tui": ">=0.1.0"

package/src/keybinding-offer.test.ts

@@ -0,0 +1,472 @@
+import {
+  afterAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "vitest";
+
+// ── hoisted: must use require() since vi.hoisted runs before imports ────────
+
+const { tempDir, fs, join, existsSyncSpy } = 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(), `keybinding-offer-test-${randomUUID()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  // Pass-through by default; specific tests re-target it (the concurrent-file
+  // case needs keybindings.json to appear between gate 4 and the pre-rename
+  // re-check).
+  const existsSyncSpy = vi.fn((p: unknown) => fs.existsSync(String(p)));
+  return { tempDir: dir, fs, join, existsSyncSpy };
+});
+
+// ── mocks: registered before the module under test is first imported ─────────
+// The mock MUST be registered before keybinding-offer.js (and the settings-io
+// it pulls in) is loaded: module-scope path constants capture getAgentDir() at
+// load time (settings-io.ts:5).
+
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+  getAgentDir: () => tempDir,
+}));
+
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  return { ...actual, existsSync: existsSyncSpy };
+});
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+// Identical to the package's ExtensionMode (dist types:208-209), which is not
+// re-exported from the package root.
+type Mode = "tui" | "rpc" | "json" | "print";
+
+const { offerKeybindingFix, CREATED_NOTIFY } = await import("./keybinding-offer.js");
+
+// ── fixtures ─────────────────────────────────────────────────────────────────
+
+const NAMESPACE = "archimedes.imagePaste";
+/** The exact snippet from packages/image-paste/README.md → "Paste shortcuts". */
+const SNIPPET = '{ "app.clipboard.pasteImage": [] }';
+/** What a concurrent process writes into keybindings.json at rename time. */
+const CONCURRENT_CONTENT = '{ "app.clipboard.pasteImage": ["ctrl+v"] }';
+
+
+const settingsPath = (): string => join(tempDir, "settings.json");
+const keybindingsPath = (): string => join(tempDir, "keybindings.json");
+const tmpPath = (): string => `${keybindingsPath()}.${process.pid}.tmp`;
+
+function writeSettings(obj: object): void {
+  fs.writeFileSync(settingsPath(), JSON.stringify(obj), "utf-8");
+}
+
+function readSettings(): Record<string, unknown> {
+  if (!fs.existsSync(settingsPath())) return {};
+  try {
+    return JSON.parse(fs.readFileSync(settingsPath(), "utf-8")) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+function readFlag(): boolean {
+  const ns = readSettings()[NAMESPACE] as Record<string, unknown> | undefined;
+  return ns?.keybindingsPromptDone === true;
+}
+
+function cleanupArtifacts(): void {
+  for (const p of [settingsPath(), settingsPath() + ".tmp", keybindingsPath(), tmpPath()]) {
+    try {
+      fs.rmSync(p, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  }
+}
+
+function makeCtx(mode: Mode) {
+  const confirm = vi.fn();
+  const notify = vi.fn();
+  const reload = vi.fn(async () => {});
+  const ctx = {
+    mode,
+    hasUI: true,
+    ui: { confirm, notify },
+    reload,
+  } as unknown as ExtensionContext;
+  return { ctx, confirm, notify, reload };
+}
+
+function callArgs(m: ReturnType<typeof vi.fn>): unknown[][] {
+  return m.mock.calls as unknown[][];
+}
+
+beforeEach(() => {
+  cleanupArtifacts();
+  existsSyncSpy.mockReset();
+  existsSyncSpy.mockImplementation((p: unknown) => fs.existsSync(String(p)));
+});
+
+afterAll(() => {
+  try {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  } catch {
+    // ignore
+  }
+});
+
+// ── gate matrix ──────────────────────────────────────────────────────────────
+// isConfigEnabled × {t,f} × ctx.mode ∈ {tui, rpc, json, print} × file {absent,
+// present} × flag {unset, set} × confirm outcome {yes, no, cancel-resolves-false}
+// (Esc/timeout: `confirm` resolves `false` either way → counts as decline).
+
+interface Case {
+  enabled: boolean;
+  mode: Mode;
+  file: "absent" | "present";
+  flag: "unset" | "set";
+  outcome: "yes" | "no" | "cancel-resolves-false";
+}
+
+const CASES: Case[] = (() => {
+  const cases: Case[] = [];
+  for (const enabled of [false, true]) {
+    for (const mode of ["tui", "rpc", "json", "print"] as Mode[]) {
+      for (const file of ["absent", "present"] as const) {
+        for (const flag of ["unset", "set"] as const) {
+          for (const outcome of ["yes", "no", "cancel-resolves-false"] as const) {
+            cases.push({ enabled, mode, file, flag, outcome });
+          }
+        }
+      }
+    }
+  }
+  return cases;
+})();
+
+describe("offerKeybindingFix — gate matrix", () => {
+  it.each(CASES)(
+    "$enabled/$mode/$file/$flag → $outcome",
+    async ({ enabled, mode, file, flag, outcome }) => {
+      // ── setup ──
+      const ns: Record<string, unknown> = {};
+      if (enabled === false) ns.enabled = false;
+      if (flag === "set") ns.keybindingsPromptDone = true;
+      const settingsBefore = { ...ns };
+      if (Object.keys(settingsBefore).length > 0) {
+        writeSettings({ [NAMESPACE]: settingsBefore });
+      }
+      const settingsBeforeJson = readSettings();
+
+      if (file === "present") {
+        fs.writeFileSync(keybindingsPath(), CONCURRENT_CONTENT, "utf-8");
+      }
+
+      const { ctx, confirm, notify } = makeCtx(mode);
+      if (outcome === "yes") confirm.mockResolvedValue(true);
+      else confirm.mockResolvedValue(false); // no + cancel: confirm resolves false
+
+      await offerKeybindingFix(ctx);
+
+      const shouldAsk =
+        enabled === true &&
+        mode === "tui" &&
+        flag === "unset" &&
+        file === "absent";
+
+      // ── gate behavior ──
+      expect(confirm).toHaveBeenCalledTimes(shouldAsk ? 1 : 0);
+      // never fires when the plugin is disabled
+      if (enabled === false) expect(confirm).not.toHaveBeenCalled();
+      // never fires when the file already exists
+      if (file === "present") expect(confirm).not.toHaveBeenCalled();
+      // never fires when the flag is already consumed
+      if (flag === "set") expect(confirm).not.toHaveBeenCalled();
+      // never fires in non-TUI modes
+      if (mode !== "tui") expect(confirm).not.toHaveBeenCalled();
+
+      if (shouldAsk) {
+        // confirm is called with the TITLE FIRST (docs/extensions.md:165)
+        const [title, message] = callArgs(confirm)[0] as [string, string];
+        expect(title).toBe("First run");
+        expect(typeof message).toBe("string");
+        expect(message).toContain("keybindings.json");
+      }
+
+      // ── file effects ──
+      const kbExists = fs.existsSync(keybindingsPath());
+      if (shouldAsk && outcome === "yes") {
+        // yes → file written with the exact snippet content
+        expect(kbExists).toBe(true);
+        expect(fs.readFileSync(keybindingsPath(), "utf-8")).toBe(SNIPPET);
+      } else {
+        // never written when the offer never fires; the pre-existing file is never
+        // clobbered
+        expect(kbExists).toBe(file === "present");
+      }
+
+      // ── flag effects ──
+      if (shouldAsk) {
+        // offer fires once and sets the flag on every outcome (yes, no, cancel → decline)
+        expect(readFlag()).toBe(true);
+      } else {
+        // non-TUI / non-offer rows never consume the flag — settings byte-identical
+        expect(readSettings()).toEqual(settingsBeforeJson);
+        expect(readFlag()).toBe(flag === "set");
+      }
+
+      // ── notifications ──
+      if (shouldAsk && outcome === "yes") {
+        expect(
+          callArgs(notify).some(
+            (c) => c[0] === CREATED_NOTIFY && c[1] === "info",
+          ),
+        ).toBe(true);
+      } else {
+        expect(notify).not.toHaveBeenCalled();
+      }
+    },
+  );
+});
+
+// ── flag persistence regression: load-modify-save preserves other keys ──────
+// saveConfig REPLACES the namespace object (settings-io.ts:29-33), so a bare
+// saveConfig(ns, { keybindingsPromptDone: true }) would erase other keys under
+// archimedes.imagePaste.
+
+describe("flag write preserves existing settings", () => {
+  async function run(outcome: "yes" | "no") {
+    writeSettings({
+      [NAMESPACE]: { enabled: true, someOtherKey: 42, nested: { a: 1 } },
+      "other.ns": { z: 1 },
+    });
+    const { ctx, confirm } = makeCtx("tui");
+    confirm.mockResolvedValue(outcome === "yes");
+    await offerKeybindingFix(ctx);
+  }
+
+  it("yes: snippet file written; other archimedes.imagePaste keys survive the flag set", async () => {
+    await run("yes");
+    expect(fs.readFileSync(keybindingsPath(), "utf-8")).toBe(SNIPPET);
+    const data = readSettings();
+    const ns = data[NAMESPACE] as Record<string, unknown>;
+    expect(ns).toEqual({
+      enabled: true,
+      someOtherKey: 42,
+      nested: { a: 1 },
+      keybindingsPromptDone: true,
+    });
+    expect(data["other.ns"]).toEqual({ z: 1 });
+  });
+
+  it("no: decline sets the flag via load-modify-save; keys survive, file untouched", async () => {
+    await run("no");
+    expect(fs.existsSync(keybindingsPath())).toBe(false);
+    const ns = readSettings()[NAMESPACE] as Record<string, unknown>;
+    expect(ns).toEqual({
+      enabled: true,
+      someOtherKey: 42,
+      nested: { a: 1 },
+      keybindingsPromptDone: true,
+    });
+  });
+});
+
+// ── error paths ──────────────────────────────────────────────────────────────
+
+describe("file write throws → flag stays false (self-heals next session)", () => {
+  it("yes with an unwritable tmp target: no file, flag unset, error notified, no throw", async () => {
+    // Make the (pid-predictable) tmp path unwritable: a directory.
+    fs.mkdirSync(tmpPath(), { recursive: true });
+
+    const { ctx, confirm, notify } = makeCtx("tui");
+    confirm.mockResolvedValue(true);
+
+    await expect(offerKeybindingFix(ctx)).resolves.toBeUndefined();
+
+    expect(confirm).toHaveBeenCalledTimes(1);
+    expect(fs.existsSync(keybindingsPath())).toBe(false);
+    expect(readFlag()).toBe(false);
+    expect(
+      readSettings()[NAMESPACE] ?? {},
+    ).toEqual({}); // nothing persisted to settings
+
+    expect(notify).toHaveBeenCalledTimes(1);
+    const [msg, type] = notify.mock.calls[0] as [string, string];
+    expect(type).toBe("warning");
+    expect(msg.length).toBeGreaterThan(0);
+  });
+});
+
+describe("flag write throws → notify, no crash (file write already succeeded)", () => {
+  it("yes with an unwritable settings target: file kept, flag unset, both notifies, no throw", async () => {
+    // Make settings.json an unwritable target: a directory (rename + direct
+    // write onto it both fail with EISDIR).
+    fs.mkdirSync(settingsPath(), { recursive: true });
+
+    const { ctx, confirm, notify } = makeCtx("tui");
+    confirm.mockResolvedValue(true);
+
+    await expect(offerKeybindingFix(ctx)).resolves.toBeUndefined();
+
+    // The file write strictly precedes the flag set and survived:
+    expect(fs.readFileSync(keybindingsPath(), "utf-8")).toBe(SNIPPET);
+    // Flag persistence failed: settings.json is still the directory, no flag
+    expect(fs.statSync(settingsPath()).isDirectory()).toBe(true);
+    expect(readFlag()).toBe(false);
+    // Gate 4 blocks the re-offer anyway (file now exists) — by design
+
+    const args = callArgs(notify);
+    expect(
+      args.some((c) => c[0] === CREATED_NOTIFY && c[1] === "info"),
+    ).toBe(true); // the file WAS created
+    expect(args.some((c) => c[1] === "warning" && String(c[0]).length > 0)).toBe(true); // flag save error: non-empty warning message
+  });
+});
+
+// ── auto-reload on accept ────────────────────────────────────────────────────
+
+describe("auto-reload on accept", () => {
+  it("yes path: ctx.reload() called exactly once after flag is persisted and CREATED_NOTIFY emitted", async () => {
+    // Track invocation order so we can assert flag is persisted before reload.
+    const order: string[] = [];
+    const { ctx, confirm, notify, reload } = makeCtx("tui");
+    confirm.mockResolvedValue(true);
+    // Wrap the reload spy to record when it's called relative to flag write.
+    reload.mockImplementation(async () => {
+      // At this point the flag must already be persisted to disk.
+      order.push(readFlag() ? "flag-then-reload" : "reload-before-flag");
+    });
+    notify.mockImplementation((...args: unknown[]) => {
+      if ((args[0] as string) === CREATED_NOTIFY) order.push("notify");
+    });
+
+    await offerKeybindingFix(ctx);
+
+    // reload called exactly once
+    expect(reload).toHaveBeenCalledTimes(1);
+    // flag was already set when reload ran
+    expect(order).toContain("flag-then-reload");
+    expect(order).not.toContain("reload-before-flag");
+    // CREATED_NOTIFY emitted before reload
+    const notifyIdx = order.indexOf("notify");
+    const reloadIdx = order.indexOf("flag-then-reload");
+    expect(notifyIdx).toBeGreaterThanOrEqual(0);
+    expect(reloadIdx).toBeGreaterThan(notifyIdx);
+    // File written
+    expect(fs.readFileSync(keybindingsPath(), "utf-8")).toBe(SNIPPET);
+    // CREATED_NOTIFY contains "reloading now"
+    expect(CREATED_NOTIFY).toContain("reloading now");
+  });
+
+  it("no path: ctx.reload() NOT called", async () => {
+    const { ctx, confirm, reload } = makeCtx("tui");
+    confirm.mockResolvedValue(false);
+    await offerKeybindingFix(ctx);
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it("cancel (resolves false) path: ctx.reload() NOT called", async () => {
+    const { ctx, confirm, reload } = makeCtx("tui");
+    confirm.mockResolvedValue(false); // Esc/timeout: same as no
+    await offerKeybindingFix(ctx);
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it("file-write-fails path: ctx.reload() NOT called", async () => {
+    // Block the file write by making the tmp path a directory
+    fs.mkdirSync(tmpPath(), { recursive: true });
+    const { ctx, confirm, reload } = makeCtx("tui");
+    confirm.mockResolvedValue(true);
+    await offerKeybindingFix(ctx);
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it("reload rejects: offer still resolves, flag persisted, file present, CREATED_NOTIFY emitted", async () => {
+    const { ctx, confirm, notify, reload } = makeCtx("tui");
+    confirm.mockResolvedValue(true);
+    reload.mockRejectedValue(new Error("Reload failed"));
+
+    await expect(offerKeybindingFix(ctx)).resolves.toBeUndefined();
+
+    // File must have been written
+    expect(fs.readFileSync(keybindingsPath(), "utf-8")).toBe(SNIPPET);
+    // Flag must have been set (reload runs after flag)
+    expect(readFlag()).toBe(true);
+    // CREATED_NOTIFY must have been emitted (fires before reload)
+    expect(
+      (notify.mock.calls as unknown[][]).some(
+        (c) => c[0] === CREATED_NOTIFY && c[1] === "info",
+      ),
+    ).toBe(true);
+    // reload was still attempted once
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("TOCTOU path: ctx.reload() NOT called", () => {
+  it("file created between gate 4 and pre-rename re-check: reload NOT called", async () => {
+    let kbHits = 0;
+    existsSyncSpy.mockImplementation((p: unknown) => {
+      const s = String(p);
+      if (s === keybindingsPath()) {
+        kbHits += 1;
+        if (kbHits >= 2) {
+          if (!fs.existsSync(s)) fs.writeFileSync(s, CONCURRENT_CONTENT, "utf-8");
+          return true;
+        }
+      }
+      return fs.existsSync(s);
+    });
+
+    const { ctx, confirm, reload } = makeCtx("tui");
+    confirm.mockResolvedValue(true);
+    await offerKeybindingFix(ctx);
+
+    expect(reload).not.toHaveBeenCalled();
+  });
+});
+
+describe("concurrent creation is never clobbered", () => {
+  it("file created between gate 4 and the pre-rename re-check: left intact, flag set", async () => {
+    // Simulate: the first keybindings.json check (gate 4) sees nothing; the
+    // second (pre-rename re-check) sees a file that a concurrent process just
+    // created — the spy materializes it on that hit.
+    let kbHits = 0;
+    existsSyncSpy.mockImplementation((p: unknown) => {
+      const s = String(p);
+      if (s === keybindingsPath()) {
+        kbHits += 1;
+        // NOTE: coupled to the module's two existsSync calls — gate-4 check,
+        // then the pre-rename re-check (keybinding-offer.ts). If the module
+        // de-duplicates or adds an existence check, update kbHits accordingly.
+        if (kbHits >= 2) {
+          if (!fs.existsSync(s)) {
+            fs.writeFileSync(s, CONCURRENT_CONTENT, "utf-8");
+          }
+          return true;
+        }
+      }
+      return fs.existsSync(s);
+    });
+
+    const { ctx, confirm, notify } = makeCtx("tui");
+    confirm.mockResolvedValue(true);
+
+    await expect(offerKeybindingFix(ctx)).resolves.toBeUndefined();
+
+    // The concurrently created file is never clobbered by the snippet
+    expect(fs.readFileSync(keybindingsPath(), "utf-8")).toBe(CONCURRENT_CONTENT);
+    expect(fs.readFileSync(keybindingsPath(), "utf-8")).not.toBe(SNIPPET);
+    // The tmp file is cleaned up
+    expect(fs.existsSync(tmpPath())).toBe(false);
+    // The offer ends: the offer was made and the fix is in force (file exists)
+    expect(readFlag()).toBe(true);
+    // We did not create the file, so we do not claim to
+    expect(
+      callArgs(notify).some((c) => c[0] === CREATED_NOTIFY),
+    ).toBe(false);
+  });
+});

package/src/keybinding-offer.ts

@@ -0,0 +1,165 @@
+import { existsSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { isConfigEnabled, loadConfig, updateConfig } from "@pi-archimedes/core/settings-io";
+
+const NAMESPACE = "archimedes.imagePaste";
+
+const CONFIRM_TITLE = "First run";
+const CONFIRM_MESSAGE =
+  "~/.pi/agent/keybindings.json is missing. Without it, Pi's built-in " +
+  "app.clipboard.pasteImage binding (Ctrl+V on Linux/macOS, Alt+V on Windows) " +
+  "double-fires with image-paste's Ctrl+V handler. Create the file now with the " +
+  "docs snippet? It clears the built-in binding (/reload applies it).";
+
+/** Exactly the snippet from packages/image-paste/README.md → "Paste shortcuts". */
+const SNIPPET_JSON = '{ "app.clipboard.pasteImage": [] }';
+
+export const CREATED_NOTIFY = "Created ~/.pi/agent/keybindings.json — reloading now";
+
+interface PromptConfig {
+  keybindingsPromptDone: boolean;
+}
+
+const PROMPT_DEFAULTS: PromptConfig = { keybindingsPromptDone: false };
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Persist `keybindingsPromptDone: true` via updateConfig: optimistic re-read
+ * check + bounded retry, so a concurrent write to settings.json (e.g. another
+ * session's /plugins toggle) is detected and re-read — the flag save cannot
+ * clobber a newer `enabled` value. Never throws: a failed save notifies and
+ * leaves the flag unset (gate 4 blocks the re-offer once the file exists anyway).
+ */
+function markPromptDone(ctx: ExtensionContext): void {
+  try {
+    updateConfig<PromptConfig>(
+      NAMESPACE,
+      PROMPT_DEFAULTS,
+      (cfg) => ({ ...cfg, keybindingsPromptDone: true }),
+    );
+  } catch (error) {
+    ctx.ui.notify(
+      `Could not persist keybinding prompt flag: ${messageOf(error)}`,
+      "warning",
+    );
+  }
+}
+
+/**
+ * First-run keybinding offer (once ever, all platforms).
+ *
+ * On the first TUI session, if `~/.pi/agent/keybindings.json` does not exist,
+ * offer to create it with the docs snippet so Pi's built-in clipboard paste
+ * doesn't double-fire with image-paste's Ctrl+V handler. Accepting writes the
+ * file (atomic tmp+rename, pre-rename existence re-check) and then sets the
+ * one-shot flag and reloads the TUI (`ctx.reload()` — the exact /reload flow:
+ * re-reads keybindings.json and re-binds shortcuts) so the cleared built-in
+ * binding applies immediately. Declining or cancelling (Esc/timeout — `confirm`
+ * resolves `false` either way) sets the flag without touching the file. A
+ * failed file write leaves the flag unset, so the offer self-heals next session.
+ *
+ * **Concurrent-session edge:** if the user runs `/new` or `/reload` while the
+ * confirm dialog is still open, `ctx.ui.confirm` resolves `false` (the TUI
+ * 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`.
+ */
+export async function offerKeybindingFix(ctx: ExtensionContext): Promise<void> {
+  // 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
+  // function runs from the meta session_start handler before plugin
+  // 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;
+  }
+
+  // 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;
+  }
+
+  // Gate 3: not yet consumed
+  if (loadConfig<PromptConfig>(NAMESPACE, { ...PROMPT_DEFAULTS }).keybindingsPromptDone === true) {
+    return;
+  }
+
+  // Gate 4: file absent — never merge into or rewrite an existing user file
+  const keybindingsPath = join(getAgentDir(), "keybindings.json");
+  if (existsSync(keybindingsPath)) {
+    return;
+  }
+
+  // Gate 5: ask (confirm signature is TITLE first — docs/extensions.md:165)
+  const confirmed = await ctx.ui.confirm(CONFIRM_TITLE, CONFIRM_MESSAGE);
+
+  // No, or cancel (Esc/timeout — `confirm` resolves `false` either way counts
+  // as decline): set the flag and do nothing else.
+  if (!confirmed) {
+    markPromptDone(ctx);
+    return;
+  }
+
+  // Yes: write the file atomically (tmp + rename) — strictly BEFORE the flag
+  // is set, so a failed write leaves both gates open and the offer self-heals.
+  const tmpPath = `${keybindingsPath}.${process.pid}.tmp`;
+  try {
+    writeFileSync(tmpPath, SNIPPET_JSON, "utf-8");
+    // Re-check immediately before the rename so a concurrently created file is
+    // never clobbered (TOCTOU).
+    if (existsSync(keybindingsPath)) {
+      // Someone created the file in the meantime: leave it intact, clean up
+      // our tmp, and end the offer (gate 4 blocks re-offer anyway).
+      try {
+        unlinkSync(tmpPath);
+      } catch {
+        // ignore
+      }
+      markPromptDone(ctx);
+      return;
+    }
+    renameSync(tmpPath, keybindingsPath);
+  } catch (error) {
+    // File write (or rename) failed: do NOT set the flag — the offer self-
+    // heals next session. Best-effort tmp cleanup first.
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+      // ignore
+    }
+    ctx.ui.notify(
+      `Could not create keybindings.json: ${messageOf(error)}`,
+      "warning",
+    );
+    return;
+  }
+
+  // File written successfully → THEN set the flag (deliberately after the
+  // write, per the design).
+  markPromptDone(ctx);
+  ctx.ui.notify(CREATED_NOTIFY, "info");
+
+  // Auto-apply: ctx.reload() runs the exact /reload TUI flow (re-reads
+  // keybindings.json + re-binds extension shortcuts). Must be the LAST
+  // use of ctx — the reload invalidates this extension instance. If the
+  // reload itself fails, the TUI shows its own "Reload failed" status;
+  // the file + flag are already persisted, so a manual /reload heals
+  // it and the offer is not repeated (flag gate).
+  // Cast: reload() is typed on ExtensionCommandContext; the session_start
+  // handler receives the base ExtensionContext, but at TUI runtime the
+  // reload action is always present (verified: runner.js:611).
+  try {
+    await (ctx as ExtensionCommandContext).reload();
+  } catch {
+    // Swallowed on purpose: see comment above. The offer never throws.
+  }
+}