@pi-archimedes/image-paste 2.10.3 → 2.11.0

package/src/keybinding-offer.ts

@@ -1,27 +1,72 @@
-import { existsSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, 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";
+import { diag } from "@pi-archimedes/core/log";
+import {
+  isConfigEnabled,
+  loadConfig,
+  updateConfig,
+  writeAtomicPreservingSymlinks,
+} from "@pi-archimedes/core/settings-io";
 
 const NAMESPACE = "archimedes.imagePaste";
 
+/** pi's native clipboard action, the one key this package takes over. */
+const UNBIND_KEY = "app.clipboard.pasteImage";
+
+/** pi's published keybindings schema — the `$schema` value the suite writes. */
+const PI_KEYBINDINGS_SCHEMA_URL = "https://pi.dev/schemas/keybindings.schema.json";
+
 const CONFIRM_TITLE = "First run";
+// Wording is measured, not assumed: on Pi 1.2.0 the two bindings do NOT both
+// run. `app.clipboard.pasteImage` is not on pi's reserved-keybinding list, so
+// the extension shortcut wins (`runner.js:467-474`) and `handleInput` returns
+// before the built-in's paste branch (`custom-editor.js:63-70`) — what the user
+// gets without this file is one paste (ours) plus a standing `[Extension
+// issues]` line, not two pastes.
 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 " +
+  "shares the paste key with image-paste's handler: image-paste's handler wins, " +
+  "Pi never runs its own action, and every session starts with an " +
+  "[Extension issues] shortcut-conflict line. 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": [] }';
+/**
+ * Exactly the snippet from packages/image-paste/README.md → "Paste shortcuts".
+ *
+ * `$schema` points at pi's published keybindings schema. Read it as
+ * forward-compatibility and editor tooling, not as validation: pi 1.2.0 ships
+ * `KeybindingsSchema` (`dist/core/keybindings-schema.js:13`) with nothing in the
+ * shipped `dist` importing it, and what it validates at startup is *theme* JSON
+ * (`setThemeJsonValidator`, `dist/main.js:452`). What matters for us is that the
+ * loader ignores the key — `toKeybindingsConfig` does
+ * `if (key === "$schema") continue;` (`dist/core/keybindings.js:247-248`) — so
+ * the unbinding still applies, and the schema itself declares
+ * `"$schema": { "type": "string" }` (verified against the live
+ * https://pi.dev/schemas/keybindings.schema.json, whose `$id` is that URL).
+ */
+const SNIPPET_JSON =
+  `{ "$schema": "${PI_KEYBINDINGS_SCHEMA_URL}", "${UNBIND_KEY}": [] }`;
 
 export const CREATED_NOTIFY = "Created ~/.pi/agent/keybindings.json — reloading now";
 /** Fallback wording for runtimes whose event ctx has no reload (Pi 0.85.1). */
 export const CREATED_RELOAD_HINT =
   "Created ~/.pi/agent/keybindings.json — run /reload to apply";
