Guard against duplicate instances stealing the RPC registration

iTerm2 starts a new copy of an AutoLaunch script every time it's launched
(Scripts → AutoLaunch) without stopping the prior one. Each copy registers
the same `remote_paste` RPC, so ⌃V dispatch becomes ambiguous and invocations
get routed to a stale instance and silently dropped — pastes stop working with
nothing in the log, even though iTerm2 reports the script as running.

ensure_single_instance() now pgreps for sibling copies on startup, SIGTERMs
them, and waits for their API connections to close before registering, so
exactly one instance owns the function. The PID-selection logic is split into a
pure sibling_pids() helper with unit tests.

Also add __version__ (1.1), log it on startup, and document the failure mode
in the README troubleshooting section.

Author: jaredatch

README.md

@@ -102,6 +102,7 @@ tail -f ~/Library/Logs/remote_paste.log
 A successful paste writes a line like `paste[-CC]: host=my-server tmux=work image=148293 ok=True`.
 
 - **Pasting inserts literal `0x16`.** The script isn't delivering a real keystroke. Confirm the key binding is set to *Invoke Script Function* with exactly `remote_paste(session_id: id)`, and that the script is running (Scripts → Console).
+- **⌃V does nothing and no new log lines appear.** You likely have more than one copy of the script running, each fighting over the same RPC registration — this happens when you relaunch from Scripts → AutoLaunch without stopping the old copy first. Check with `pgrep -fl remote_paste.py`; you should see exactly one. The script now evicts older copies on startup, so relaunching it once clears the jam.
 - **"No image found in clipboard."** Your clipboard had no image when you pasted. On macOS, Cmd+Shift+Ctrl+4 copies a screenshot to the clipboard; plain Cmd+Shift+4 saves it to a file instead. If `image=0` shows in the log, the image never reached the script. Installing `pngpaste` helps with unusual clipboard formats.
 - **`pngpaste: command not found` in the log.** Harmless. The script falls back to osascript. Install `pngpaste` to silence it.
 - **Image lands in the wrong tmux pane.** remote-paste targets the active pane of the focused window. If you split a window and the focus tracking is off, open an issue.

remote_paste.py

@@ -48,12 +48,21 @@
 import re
 import shlex
 import shutil
+import signal
 import subprocess
 import tempfile
+import time
 import traceback
 
 import iterm2
 
+__version__ = "1.1"
+
+# Marker matched (via pgrep -f) to find sibling copies of this script. iTerm2
+# relaunches AutoLaunch scripts without stopping the prior copy, so duplicates
+# pile up and fight over the same RPC registration — see ensure_single_instance.
+INSTANCE_MARKER = "AutoLaunch/remote_paste.py"
+
 # --------------------------------------------------------------------------- #
 # Configuration
 # --------------------------------------------------------------------------- #
@@ -262,7 +271,7 @@ async def main(connection):
     pngpaste = discover("pngpaste", cfg["pngpaste"],
                         ["/opt/homebrew/bin/pngpaste", "/usr/local/bin/pngpaste"])
     ssh = discover("ssh", cfg["ssh"], ["/usr/bin/ssh"]) or "ssh"
-    log("remote_paste: starting (pngpaste=%s ssh=%s)" % (pngpaste, ssh))
+    log("remote_paste %s: starting (pngpaste=%s ssh=%s)" % (__version__, pngpaste, ssh))
 
     app = await iterm2.async_get_app(connection)
 
@@ -325,5 +334,58 @@ async def remote_paste(session_id):
     await asyncio.Future()  # stay alive so the RPC remains registered
 
 
+def sibling_pids(pgrep_output, me, parent):
+    """PIDs from `pgrep -f` output to terminate: everything but us and our parent.
+
+    The parent is excluded because it's the it2_api_wrapper.sh shell that launched
+    this script — its command line also matches the marker, but killing it would
+    take us down with it.
+    """
+    return [p for p in (int(x) for x in pgrep_output.split() if x.isdigit())
+            if p not in (me, parent)]
+
+
+def ensure_single_instance():
+    """Terminate any other running copies of this script before we register.
+
+    iTerm2 starts a *new* instance every time the script is launched (Scripts →
+    AutoLaunch) without stopping the old one, and each instance registers the same
+    `remote_paste` RPC. Multiple registrations make ⌃V dispatch ambiguous, so
+    invocations get routed to a stale instance and silently dropped. Killing
+    siblings on startup guarantees exactly one owner of the function.
+    """
+    me, parent = os.getpid(), os.getppid()
+    try:
+        out = subprocess.run(["/usr/bin/pgrep", "-f", INSTANCE_MARKER],
+                             capture_output=True, text=True, timeout=5).stdout
+    except Exception:
+        log("singleton: pgrep failed:\n" + traceback.format_exc())
+        return
+    others = sibling_pids(out, me, parent)
+    for pid in others:
+        try:
+            os.kill(pid, signal.SIGTERM)
+            log("singleton: terminated prior instance pid=%d" % pid)
+        except ProcessLookupError:
+            pass
+        except Exception:
+            log("singleton: kill pid=%d failed:\n%s" % (pid, traceback.format_exc()))
+    # Wait briefly for the killed instances' API connections to close so iTerm2
+    # frees the old registration before we claim it.
+    for _ in range(20):
+        if not any(_alive(p) for p in others):
+            break
+        time.sleep(0.05)
+
+
+def _alive(pid):
+    try:
+        os.kill(pid, 0)
+        return True
+    except OSError:
+        return False
+
+
 if __name__ == "__main__":
+    ensure_single_instance()
     iterm2.run_forever(main)

tests/test_detect.py

@@ -89,3 +89,20 @@ def test_remote_tmux_expr_uses_configured_path():
 def test_remote_tmux_expr_probes_when_unset():
     expr = rp.remote_tmux_expr(None)
     assert "command -v tmux" in expr
+
+
+# --- sibling_pids (singleton guard) --------------------------------------- #
+
+def test_sibling_pids_excludes_self_and_parent():
+    # pgrep lists us (10), our wrapper parent (9), and one stale instance (42).
+    assert rp.sibling_pids("9\n10\n42\n", me=10, parent=9) == [42]
+
+def test_sibling_pids_none_to_kill_on_clean_start():
+    # First launch: only this process and its wrapper are present.
+    assert rp.sibling_pids("9\n10\n", me=10, parent=9) == []
+
+def test_sibling_pids_kills_multiple_duplicates():
+    assert rp.sibling_pids("9 10 14899 14913 25459", me=10, parent=9) == [14899, 14913, 25459]
+
+def test_sibling_pids_ignores_non_numeric_noise():
+    assert rp.sibling_pids("10\n\n  \nfoo\n42\n", me=10, parent=9) == [42]