pi-superwhisper-paste 0.1.4 → 0.1.14

package/CHANGELOG.md

@@ -4,6 +4,71 @@ All notable changes to this project will be documented in this file.
 
 This project follows semantic versioning.
 
+## [0.1.14] - 2026-06-05
+
+### Changed
+
+- Re-add `Code` / `Cursor` host processes to the clipboard-owner denylist so editor-hosted clipboard updates are blocked again during debugging.
+
+## [0.1.13] - 2026-06-05
+
+### Fixed
+
+- Remove `Code.exe` / `Cursor.exe` from the terminal-owner denylist so editor-hosted Superwhisper clipboard updates are not blocked just because Pi is running inside Code/Cursor.
+
+## [0.1.12] - 2026-06-05
+
+### Changed
+
+- Add an explicit `v0.1.12` marker to the status text so stale package loads are visible during live debugging.
+
+## [0.1.11] - 2026-06-05
+
+### Fixed
+
+- Broaden the terminal clipboard-owner denylist with `OpenConsole` / explicit `.exe` variants.
+- Surface the last clipboard decision in the Pi status text (`blocked ...`, `... via ...`) so real-machine owner mismatches can be diagnosed quickly.
+
+## [0.1.10] - 2026-06-05
+
+### Fixed
+
+- Fix the Windows PowerShell clipboard-owner probe script so the owner-aware bridge works in real Pi sessions instead of failing on multiline `Add-Type` syntax.
+
+## [0.1.9] - 2026-06-05
+
+### Fixed
+
+- Replace the strict Superwhisper owner allowlist with a terminal-owner denylist so unknown Superwhisper owner names still auto-paste while terminal/CLI clipboard owners stay blocked.
+
+## [0.1.8] - 2026-06-05
+
+### Fixed
+
+- Filter clipboard updates by clipboard-owner process so Pi auto-pastes only when the clipboard owner looks like Superwhisper.
+- Keep local terminal copy suppression as a fallback for forwarded copy shortcuts while blocking mouse/right-click terminal copies via owner filtering.
+
+## [0.1.7] - 2026-06-05
+
+### Fixed
+
+- Suppress auto-paste for a short window after local terminal copy shortcuts so copying inside the active CLI no longer pastes into Pi.
+- Refresh the clipboard baseline after local copy intent so the bridge keeps waiting for the next Superwhisper clipboard update.
+
+## [0.1.6] - 2026-06-04
+
+### Changed
+
+- Added `version:check` PR guard support: package script + `scripts/check-version-bump.mjs`.
+- Added CI verification that publishable changes must bump `package.json` and update `CHANGELOG.md` in the same PR.
+
+### Fixed
+
+- Truncate clipboard text in PowerShell before writing stdout so huge clipboards no longer exceed Node `maxBuffer` on extension load.
+- Treat clipboard read failures (including `maxBuffer`) as empty reads so `session_start` never surfaces as an extension error.
+
+## [0.1.5] - 2026-06-03
+
 ## [0.1.4] - 2026-06-03
 
 ### Changed

package/README.md

@@ -50,6 +50,8 @@ pi install git:github.com/eiei114/pi-superwhisper-paste
 - Default-on after the extension loads.
 - Slash commands: `/sw-paste:on` and `/sw-paste:off`.
 - Windows clipboard polling with active-tab gating.
+- Brief copy-suppression window so local terminal copy actions do not get auto-pasted back into Pi.
+- Clipboard-owner filtering so terminal/CLI-owned clipboard updates stay blocked by default.
 
 See [CHANGELOG.md](CHANGELOG.md) for version history.
 

package/docs/examples.md

@@ -28,6 +28,8 @@ Run these commands inside Pi's input box:
 | `PI_SUPERWHISPER_PASTE` | `on` | Set to `off`, `0`, `false`, or `no` to disable by default. |
 | `PI_SUPERWHISPER_PASTE_INTERVAL_MS` | `800` | Clipboard polling interval. |
 | `PI_SUPERWHISPER_PASTE_MAX_CHARS` | `8000` | Maximum clipboard text length to paste. |