+/**
+ * The restore twin of the two texts above. Same flow (see
+ * {@link reloadAfterKeybindingChange}), different verb: saying "Created
+ * ~/.pi/agent/keybindings.json" immediately after emptying that file would be
+ * false, and this suite tells the user what actually happened.
+ */
+export const RESTORED_NOTIFY =
+  "Restored pi's native clipboard paste — app.clipboard.pasteImage removed from ~/.pi/agent/keybindings.json, reloading now";
+/** Restore fallback for a ctx whose event context has no `reload`. */
+export const RESTORED_RELOAD_HINT =
+  "Restored pi's native clipboard paste — run /reload to apply";
 
 interface PromptConfig {
   keybindingsPromptDone: boolean;
@@ -29,10 +74,95 @@ interface PromptConfig {
 
 const PROMPT_DEFAULTS: PromptConfig = { keybindingsPromptDone: false };
 
+/** `archimedes.imagePaste`, the keys this module reads. */
+interface ImagePasteConfig {
+  suppressNativePaste: boolean;
+}
+
+/**
+ * Default `true` = today's behaviour: the suite keeps the paste key and pi's
+ * native action stays unbound. Only an explicit `false` asks for the key back
+ * (strict comparison — `"false"` and `0` are not `false`, same rule as
+ * `isConfigEnabled`).
+ */
+const IMAGE_PASTE_DEFAULTS: ImagePasteConfig = { suppressNativePaste: true };
+
+/**
+ * Whether the suite may claim pi's paste key(s) for itself this session.
+ *
+ * `true` (the default) is today's behaviour: image-paste registers the paste
+ * shortcuts and pi's native `app.clipboard.pasteImage` stays unbound. `false` —
+ * the strict boolean, same rule as {@link runNativePasteRestore} — asks for the
+ * key back, and then BOTH halves of the promise apply: the file restore removes
+ * our unbinding from `keybindings.json`, AND `registerImagePaste` registers no
+ * shortcut, so the restored native binding is actually reachable.
+ *
+ * Why the second half is needed (pi 1.2.0, measured): `app.clipboard.pasteImage`
+ * is not in `RESERVED_KEYBINDINGS_FOR_EXTENSION_CONFLICTS` (`dist/core/
+ * extensions/runner.js:9-27`), so `restrictOverride === false` and
+ * `ExtensionRunner.getShortcuts` keeps the extension shortcut and prints "…
+ * Using `<ext>`" (`dist/core/extensions/runner.js:467-474`); and
+ * `CustomEditor.handleInput` consults `onExtensionShortcut` before its
+ * `app.clipboard.pasteImage` branch and returns (`dist/modes/interactive/
+ * components/custom-editor.js:63-70`). While we hold the shortcut, an empty
+ * keybinding entry therefore changes nothing except adding a shortcut-conflict
+ * diagnostic — the key only comes back when we stop claiming it.
+ *
+ * Read per call, never cached at module scope: pi caches the extension factory
+ * (`dist/core/extensions/loader.js:461-489`) but re-invokes it per session, and
+ * the composed suite calls the registration from its own `session_start`
+ * handler, so a module-level flag would freeze the first session's answer.
+ */
+export function suiteMayClaimPasteKey(): boolean {
+  return loadConfig<ImagePasteConfig>(NAMESPACE, IMAGE_PASTE_DEFAULTS).suppressNativePaste !== false;
+}
+
 function messageOf(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+/**
+ * The reload path shared by the first-run offer and the restore: notify, then
+ * call `ExtensionCommandContext.reload` if this runtime puts it on the ctx
+ * (Pi 0.85.1 attaches it to the command context only, so the event ctx may have
+ * no `reload` — then the user is told to run `/reload` instead).
+ *
+ * `reload()` must be the LAST use of `ctx` — the reload invalidates this
+ * extension instance. A rejected reload is swallowed: the TUI shows its own
+ * "Reload failed" status and the session continues on the still-valid ctx.
+ *
+ * `opts.notify` (default `true`) suppresses BOTH messages, for a caller running
+ * on a UI-less ctx: the texts are UI messages and `runNativePasteRestore`'
+ * contract is to stay silent when `ctx.hasUI` is false. The reload itself is
+ * unaffected — a host that exposes `reload` still gets the file re-read.
+ *
+ * @returns `true` iff a reload was available and completed.
+ */
+async function reloadAfterKeybindingChange(
+  ctx: ExtensionContext,
+  notifyText: string,
+  hintText: string,
+  opts?: { notify?: boolean },
+): Promise<boolean> {
+  const shouldNotify = opts?.notify ?? true;
+  // Cast: reload() is typed on ExtensionCommandContext; the session_start
+  // handler receives the base ExtensionContext, hence the presence guard.
+  const reload = (ctx as ExtensionCommandContext).reload;
+  if (typeof reload !== "function") {
+    if (shouldNotify) ctx.ui.notify(hintText, "info");
+    return false;
+  }
+  if (shouldNotify) ctx.ui.notify(notifyText, "info");
+  try {
+    await reload();
+    return true;
+  } catch {
+    // Swallowed on purpose: the TUI shows its own "Reload failed" status, and
+    // the file change is already persisted, so a manual /reload heals it.
+    return false;
+  }
+}
+
 /**
  * Persist `keybindingsPromptDone: true` via updateConfig: optimistic re-read
  * check + bounded retry, so a concurrent write to settings.json (e.g. another
@@ -60,7 +190,10 @@ function markPromptDone(ctx: ExtensionContext): void {
  *
  * 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
+ * doesn't share the key with an action that would otherwise win — with both
+ * bindings live image-paste's handler is the one that runs, pi's own action
+ * never fires, and the session starts with a `[Extension issues]`
+ * shortcut-conflict line. Accepting writes the
  * file (atomic tmp+rename, pre-rename existence re-check) and then sets the
  * one-shot flag and, when the runtime exposes `reload()` on the session ctx,
  * reloads the TUI (the exact /reload flow: re-reads keybindings.json and
@@ -70,6 +203,13 @@ function markPromptDone(ctx: ExtensionContext): void {
  * 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.
  *
+ * **Precondition (gate 1b, issue #133):** the offer only exists for an install
+ * that is going to hold the paste key. While `suppressNativePaste` is `false`
+ * the suite registers no paste shortcut and the restore hands the key back, so
+ * there is nothing to fix and the offer stays silent — without consuming
+ * `keybindingsPromptDone`, because the setting is reversible and closing it again
+ * must still be met by the offer. See the invariant comment at the gate.
+ *
  * **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
@@ -78,8 +218,8 @@ function markPromptDone(ctx: ExtensionContext): void {
  *
  * **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
+ * and the reload completed). Every other outcome — the gates (1, 1b, 2–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
@@ -98,6 +238,59 @@ export async function offerKeybindingFix(ctx: ExtensionContext): Promise<boolean
     return false;
   }
 
+  // Gate 1b: the suite must be the one holding the paste key, or there is
+  // nothing to offer.
+  //
+  // The subject of this whole flow is the file that unbinds pi's
+  // `app.clipboard.pasteImage` so our shortcut can own the key. With
+  // `archimedes.imagePaste.suppressNativePaste: false` the install has decided
+  // the opposite (ADR 0030's amendments): `registerImagePaste` registers no
+  // paste shortcut at all (the gate in packages/image-paste/src/index.ts) and
+  // `runNativePasteRestore` takes the unbinding back out of the file below. Offering to create it anyway asked
+  // permission for a file this install does not want, left `ctrl+v` bound to
+  // nobody (pi's action cleared by the file we just wrote, our handler not
+  // registered to take the key), and handed the next session's restore an
+  // artefact to empty — so "Created ~/.pi/agent/keybindings.json" and "Restored
+  // pi's native clipboard paste" both described one file, one session apart.
+  // Issue #133.
+  //
+  // WHY HERE: it is a settings read from the same namespace as gate 1, and both
+  // answer "does this install want this flow at all", so the two configuration
+  // preconditions sit together; the position also puts it before gate 4 stats
+  // keybindings.json, and that half is asserted — gate 4's check IS
+  // `existsSync(keybindingsPath)` and the spy over `node:fs`'s `existsSync` shows
+  // a hatch-off skip never names the path (moving this check after gate 4 fails
+  // that test). Gate 3's flag read is skipped by the same position but is not
+  // observable from outside — this gate reads settings.json itself, as gate 1
+  // already did — so nothing claims to prove that half. Inserting it as a
+  // numbered gate 2 was rejected: the existing gate numbers are cited outside this
+  // file — `docs/features/first-run-keybinding-offer.md`, ADR 0030's amendment
+  // ("gate 4 of the first-run offer refuses to touch a file that is already
+  // there") and the comments in `keybinding-offer.test.ts` — and renumbering would
+  // silently point every one of those citations at the wrong check. Gate 1 keeps
+  // first place (the ADR 0012 exception), and gate 2 keeps its documented reason
+  // for not consuming the flag in non-TUI modes.
+  //
+  // It must NOT consume `keybindingsPromptDone`. The hatch is reversible: the
+  // user who sets `suppressNativePaste` back to `true` has to meet the offer in
+  // a later session, which is the whole value of an escape hatch you can undo.
+  // Like gate 2's non-TUI skip, this one leaves the offer armed.
+  //
+  // INVARIANT (mirrored at the head of `runNativePasteRestore`): for a given
+  // configuration the two flows are mutually exclusive — the offer acts only
+  // when `suiteMayClaimPasteKey()` is true, the restore only when it is false.
+  // So no session can both create the file and hand it back, and one run can
+  // never tell the user "Created …" and "Restored …" about the same file. What
+  // this does NOT forbid is the sequenced pair across a settings change: accept
+  // the offer today, set `suppressNativePaste: false` tomorrow, and the restore
+  // gives the key back — that is the hatch doing what it says, not a breach. It
+  // forbids the #133 shape, where both fired under one unchanged setting.
+  // Pinned by the "the invariant" describe in `keybinding-offer.test.ts`, which
+  // drives both entry points in the order `meta/src/index.ts` runs them.
+  if (!suiteMayClaimPasteKey()) {
+    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") {
@@ -163,36 +356,546 @@ export async function offerKeybindingFix(ctx: ExtensionContext): Promise<boolean
   // write, per the design).
   markPromptDone(ctx);
 
-  // Auto-apply: when the runtime exposes `reload()` on this ctx, run the
-  // exact /reload TUI flow (re-reads keybindings.json + re-binds extension
-  // shortcuts) so the cleared built-in binding applies immediately. Pi
-  // 0.85.1 attaches `reload()` ONLY to the command context — the base
-  // context that event handlers (like this session_start handler) receive
-  // has no `reload` property, so auto-reload activates only on Pi versions
-  // that add it to the event ctx; otherwise the user is told to run
-  // /reload. reload() 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, hence the presence guard.
-  const reload = (ctx as ExtensionCommandContext).reload;
-  if (typeof reload === "function") {
-    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 reload FAILED, so the session continues on
-      // the still-valid ctx → report `false` (the onboarding still runs).
-      return false;
+  // Auto-apply goes through the shared reload path
+  // ({@link reloadAfterKeybindingChange}): notify, then reload() when this
+  // runtime puts it on the ctx. `true` means a reload was triggered, so the
+  // caller skips the onboarding on the now-stale ctx; a failed reload is
+  // swallowed there (the TUI shows its own "Reload failed"), and the offer
+  // never throws.
+  return reloadAfterKeybindingChange(ctx, CREATED_NOTIFY, CREATED_RELOAD_HINT);
+}
+
+// ── restoreNativePaste — ADR 0030, Amendment (2026-10-13) ───────────────────
+//
+// "Declining to suppress" cannot help the user who already accepted the
+// first-run offer: they hold `~/.pi/agent/keybindings.json` containing our
+// unbinding, which is exactly why pi's native `app.clipboard.pasteImage` is
+// dead. So `archimedes.imagePaste.suppressNativePaste: false` has to give the
+// key back in TWO halves: delete our own artefact from that file — the narrow
+// exception to gate 4's "never rewrite an existing user keybindings file" rule —
+// and stop claiming the key, which `registerImagePaste` does from the same
+// setting (`suiteMayClaimPasteKey`). Removing the unbinding alone is not enough:
+// while our shortcut is registered pi keeps it and the restored binding never
+// runs. See
+// docs/decisions/0030-image-paste-superset-not-supplement.md § Amendment.
+
+/**
+ * Why a file was left alone. The five are NOT the same five files, and the
+ * warning no longer pretends otherwise (issue #127): `binding-not-empty` and an
+ * `extra-key` file that also still carries an empty `app.clipboard.pasteImage`
+ * hold an entry the user can delete, while foreign-keys-only /
+ * `$schema`-only files hold none, and the three unreadable shapes cannot be
+ * inspected at all. `manualEdit` branches on this — and on
+ * {@link pasteEntryFacts}, because which entry (if any) is in there is a fact
+ * the reason alone does not carry.
+ */
+export type UntouchedReason =
+  /** Valid JSON that is not an object (an array, a string, a number…). */
+  | "not-an-object"
+  /** Any key we did not write, including a `$schema` with another URL. */
+  | "extra-key"
+  /** `app.clipboard.pasteImage` present with a value that is not `[]`. */
+  | "binding-not-empty"
+  /** The file does not parse. */
+  | "unparsable"
+  /** The file exists but cannot be read (EISDIR, EACCES…). */
+  | "unreadable";
+
+/** What {@link restoreNativePaste} did to `keybindings.json`. */
+export type RestoreNativePasteStatus =
+  /** No file at all — nothing to restore, nothing written. */
+  | { kind: "missing"; path: string }
+  /** The file already parses to `{}` — reported WITHOUT rewriting it. */
+  | { kind: "already-restored"; path: string }
+  /** Our artefact was removed and `{}` written; pi must re-read the file. */
+  | { kind: "restored"; path: string; reloadRequired: boolean }
+  /** Left byte-for-byte alone; `manualEdit` is what to do about it — for the
+   *  refusals that hold one, the entry to remove; for the rest, no errand. */
+  | { kind: "untouched"; path: string; reason: UntouchedReason; manualEdit: string }
+  /**
+   * The rewrite itself failed (EACCES, EISDIR, ENOSPC…); the file is intact.
+   * A symlink LOOP is NOT in this case: `existsSync` follows links, so a loop —
+   * like a dangling link — reads as `"missing"` and the write is never
+   * attempted. Verified by test.
+   */
+  | { kind: "failed"; path: string; error: string; manualEdit: string };
+
+/**
+ * What {@link runNativePasteRestore} did — the restoration statuses plus
+ * `"suppressed"`, meaning the settings did not ask for the key back.
+ */
+export type NativePasteRestoreOutcome =
+  | RestoreNativePasteStatus
+  | { kind: "suppressed" };
+
+/**
+ * The once-per-process notify guard. It lives on `globalThis`, NOT in module
+ * scope, and module scope cannot work here: pi re-evaluates the extension
+ * module on every load — `loadExtensionModule()` builds a fresh jiti with
+ * **`moduleCache: false`** each time it imports an extension (pi 1.2.0
+ * `dist/core/extensions/loader.js:477-481`, `moduleCache: false` at `:478`, the
+ * import at `:481`), and `ctx.reload()` clears the cached factory first
+ * (`dist/core/resource-loader.js:359` → `clearExtensionCache()`, defined at
+ * `dist/core/extensions/loader.js:89-93`). So a `let` at module scope is
+ * re-created on `/reload` and the user would be re-warned about the same
+ * untouched file.
+ *
+ * Both codebases already use this exact technique for this exact reason: pi
+ * keeps its theme instance on `globalThis` under a `Symbol.for` key — "Use
+ * globalThis to share theme across module loaders (node + jiti in dev mode)"
+ * (`dist/modes/interactive/theme/theme.js:500-517`; comment `:502`, key `:503`,
+ * read `:509`, writes `:516-517`) — and our own deleted `packages/core/src/bus.ts`
+ * was a `globalThis` singleton for the same reason.
+ */
+const RESTORE_NOTIFIED_KEY = Symbol.for("pi-archimedes:image-paste:restore-notified");
+
+/** Spend the guard: `true` the first time per process, `false` afterwards. */
+function claimRestoreNotice(): boolean {
+  const g = globalThis as Record<symbol, unknown>;
+  if (g[RESTORE_NOTIFIED_KEY] === true) return false;
+  g[RESTORE_NOTIFIED_KEY] = true;
+  return true;
+}
+
+/**
+ * pi's pre-rename name for the paste action — `KEYBINDING_NAME_MIGRATIONS.pasteImage`
+ * (`dist/core/keybindings.js:225` in pi 1.2.0, and the same entry in 0.87.0),
+ * applied by `migrateKeybindingsConfig` (`:254-269`) before the bindings are
+ * built. So `"pasteImage": []` unbinds `app.clipboard.pasteImage` exactly as the
+ * current spelling does; measured on both versions, pi resolves the action to
+ * `[]` for that file.
+ *
+ * We still never rewrite such a file — the accept-set is only what this suite
+ * has actually written, which is the modern name — but a refusal that calls that
+ * file one "pi's own paste answers" is describing the opposite of what pi does
+ * with it. pi's startup migration rewrites legacy names on disk
+ * (`migrations.js:139-157`) before extensions load, and its own `catch {}` means
+ * a read-only agent dir leaves the legacy file in place; `keybindings.reload()`
+ * on `/reload` (`dist/modes/interactive/interactive-mode.js:5406`) re-reads
+ * without migrating, so a file replaced by a dotfiles sync mid-session reaches
+ * us un-migrated either way.
+ */
+const LEGACY_UNBIND_KEY = "pasteImage";
+
+/** Which entry of a file we read keeps pi's paste action switched off. */
+type PasteBlocker =
+  /** Nothing in the file unbinds the action, under either name. */
+  | "none"
+  /** `[]` under the name this suite writes. */
+  | "current"
+  /** `[]` under pi's pre-rename name (`{@link LEGACY_UNBIND_KEY}`). */
+  | "legacy";
+
+/**
+ * What a readable file does to the paste key, as one value, so the guidance and
+ * the reason cannot be derived from different facts.
+ */
+interface PasteEntryFacts {
+  blocker: PasteBlocker;
+  /**
+   * `[]` under the old name, sitting behind a modern entry that pi prefers: the
+   * migrator drops the legacy entry while the modern key exists
+   * (`keybindings.js:260-264`), so the old name is invisible today and takes the
+   * binding back the moment the modern entry is deleted — i.e. right after the
+   * user does what the warning tells them to do.
+   */
+  legacyBehindModern: boolean;
+}
+
+/** The facts for a file we never got far enough with to inspect. */
+const UNSEEN_FILE_FACTS: PasteEntryFacts = { blocker: "none", legacyBehindModern: false };
+
+function isEmptyBinding(value: unknown): boolean {
+  return Array.isArray(value) && value.length === 0;
+}
+
+/** The facts {@link guidanceLine} needs, read off the parsed object. */
+function pasteEntryFacts(obj: Record<string, unknown>): PasteEntryFacts {
+  const current = isEmptyBinding(obj[UNBIND_KEY]);
+  const legacy = isEmptyBinding(obj[LEGACY_UNBIND_KEY]);
+  return {
+    // The modern name wins when both are present, because pi drops the legacy
+    // entry in that case — so it decides which entry is the blocker.
+    blocker: current ? "current" : legacy ? "legacy" : "none",
+    legacyBehindModern: !current && legacy && UNBIND_KEY in obj,
+  };
+}
+
+/**
+ * The instruction for the one refusal that really does hold OUR unbinding: the
+ * entry is in there, removing it is the fix, and until it goes nothing answers
+ * the key (the file empties it and `suppressNativePaste: false` took our
+ * shortcut). Shared by the `extra-key`-with-unbinding refusal and by `failed`,
+ * whose file is our artefact.
+ */
+function removeOurEntryGuidance(path: string): string {
+  return (
+    `To give the paste key back to pi, remove the "${UNBIND_KEY}" entry from ` +
+    `${path} and run /reload. ` +
+    "image-paste is not binding the paste key either (suppressNativePaste is off), " +
+    "so that key does nothing until you do."
+  );
+}
+
+/**
+ * The same refusal for the same dead key, reached through pi's old name for the
+ * action: an entry IS there and removing it IS the fix, but it is spelled
+ * `pasteImage`, so naming the modern key would send the user looking for a line
+ * that is not in the file. It is not our artefact, so it is not named as ours
+ * and never rewritten — only described.
+ */
+function removeLegacyEntryGuidance(path: string): string {
+  return (
+    `To give the paste key back to pi, remove the "${LEGACY_UNBIND_KEY}" entry from ` +
+    `${path} and run /reload — that is the old name for "${UNBIND_KEY}", and pi ` +
+    "still reads it as an unbinding of the paste action. image-paste is not " +
+    "binding the paste key either (suppressNativePaste is off), so that key does " +
+    "nothing until you do."
+  );
+}
+
+/**
+ * The guidance line for a file the extension must not touch, naming the path and
+ * saying only what this file actually supports (issue #127, and the PR #129
+ * review of the first split).
+ *
+ * One warning used to cover every refusal, and it ordered the user to "remove the
+ * `app.clipboard.pasteImage` entry" — true only when such an entry is in there.
+ * For a file of foreign keys, a `$schema`-only file, and the three shapes we
+ * cannot read, that instruction sends someone hunting a line that is not in the
+ * file, in a file that needs no edit at all. So the wording branches:
+ *
+ * * `binding-not-empty` — an entry IS there, and removing it is still how the key
+ *   gets back to pi, but it is the user's own binding, so it is named as theirs
+ *   and the key is not called dead (their binding answers it). If pi's OLD name
+ *   sits behind it with `[]`, the sentence says to clear that one too: pi drops
+ *   the legacy entry only while the modern key exists, so deleting just the
+ *   modern one would hand the key straight back to the old unbinding.
+ * * `extra-key` holding our `[]` — the original wording, and the case where
+ *   "that key does nothing until you do" is true of a file we wrote.
+ * * `extra-key` holding `[]` under pi's old name — the same dead key and the same
+ *   fix, but the entry is named the way the file spells it.
+ * * `extra-key` with neither — nothing of ours to clean up, nothing to edit, and
+ *   pi answers the key on its own default binding, so no reload is asked for
+ *   either. No claim about who wrote the file: `$schema` with pi's published URL
+ *   is byte-for-byte what the offer writes, and it is also what a hand-written
+ *   file can carry, so authorship is not a fact the refusal can see.
+ * * the three unreadable shapes — the file is named and the cause is named, and
+ *   what happens next is stated rather than left unknown: pi throws away a file
+ *   it cannot use and every action keeps its default
+ *   (`loadRawConfig` → `undefined` → `{}` user bindings,
+ *   `dist/core/keybindings.js:285-297`), which means pi's own paste IS answering
+ *   the key and none of the file's other bindings are in force. Asking the user
+ *   to go read a file pi is ignoring would leave them looking in the wrong place.
+ *
+ * {@link pasteEntryFacts} is the one value carrying what the reason alone cannot:
+ * `extra-key` covers "an unbinding beside a foreign key" and "no unbinding at
+ * all", which need opposite instructions, and it does not say which spelling of
+ * the action the file uses. The unreadable shapes get {@link UNSEEN_FILE_FACTS}.
+ */
+function guidanceLine(path: string, reason: UntouchedReason, facts: PasteEntryFacts): string {
+  switch (reason) {
+    case "binding-not-empty":
+      return (
+        `The "${UNBIND_KEY}" binding in ${path} is yours, not something this suite ` +
+        "wrote, so it is yours to hand back: remove that entry and run /reload. " +
+        "image-paste is not binding the paste key either (suppressNativePaste is off)." +
+        (facts.legacyBehindModern
+          ? ` The file also carries the old name "${LEGACY_UNBIND_KEY}", which pi reads ` +
+            "as the same action, so clear that entry too — once the entry above is gone " +
+            "it is the one keeping the paste key unbound."
+          : "")
+      );
+    case "extra-key":
+      if (facts.blocker === "current") return removeOurEntryGuidance(path);
+      if (facts.blocker === "legacy") return removeLegacyEntryGuidance(path);
+      return (
+        `Nothing in ${path} is ours to clean up and nothing in it clears pi's ` +
+        "paste binding, so there is nothing for you to edit — pi's own paste " +
+        "answers that key on its default binding. image-paste registers no paste " +
+        "shortcut of its own while suppressNativePaste is off."
+      );
+    case "unreadable":
+    case "unparsable":
+    case "not-an-object": {
+      const cause =
+        reason === "unreadable"
+          ? "it could not be read"
+          : reason === "unparsable"
+            ? "it does not parse as JSON"
+            : "it is not a JSON object";
+      return (
+        `The file is left exactly as it is; ${cause}, and pi treats a file it ` +
+        "cannot use as if it held no bindings at all — every action keeps its " +
+        "default, so pi's own paste is answering the key and nothing else in that " +
+        `file is in force. Please check ${path} yourself, and run /reload once it ` +
+        "is readable again. image-paste registers no paste shortcut of its own " +
+        "while suppressNativePaste is off."
+      );
     }
   }
-  ctx.ui.notify(CREATED_RELOAD_HINT, "info");
-  return false;
 }
+
+/** The guidance for a file we read, from the same read that gives the reason. */
+function guidanceForReadFile(
+  path: string,
+  obj: Record<string, unknown>,
+  reason: UntouchedReason,
+): string {
+  return guidanceLine(path, reason, pasteEntryFacts(obj));
+}
+
+/** The guidance for a file we never got far enough with to inspect. */
+function guidanceForUnreadableFile(path: string, reason: UntouchedReason): string {
+  return guidanceLine(path, reason, UNSEEN_FILE_FACTS);
+}
+
+function agentKeybindingsPath(): string {
+  return join(getAgentDir(), "keybindings.json");
+}
+
+/**
+ * True only for the artefact this suite has written, in either of its two
+ * shapes:
+ *
+ * * before PR #123 — `{ "app.clipboard.pasteImage": [] }`
+ * * since PR #123 — `{ "$schema": "https://pi.dev/schemas/keybindings.schema.json",
+ *   "app.clipboard.pasteImage": [] }`
+ *
+ * **Accept-set decision (the amendment asks for it explicitly):** the `$schema`
+ * + `app.clipboard.pasteImage: []` pair IS accepted, because that is literally
+ * what the suite writes today — refusing it would leave every current install
+ * unable to give the key back without a hand edit. `$schema` counts as ours
+ * only with pi's published URL, which keeps the set closed without widening it.
+ * Nothing else is ever accepted: not a third key, not a different `$schema`,
+ * not a non-empty binding — and not pi's old name for the action either
+ * ({@link LEGACY_UNBIND_KEY}). A file holding `"pasteImage": []` clears the
+ * paste key just as effectively, but this suite never wrote that spelling, so it
+ * is refused (and explained) rather than rewritten.
+ */
+function isSuiteOwnedUnbinding(obj: Record<string, unknown>): boolean {
+  if (!isEmptyBinding(obj[UNBIND_KEY])) return false;
+  const keys = Object.keys(obj);
+  if (keys.length === 1) return true;
+  return (
+    keys.length === 2 &&
+    keys.every((key) => key === UNBIND_KEY || key === "$schema") &&
+    obj["$schema"] === PI_KEYBINDINGS_SCHEMA_URL
+  );
+}
+
+/**
+ * Remove the suite's `app.clipboard.pasteImage` unbinding from
+ * `~/.pi/agent/keybindings.json` and return what it did. **It never logs and
+ * never notifies** — the caller surfaces the outcome (see
+ * {@link runNativePasteRestore}), so one run per session cannot produce two
+ * messages and a headless caller stays silent on its own.
+ *
+ * Rules (ADR 0030 amendment):
+ *
+ * * Only ever acts on the suite's own artefact, and the write only ever
+ *   *removes* the key — the result is `{}`.
+ * * Anything else — extra keys, a non-empty binding, a foreign `$schema`, pi's
+ *   old name for the action, a file that does not parse or cannot be read — is
+ *   left byte-for-byte alone, and the returned `"untouched"` status carries the
+ *   path plus the guidance that refusal warrants ({@link guidanceLine}) — the
+ *   entry to remove only when an entry really is in there, spelled the way the
+ *   file spells it.
+ * * Idempotent by content: `{}` is reported as `"already-restored"` **without a
+ *   rewrite**, so the flag cannot touch a user file on every session start.
+ * * Writes atomically through {@link writeAtomicPreservingSymlinks}, so a
+ *   `keybindings.json` that is a symlink to somewhere else stays a symlink
+ *   (the offer's own tmp+rename-onto-path is deliberately NOT reused — it only
+ *   ever *creates* a missing file, where link preservation cannot matter). A
+ *   DANGLING link never reaches that helper either: `existsSync` follows the
+ *   link, so the status is `"missing"` and nothing is written through it.
+ * * Never throws: a failed write comes back as `"failed"`.
+ */
+export function restoreNativePaste(): RestoreNativePasteStatus {
+  const path = agentKeybindingsPath();
+  if (!existsSync(path)) return { kind: "missing", path };
+
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return {
+      kind: "untouched",
+      path,
+      reason: "unreadable",
+      manualEdit: guidanceForUnreadableFile(path, "unreadable"),
+    };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {
+      kind: "untouched",
+      path,
+      reason: "unparsable",
+      manualEdit: guidanceForUnreadableFile(path, "unparsable"),
+    };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return {
+      kind: "untouched",
+      path,
+      reason: "not-an-object",
+      manualEdit: guidanceForUnreadableFile(path, "not-an-object"),
+    };
+  }
+
+  const obj = parsed as Record<string, unknown>;
+  // Already restored: report it and leave the bytes (and their mtime) alone.
+  if (Object.keys(obj).length === 0) return { kind: "already-restored", path };
+
+  if (!isSuiteOwnedUnbinding(obj)) {
+    // Root cause, for the log: the binding itself being someone else's beats
+    // "there is a key we did not write" (a foreign `$schema` alongside a real
+    // `[]` unbinding is the extra key, not a live binding). The legacy spelling
+    // is an extra key by this test — pi renames it later, and `guidanceLine`
+    // says so to the user.
+    const reason: UntouchedReason =
+      UNBIND_KEY in obj && !isEmptyBinding(obj[UNBIND_KEY]) ? "binding-not-empty" : "extra-key";
+    return {
+      kind: "untouched",
+      path,
+      reason,
+      manualEdit: guidanceForReadFile(path, obj, reason),
+    };
+  }
+
+  try {
+    writeAtomicPreservingSymlinks(path, "{}");
+  } catch (error) {
+    // The file IS our artefact — that is the only way to reach a write — so the
+    // unbinding really is in there and removing it really is the fix.
+    return {
+      kind: "failed",
+      path,
+      error: messageOf(error),
+      manualEdit: removeOurEntryGuidance(path),
+    };
+  }
+  return { kind: "restored", path, reloadRequired: true };
+}
+
+/** One-line detail for `diag` — path and key included, never the console. */
+function describeRestoreStatus(status: RestoreNativePasteStatus): string {
+  switch (status.kind) {
+    case "missing":
+      return `restoreNativePaste: nothing to restore — ${status.path} does not exist`;
+    case "already-restored":
+      return `restoreNativePaste: already restored — ${status.path} holds no keys (no rewrite)`;
+    case "restored":
+      return (
+        `restoreNativePaste: restored — removed "${UNBIND_KEY}" from ${status.path}, ` +
+        `wrote {} (reloadRequired=${status.reloadRequired})`
+      );
+    case "untouched":
+      return (
+        `restoreNativePaste: untouched (${status.reason}) — ${status.path} was left as-is. ` +
+        status.manualEdit
+      );
+    case "failed":
+      return `restoreNativePaste: failed — ${status.path}: ${status.error}. ${status.manualEdit}`;
+  }
+}
+
+/**
+ * The `session_start` call site: read the setting, restore if asked, and surface
+ * the outcome. Runs from whichever path loaded the package — image-paste's own
+ * `session_start` registration for standalone installs, or meta's composed
+ * `session_start` for the suite — and from each exactly once per session.
+ * Handlers stay registered at the top level of the registering factory, never
+ * nested (AGENTS.md).
+ *
+ * Surfacing rule: the actionable "this file is yours" outcome gets one
+ * `ctx.ui.notify(…, "warning")` **per process** — the guard lives on
+ * `globalThis` (see {@link RESTORE_NOTIFIED_KEY}) because a module-level flag
+ * would be reset by `/reload`. `diag("image-paste", …)` carries the detail on
+ * every outcome and both may fire, but `diag` cannot be the only channel: it is
+ * a no-op unless `PI_ARCHIMEDES_LOG` names a file, so a default install would be
+ * silent while pi's paste stayed dead. No notify at all when `ctx.hasUI` is
+ * false — on ANY outcome, including a successful restore, whose info and
+ * `/reload`-hint texts are UI messages too — and a headless run does not spend
+ * the guard. Nothing here uses
+ * `console.*` (`docs/features/ui.md`, guarded by
+ * `packages/core/src/log-discipline.test.ts`).
+ *
+ * A successful restore goes through the existing reload path so pi re-reads
+ * `keybindings.json`; on a ctx without `reload` the returned status says
+ * `/reload` is required. Never throws — a session start must not fail because a
+ * keybinding file is awkward.
+ */
+export async function runNativePasteRestore(
+  ctx: ExtensionContext,
+): Promise<NativePasteRestoreOutcome> {
+  // Same predicate the shortcut gate reads, so the file restore and the
+  // registration can never disagree about what the user asked for.
+  //
+  // INVARIANT (mirrored at gate 1b of `offerKeybindingFix`): for a given
+  // configuration only one of the two paste-key flows acts — this one runs only
+  // when the suite will NOT claim the key, the offer only when it will. So no
+  // session creates `keybindings.json` and then empties it, and one run cannot
+  // say both "Created …" and "Restored …" about one file. A user who changes the
+  // setting between sessions legitimately gets *Created* first and *Restored*
+  // later: that is the reversible hatch, not the breach this forbids.
+  if (suiteMayClaimPasteKey()) {
+    return { kind: "suppressed" };
+  }
+
+  const status = restoreNativePaste();
+  diag(
+    "image-paste",
+    `[archimedes:restore-native-paste] ${describeRestoreStatus(status)}`,
+  );
+
+  if (status.kind === "untouched" || status.kind === "failed") {
+    // "We did not touch it" — one actionable warning naming the path, spent at
+    // most once per process. What it asks of the user comes from the status
+    // itself (`manualEdit`, i.e. {@link guidanceLine}), because the refusals are
+    // not the same files: only a file that still holds an unbinding of the paste
+    // action has anything to delete, and issue #127 is the warning that used to
+    // order all of them to go look for one.
+    if (ctx.hasUI && claimRestoreNotice()) {
+      const failure =
+        status.kind === "failed" ? `The write failed (${status.error}). ` : "";
+      // `manualEdit` carries the second half of the promise too — that with the
+      // flag off image-paste registers NO paste shortcut — worded per refusal:
+      // "that key does nothing until you do" only where the file really does
+      // leave the key unbound (our `[]`, or pi's old name for it), "pi's own
+      // paste answers that key" where it does not, and "pi is running on its
+      // defaults, check the file" where it cannot be read at all. `describeRestoreStatus`
+      // feeds the SAME `manualEdit` to `diag`, so the log and the warning cannot
+      // tell two stories about one file — asserted, not merely intended, by the
+      // `keybinding-offer.test.ts` case that names the mutant it guards.
+      ctx.ui.notify(
+        `image-paste did not change ${status.path}. ${failure}${status.manualEdit}`,
+        "warning",
+      );
+    }
+    return status;
+  }
+
+  if (status.kind === "restored") {
+    // Last use of ctx: reload() invalidates this extension instance.
+    // `notify: ctx.hasUI` keeps the silence promise for a UI-less ctx: the
+    // restore still runs and `diag` still records it, but no UI message is
+    // pushed at a host that said it has no UI.
+    const reloaded = await reloadAfterKeybindingChange(
+      ctx,
+      RESTORED_NOTIFY,
+      RESTORED_RELOAD_HINT,
+      { notify: ctx.hasUI },
+    );
+    return { ...status, reloadRequired: !reloaded };
+  }
+
+  // "missing" / "already-restored": nothing happened and nothing is asked of
+  // the user, so no notify — the log line above is the record.
+  return status;
+}
+