+| `PI_SUPERWHISPER_PASTE_IGNORE_COPY_MS` | `1500` | Ignore clipboard changes briefly after local terminal copy shortcuts. |
+| `PI_SUPERWHISPER_PASTE_OWNER_DENYLIST` | `windowsterminal,...` | Comma-separated clipboard owner process/path substrings blocked from auto-paste. |
 
 ## Expected workflow
 
@@ -40,3 +42,7 @@ Run these commands inside Pi's input box:
 When multiple Pi tabs are open, only the tab that most recently had terminal focus or keyboard input should paste the new clipboard text.
 
 The bridge does not wait for Pi's agent turn to become idle. If Pi is thinking, the active tab should still receive the next Superwhisper clipboard update.
+
+When you copy text inside the active CLI, the bridge now suppresses auto-paste briefly and refreshes the clipboard baseline so the copied text is not inserted into Pi.
+
+The bridge also inspects the Windows clipboard owner and blocks auto-paste when the owner looks like a terminal/CLI app.

package/extensions/index.ts

@@ -6,19 +6,53 @@ import { join } from "node:path";
 import { promisify } from "node:util";
 
 const execFileAsync = promisify(execFile);
+const EXTENSION_VERSION = "0.1.14";
 
 const STATUS_KEY = "superwhisper-paste";
 const DEFAULT_INTERVAL_MS = 800;
 const DEFAULT_MAX_CHARS = 8000;
+const DEFAULT_IGNORE_COPY_MS = 1500;
+const BASELINE_REFRESH_DELAY_MS = 120;
+const DEFAULT_OWNER_DENYLIST = [
+  "windowsterminal",
+  "windowsterminal.exe",
+  "windows terminal",
+  "openconsole",
+  "openconsole.exe",
+  "wezterm",
+  "alacritty",
+  "mintty",
+  "conhost",
+  "cmd.exe",
+  "code",
+  "code.exe",
+  "powershell",
+  "pwsh",
+  "bash",
+  "cursor",
+  "cursor.exe",
+  "wsl",
+];
 const ACTIVE_STATE_FILE = "pi-superwhisper-paste-active.json";
 const FOCUS_IN = "\x1b[I";
 const FOCUS_OUT = "\x1b[O";
 const ENABLE_FOCUS_REPORTING = "\x1b[?1004h";
 const DISABLE_FOCUS_REPORTING = "\x1b[?1004l";
 const INSTANCE_ID = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+const CTRL_C = "\x03";
+const CTRL_INSERT = "\x1b[2;5~";
+const CTRL_SHIFT_INSERT = "\x1b[2;6~";
+const CTRL_SHIFT_C_CSI_U = "\x1b[99;6u";
+const CTRL_SHIFT_UPPER_C_CSI_U = "\x1b[67;6u";
 
 type BridgeMode = "off" | "on";
 
+type ClipboardSnapshot = {
+  text?: string;
+  ownerProcessName?: string;
+  ownerProcessPath?: string;
+};
+
 type PiEditorUi = {
   setStatus(key: string, value: string | undefined): void;
   notify(message: string, level?: "info" | "warning" | "error" | "success"): void;
@@ -42,11 +76,13 @@ type SessionHandle = {
 type BridgeState = {
   mode: BridgeMode;
   interval?: NodeJS.Timeout;
+  baselineRefreshTimeout?: NodeJS.Timeout;
   generation: number;
   session?: SessionHandle;
   inFlightGeneration?: number;
   activatingGeneration?: number;
   terminalFocused: boolean;
+  suppressPasteUntil?: number;
   unsubscribeTerminalInput?: () => void;
   lastClipboard?: string;
   lastPasted?: string;
@@ -59,33 +95,70 @@ const state: BridgeState = {
   terminalFocused: true,
 };
 
+/** Resolves bridge on/off from `PI_SUPERWHISPER_PASTE` (default on). */
 function defaultMode(): BridgeMode {
   const raw = (process.env.PI_SUPERWHISPER_PASTE ?? "on").trim().toLowerCase();
   return ["0", "false", "no", "off"].includes(raw) ? "off" : "on";
 }
 
+/** Poll interval from env or default. */
 function intervalMs(): number {
   const parsed = Number(process.env.PI_SUPERWHISPER_PASTE_INTERVAL_MS);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_INTERVAL_MS;
 }
 
+/** Max pasted characters from env or default. */
 function maxChars(): number {
   const parsed = Number(process.env.PI_SUPERWHISPER_PASTE_MAX_CHARS);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_CHARS;
 }
 
+/** Ignore clipboard changes briefly after local copy shortcuts. */
+function ignoreCopyMs(): number {
+  const parsed = Number(process.env.PI_SUPERWHISPER_PASTE_IGNORE_COPY_MS);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_IGNORE_COPY_MS;
+}
+
+/** Process-name/path substrings denied from triggering auto-paste. */
+function ownerDenylist(): string[] {
+  const raw = process.env.PI_SUPERWHISPER_PASTE_OWNER_DENYLIST;
+  if (!raw) return DEFAULT_OWNER_DENYLIST;
+
+  const tokens = raw
+    .split(",")
+    .map((token) => token.trim().toLowerCase())
+    .filter(Boolean);
+
+  return tokens.length > 0 ? tokens : DEFAULT_OWNER_DENYLIST;
+}
+
+/** Status bar label for the paste bridge. */
 function statusText(): string | undefined {
   if (state.mode === "off") return undefined;
   const focusText = state.terminalFocused ? "active" : "standby";
   return state.lastPasteSummary
-    ? `SW paste: ${focusText} (${state.lastPasteSummary})`
-    : `SW paste: ${focusText}`;
+    ? `SW paste v${EXTENSION_VERSION}: ${focusText} (${state.lastPasteSummary})`
+    : `SW paste v${EXTENSION_VERSION}: ${focusText}`;
+}
+
+/** Short display name for clipboard owner debugging. */
+function clipboardOwnerSummary(snapshot: ClipboardSnapshot): string {
+  const name = snapshot.ownerProcessName?.trim();
+  if (name) return name;
+
+  const rawPath = snapshot.ownerProcessPath?.trim();
+  if (!rawPath) return "unknown";
+
+  const segments = rawPath.split(/[\\/]/).filter(Boolean);
+  return segments.at(-1) ?? rawPath;
 }
 
+/** True when `ctx`/`generation` still match the active Pi session. */
 function isCurrentSession(ctx: PiRuntimeContext, generation: number): boolean {
   return state.session?.generation === generation && state.session.ctx === ctx;
 }
 
+/** Runs a UI callback only for the current session; swallows stale-ctx errors. */
 function safeWithCurrentUi(
   ctx: PiRuntimeContext,
   generation: number,
@@ -106,12 +179,14 @@ function safeWithCurrentUi(
   }
 }
 
+/** Updates Pi status bar when session is current. */
 function setStatus(ctx: PiRuntimeContext, generation: number): boolean {
   return safeWithCurrentUi(ctx, generation, (ui) => {
     ui.setStatus(STATUS_KEY, statusText());
   });
 }
 
+/** Shows a Pi notification when session is current. */
 function notify(
   ctx: PiRuntimeContext,
   generation: number,
@@ -123,12 +198,14 @@ function notify(
   });
 }
 
+/** Pastes text into the editor when session is current. */
 function pasteToEditor(ctx: PiRuntimeContext, generation: number, text: string): boolean {
   return safeWithCurrentUi(ctx, generation, (ui) => {
     ui.pasteToEditor(text);
   });
 }
 
+/** Reads editor text when session is current. */
 function getEditorText(ctx: PiRuntimeContext, generation: number): string | undefined {
   if (!isCurrentSession(ctx, generation)) return undefined;
 
@@ -141,6 +218,7 @@ function getEditorText(ctx: PiRuntimeContext, generation: number): string | unde
   }
 }
 
+/** Records last paste and refreshes status after insert. */
 function markPasted(ctx: PiRuntimeContext, generation: number, text: string): void {
   if (!isCurrentSession(ctx, generation)) return;
   state.lastPasted = text;
@@ -149,31 +227,85 @@ function markPasted(ctx: PiRuntimeContext, generation: number, text: string): vo
   setStatus(ctx, generation);
 }
 
-async function readClipboardText(): Promise<string | undefined> {
-  const script = [
+/** Builds a PowerShell command that reads clipboard text truncated to `limit` characters. */
+function clipboardPowerShellScript(limit: number): string {
+  return [
     "[Console]::OutputEncoding = [System.Text.Encoding]::UTF8",
+    "$signature = @\"",
+    "using System;",
+    "using System.Runtime.InteropServices;",
+    "public static class ClipboardOwnerNative {",
+    "  [DllImport(\"user32.dll\")] public static extern IntPtr GetClipboardOwner();",
+    "  [DllImport(\"user32.dll\")] public static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint lpdwProcessId);",
+    "}",
+    "\"@",
+    "Add-Type -TypeDefinition $signature -ErrorAction SilentlyContinue",
+    `$limit = ${limit}`,
     "$text = Get-Clipboard -Raw -Format Text -ErrorAction SilentlyContinue",
-    "if ($null -ne $text) { [Console]::Out.Write($text) }",
-  ].join("; ");
-
-  const result = await execFileAsync(
-    "powershell.exe",
-    ["-NoProfile", "-Command", script],
-    {
-      encoding: "utf8",
-      maxBuffer: maxChars() * 4,
-      timeout: 2500,
-      windowsHide: true,
-    },
-  );
+    "$ownerProcessName = $null",
+    "$ownerProcessPath = $null",
+    "try {",
+    "  $ownerWindow = [ClipboardOwnerNative]::GetClipboardOwner()",
+    "  if ($ownerWindow -ne [IntPtr]::Zero) {",
+    "    $ownerPid = 0",
+    "    [void][ClipboardOwnerNative]::GetWindowThreadProcessId($ownerWindow, [ref]$ownerPid)",
+    "    if ($ownerPid -gt 0) {",
+    "      $ownerProcess = Get-Process -Id $ownerPid -ErrorAction SilentlyContinue",
+    "      if ($null -ne $ownerProcess) {",
+    "        $ownerProcessName = $ownerProcess.ProcessName",
+    "        $ownerProcessPath = $ownerProcess.Path",
+    "      }",
+    "    }",
+    "  }",
+    "} catch {}",
+    "if ($null -ne $text) {",
+    "  if ($text.Length -gt $limit) { $text = $text.Substring(0, $limit) }",
+    "}",
+    "$result = @{ text = $text; ownerProcessName = $ownerProcessName; ownerProcessPath = $ownerProcessPath }",
+    "[Console]::Out.Write(($result | ConvertTo-Json -Compress))",
+  ].join("\n");
+}
+
+/** Reads clipboard text and owner metadata via PowerShell. */
+async function readClipboardSnapshot(): Promise<ClipboardSnapshot | undefined> {
+  const limit = maxChars();
 
-  return typeof result.stdout === "string" ? result.stdout : undefined;
+  try {
+    const result = await execFileAsync(
+      "powershell.exe",
+      ["-NoProfile", "-Command", clipboardPowerShellScript(limit)],
+      {
+        encoding: "utf8",
+        maxBuffer: limit * 4 + 1024,
+        timeout: 2500,
+        windowsHide: true,
+      },
+    );
+
+    const stdout = typeof result.stdout === "string" ? result.stdout : undefined;
+    if (!stdout) return undefined;
+
+    const snapshot = JSON.parse(stdout) as ClipboardSnapshot;
+    const text = typeof snapshot.text === "string" ? snapshot.text : undefined;
+    return {
+      text: text && text.length > limit ? text.slice(0, limit) : text,
+      ownerProcessName:
+        typeof snapshot.ownerProcessName === "string" ? snapshot.ownerProcessName : undefined,
+      ownerProcessPath:
+        typeof snapshot.ownerProcessPath === "string" ? snapshot.ownerProcessPath : undefined,
+    };
+  } catch {
+    // Oversized clipboard, PowerShell failure, or maxBuffer must not break extension load.
+    return undefined;
+  }
 }
 
+/** Temp file path for cross-tab active-instance claim. */
 function activeStatePath(): string {
   return join(tmpdir(), ACTIVE_STATE_FILE);
 }
 
+/** Writes this Pi instance as the active tab for paste gating. */
 async function claimActiveTab(): Promise<void> {
   const claim = {
     instanceId: INSTANCE_ID,
@@ -188,6 +320,7 @@ async function claimActiveTab(): Promise<void> {
   }
 }
 
+/** True when this instance owns the active-tab claim and has focus. */
 async function isActiveTab(): Promise<boolean> {
   if (!state.terminalFocused) return false;
 
@@ -201,15 +334,32 @@ async function isActiveTab(): Promise<boolean> {
   }
 }
 
+/** Seeds `lastClipboard` without pasting (focus/tab activation). */
 async function refreshClipboardBaseline(
   ctx: PiRuntimeContext,
   generation: number,
 ): Promise<void> {
-  const text = await readClipboardText();
+  const text = (await readClipboardSnapshot())?.text;
   if (!isCurrentSession(ctx, generation)) return;
   if (text !== undefined) state.lastClipboard = text;
 }
 
+/** Best-effort delayed baseline refresh after local copy shortcuts. */
+function scheduleClipboardBaselineRefresh(ctx: PiRuntimeContext, generation: number): void {
+  if (!isCurrentSession(ctx, generation)) return;
+
+  if (state.baselineRefreshTimeout) {
+    clearTimeout(state.baselineRefreshTimeout);
+    state.baselineRefreshTimeout = undefined;
+  }
+
+  state.baselineRefreshTimeout = setTimeout(() => {
+    state.baselineRefreshTimeout = undefined;
+    if (isCurrentSession(ctx, generation)) void refreshClipboardBaseline(ctx, generation);
+  }, BASELINE_REFRESH_DELAY_MS);
+}
+
+/** Marks tab focused, refreshes clipboard baseline, claims active tab. */
 async function activateTab(ctx: PiRuntimeContext, generation: number): Promise<void> {
   if (!isCurrentSession(ctx, generation) || state.activatingGeneration !== undefined) return;
 
@@ -227,6 +377,7 @@ async function activateTab(ctx: PiRuntimeContext, generation: number): Promise<v
   }
 }
 
+/** Claims active tab when user types in the terminal. */
 async function markActiveFromInput(ctx: PiRuntimeContext, generation: number): Promise<void> {
   if (!isCurrentSession(ctx, generation)) return;
   state.terminalFocused = true;
@@ -235,6 +386,39 @@ async function markActiveFromInput(ctx: PiRuntimeContext, generation: number): P
   setStatus(ctx, generation);
 }
 
+/** True while recent local copy shortcuts should suppress bridge pastes. */
+function shouldSuppressPasteForRecentCopy(): boolean {
+  return (state.suppressPasteUntil ?? 0) > Date.now();
+}
+
+/** Detects common terminal copy shortcuts forwarded to Pi. */
+function isLocalCopyShortcut(data: string): boolean {
+  return [
+    CTRL_C,
+    CTRL_INSERT,
+    CTRL_SHIFT_INSERT,
+    CTRL_SHIFT_C_CSI_U,
+    CTRL_SHIFT_UPPER_C_CSI_U,
+  ].includes(data);
+}
+
+/** Suppresses auto-paste briefly after local terminal copy intent. */
+function suppressPasteAfterLocalCopy(ctx: PiRuntimeContext, generation: number): void {
+  if (!isCurrentSession(ctx, generation)) return;
+  state.suppressPasteUntil = Date.now() + ignoreCopyMs();
+  state.lastPasteSummary = "blocked recent copy";
+  void markActiveFromInput(ctx, generation);
+  scheduleClipboardBaselineRefresh(ctx, generation);
+}
+
+/** True when clipboard owner metadata does not look like a terminal copy source. */
+function shouldAcceptClipboardSource(snapshot: ClipboardSnapshot): boolean {
+  const owner = `${snapshot.ownerProcessName ?? ""}\n${snapshot.ownerProcessPath ?? ""}`.toLowerCase();
+  if (!owner.trim()) return true;
+  return !ownerDenylist().some((token) => owner.includes(token));
+}
+
+/** Whether clipboard text should be auto-pasted into the editor. */
 function shouldPaste(text: string, ctx: PiRuntimeContext, generation: number): boolean {
   if (!text.trim()) return false;
   if (text.length > maxChars()) return false;
@@ -247,6 +431,7 @@ function shouldPaste(text: string, ctx: PiRuntimeContext, generation: number): b
   return true;
 }
 
+/** Poll handler: paste new clipboard text when gates pass. */
 async function pasteClipboardChange(ctx: PiRuntimeContext, generation: number): Promise<void> {
   if (!isCurrentSession(ctx, generation)) return;
   if (
@@ -262,17 +447,35 @@ async function pasteClipboardChange(ctx: PiRuntimeContext, generation: number):
 
   state.inFlightGeneration = generation;
   try {
-    const text = await readClipboardText();
+    const snapshot = await readClipboardSnapshot();
+    const text = snapshot?.text;
     if (!isCurrentSession(ctx, generation)) return;
     if (text === undefined || text === state.lastClipboard) return;
 
     state.lastClipboard = text;
+    if (!snapshot) {
+      state.lastPasteSummary = "clipboard read failed";
+      setStatus(ctx, generation);
+      return;
+    }
+    if (!shouldAcceptClipboardSource(snapshot)) {
+      state.lastPasteSummary = `blocked ${clipboardOwnerSummary(snapshot)}`;
+      setStatus(ctx, generation);
+      return;
+    }
+    if (shouldSuppressPasteForRecentCopy()) {
+      state.lastPasteSummary = `blocked recent copy (${clipboardOwnerSummary(snapshot)})`;
+      setStatus(ctx, generation);
+      return;
+    }
     if (!shouldPaste(text, ctx, generation)) return;
     if (!(await isActiveTab())) return;
     if (!isCurrentSession(ctx, generation)) return;
 
     if (!pasteToEditor(ctx, generation, text)) return;
     markPasted(ctx, generation, text);
+    state.lastPasteSummary = `${text.length} chars via ${clipboardOwnerSummary(snapshot)}`;
+    setStatus(ctx, generation);
   } catch {
     // Clipboard polling should stay quiet while the user is typing.
   } finally {
@@ -280,6 +483,7 @@ async function pasteClipboardChange(ctx: PiRuntimeContext, generation: number):
   }
 }
 
+/** Enables terminal focus reporting and input hooks for this session. */
 function setupTerminalFocusTracking(ctx: PiRuntimeContext, generation: number): void {
   if (!isCurrentSession(ctx, generation)) return;
   if (state.unsubscribeTerminalInput) return;
@@ -306,6 +510,11 @@ function setupTerminalFocusTracking(ctx: PiRuntimeContext, generation: number):
         return { consume: true };
       }
 
+      if (isLocalCopyShortcut(data)) {
+        suppressPasteAfterLocalCopy(ctx, generation);
+        return undefined;
+      }
+
       if (data.length > 0) {
         void markActiveFromInput(ctx, generation);
       }
@@ -315,6 +524,7 @@ function setupTerminalFocusTracking(ctx: PiRuntimeContext, generation: number):
   });
 }
 
+/** Disables focus reporting and removes terminal input subscription. */
 function teardownTerminalFocusTracking(): void {
   try {
     state.unsubscribeTerminalInput?.();
@@ -330,16 +540,23 @@ function teardownTerminalFocusTracking(): void {
   }
 }
 
+/** Clears poll interval and terminal hooks for the current session. */
 function teardownSessionResources(): void {
   if (state.interval) {
     clearInterval(state.interval);
     state.interval = undefined;
   }
+  if (state.baselineRefreshTimeout) {
+    clearTimeout(state.baselineRefreshTimeout);
+    state.baselineRefreshTimeout = undefined;
+  }
   teardownTerminalFocusTracking();
   state.inFlightGeneration = undefined;
   state.activatingGeneration = undefined;
+  state.suppressPasteUntil = undefined;
 }
 
+/** Starts a new session generation and tears down the previous one. */
 function beginSession(ctx: PiRuntimeContext): number {
   teardownSessionResources();
   const generation = state.generation + 1;
@@ -348,17 +565,20 @@ function beginSession(ctx: PiRuntimeContext): number {
   return generation;
 }
 
+/** Returns current session generation, beginning one if needed. */
 function ensureCurrentSession(ctx: PiRuntimeContext): number {
   if (state.session?.ctx === ctx) return state.session.generation;
   return beginSession(ctx);
 }
 
+/** Invalidates the current session and releases resources. */
 function endSession(): void {
   teardownSessionResources();
   state.generation += 1;
   state.session = undefined;
 }
 
+/** Starts clipboard polling and focus tracking when mode is on. */
 function ensurePolling(ctx: PiRuntimeContext, generation: number): void {
   if (!isCurrentSession(ctx, generation)) return;
 
@@ -371,21 +591,24 @@ function ensurePolling(ctx: PiRuntimeContext, generation: number): void {
   }, intervalMs());
 }
 
+/** Stops polling and clears bridge status. */
 function stopPolling(ctx: PiRuntimeContext, generation: number): void {
   teardownSessionResources();
   state.mode = "off";
   setStatus(ctx, generation);
 }
 
+/** Baselines clipboard then starts polling (session_start path). */
 async function startPolling(ctx: PiRuntimeContext, generation: number): Promise<void> {
-  const text = await readClipboardText();
+  const text = (await readClipboardSnapshot())?.text;
   if (!isCurrentSession(ctx, generation)) return;
   state.lastClipboard = text;
   ensurePolling(ctx, generation);
 }
 
+/** Enables bridge mode and notifies the user. */
 async function arm(ctx: PiRuntimeContext, generation: number): Promise<void> {
-  const text = await readClipboardText();
+  const text = (await readClipboardSnapshot())?.text;
   if (!isCurrentSession(ctx, generation)) return;
   state.lastClipboard = text;
   state.mode = "on";
@@ -393,12 +616,14 @@ async function arm(ctx: PiRuntimeContext, generation: number): Promise<void> {
   notify(ctx, generation, "Superwhisper paste bridge: enabled", "info");
 }
 
+/** Parses `/sw-paste:on` or `/sw-paste:off` from user input. */
 function parseControlCommand(text: string): BridgeMode | undefined {
   const match = text.trim().match(/^\/sw-paste:(on|off)$/i);
   if (!match) return undefined;
   return match[1].toLowerCase() as BridgeMode;
 }
 
+/** Applies on/off control command for the current session. */
 async function runControlAction(
   action: BridgeMode,
   ctx: PiRuntimeContext,
@@ -413,6 +638,7 @@ async function runControlAction(
   notify(ctx, generation, "Superwhisper paste bridge: disabled", "info");
 }
 
+/** Pi extension entry: Superwhisper clipboard bridge for Windows. */
 export default function superwhisperPaste(pi: ExtensionAPI) {
   pi.registerCommand("sw-paste:on", {
     description: "Enable the Superwhisper clipboard paste bridge",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-superwhisper-paste",
-  "version": "0.1.4",
+  "version": "0.1.14",
   "description": "Superwhisper clipboard bridge for Pi on Windows.",
   "type": "module",
   "license": "MIT",
@@ -37,7 +37,8 @@
     "typecheck": "tsc --noEmit",
     "test": "node --test tests/*.test.mjs",
     "ci": "npm run typecheck && npm test && npm run pack:check",
-    "pack:check": "npm pack --dry-run"
+    "pack:check": "npm pack --dry-run",
+    "version:check": "node scripts/check-version-bump.mjs"
   },
   "pi": {
     "extensions": [
@@ -56,7 +57,7 @@
     "@earendil-works/pi-ai": "latest",
     "@earendil-works/pi-coding-agent": "latest",
     "@earendil-works/pi-tui": "latest",
-    "@types/node": "^22.0.0",
+    "@types/node": "^25.9.1",
     "typescript": "^6.0.3"
   }
 }