rf-mcp 0.34.0.dev4__tar.gz → 0.34.0.dev5__tar.gz

{rf_mcp-0.34.0.dev4 → rf_mcp-0.34.0.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rf-mcp
-Version: 0.34.0.dev4
+Version: 0.34.0.dev5
 Summary: Robot Framework MCP Server - Natural Language Test Automation Bridge
 Project-URL: Homepage, https://github.com/manykarim/rf-mcp
 Project-URL: Repository, https://github.com/manykarim/rf-mcp
@@ -21,9 +21,11 @@ Requires-Dist: tomlkit>=0.12.0
 Provides-Extra: all
 Requires-Dist: django<5.0,>=4.2; extra == 'all'
 Requires-Dist: model2vec>=0.4.0; extra == 'all'
+Requires-Dist: platynui-cli==0.13.0.dev2; (python_version >= '3.12') and extra == 'all'
 Requires-Dist: robotframework-appiumlibrary; extra == 'all'
 Requires-Dist: robotframework-browser; extra == 'all'
 Requires-Dist: robotframework-databaselibrary; extra == 'all'
+Requires-Dist: robotframework-platynui==0.13.0.dev2; (python_version >= '3.12') and extra == 'all'
 Requires-Dist: robotframework-requests; extra == 'all'
 Requires-Dist: robotframework-seleniumlibrary; extra == 'all'
 Requires-Dist: sqlite-vec>=0.1.6; extra == 'all'
@@ -228,7 +230,7 @@ uv pip install --pre rf-mcp[desktop]  # PlatynUI new-core (Rust) native desktop
 uv pip install rf-mcp[frontend]  # Django-based web frontend dashboard
 uv pip install rf-mcp[memory]    # Persistent semantic memory (sqlite-vec + model2vec)
 uv pip install rf-mcp[semantic]  # Sentence-transformers for find_keywords embedding ranking
-uv pip install rf-mcp[all]       # All optional Robot Framework libraries (desktop is separate — prerelease/3.12+)
+uv pip install rf-mcp[all]       # All optional Robot Framework libraries (includes desktop on Python 3.12+)
 
 # Alternatively, add to an existing uv project
 uv init

{rf_mcp-0.34.0.dev4 → rf_mcp-0.34.0.dev5}/README.md

@@ -171,7 +171,7 @@ uv pip install --pre rf-mcp[desktop]  # PlatynUI new-core (Rust) native desktop
 uv pip install rf-mcp[frontend]  # Django-based web frontend dashboard
 uv pip install rf-mcp[memory]    # Persistent semantic memory (sqlite-vec + model2vec)
 uv pip install rf-mcp[semantic]  # Sentence-transformers for find_keywords embedding ranking
-uv pip install rf-mcp[all]       # All optional Robot Framework libraries (desktop is separate — prerelease/3.12+)
+uv pip install rf-mcp[all]       # All optional Robot Framework libraries (includes desktop on Python 3.12+)
 
 # Alternatively, add to an existing uv project
 uv init

{rf_mcp-0.34.0.dev4 → rf_mcp-0.34.0.dev5}/pyproject.toml

@@ -4,7 +4,10 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rf-mcp"
-version = "0.34.0.dev4"
+# 0.34.0.dev5: harden-platynui-stuck-key-release — extend the platynui-windows-runtime
+# stuck-key net from modifiers-only to a tracked held-key registry (releases
+# non-modifier keys too) plus persisted-state recovery across hard process kills.
+version = "0.34.0.dev5"
 description = "Robot Framework MCP Server - Natural Language Test Automation Bridge"
 authors = [{ name = "Many Kasiriha" }]
 license = { text = "Apache-2.0" }
@@ -65,6 +68,12 @@ all = [
     "sqlite-vec>=0.1.6",
     "model2vec>=0.4.0",
     "tiktoken>=0.7.0",
+    # Desktop automation is part of [all]. Referenced as a self-extra so the
+    # PlatynUI pins stay defined in exactly one place (see `desktop` above) —
+    # bumping them there is enough. The `python_version >= "3.12"` markers ride
+    # along, so on 3.10/3.11 this contributes nothing and [all] still resolves.
+    # The exact-pinned prerelease is accepted without a global --pre.
+    "rf-mcp[desktop]",
 ]
 # NOTE: dev tooling lives in [dependency-groups].dev (PEP 735), which is what
 # `uv sync` / CI use. The former [project.optional-dependencies].dev extra was

{rf_mcp-0.34.0.dev4 → rf_mcp-0.34.0.dev5}/src/robotmcp/components/execution/desktop_guidance.py

@@ -30,6 +30,7 @@ _LOCATOR_CRIB: List[str] = [
     "Launch the app first (Process.Start Process), then Query for its control:Frame before acting.",
     "Read a value back with Get Attribute on the scoped node; GTK text views expose native:Text.CharacterCount (not live text content).",
     "Take Screenshot signature is (descriptor, filename, rect) — the FIRST positional is a node descriptor, not a filename; pass filename= for a path.",
+    "Prefer the atomic 'Keyboard Type' (self-contained press+release) for shortcuts, e.g. Keyboard Type  <descriptor>  <Ctrl+A>. A bare 'Keyboard Press' sends key-DOWN ONLY and MUST be paired with 'Keyboard Release' — an unpaired Press (esp. a non-modifier like a letter/F-key/Escape) leaves a key physically held on the OS.",
     "For the full locator cookbook call get_locator_guidance (topic defaults to the desktop/PlatynUI chapter).",
 ]
 

{rf_mcp-0.34.0.dev4 → rf_mcp-0.34.0.dev5}/src/robotmcp/components/execution/keyword_executor.py

@@ -1914,15 +1914,22 @@ class KeywordExecutor:
         # causing it to go to stderr instead of the MCP transport.
         # The lock also prevents concurrent Selenium WebDriver access.
         async with self._execution_lock:
-            # F16 (change: fix-platynui-windows-runtime): a desktop keyboard
-            # keyword that raises or returns failure may have been killed
-            # mid-chord, leaving a modifier physically held at the OS level
-            # (the operator's keyboard wedged until reboot). Release all
-            # modifiers on failure/exception. A SUCCESSFUL Keyboard Press
-            # legitimately holds a key for a later Keyboard Release, so we do
-            # NOT release on success. release_all_modifiers() is a no-op when
-            # nothing is held.
+            # F16 + harden-platynui-stuck-key-release: a desktop keyboard keyword
+            # that raises or returns failure may have been killed mid-chord,
+            # leaving a key physically held at the OS level (the operator's
+            # keyboard wedged). We track the EXACT keys held (incl. non-modifiers)
+            # so teardown/failure/exit release precisely those. A SUCCESSFUL
+            # Keyboard Press legitimately holds a key for a later Keyboard
+            # Release, so we do NOT release on success — but we DO record it.
             _kbd = self._is_desktop_keyboard_keyword(session, keyword)
+            _kbd_kind, _kbd_seq = (
+                self._desktop_keyboard_op(keyword, arguments) if _kbd else (None, None)
+            )
+            # Record intended-held keys BEFORE dispatch so a kill mid-call is
+            # covered by the persisted state file (Press holds; Type holds then
+            # releases within the same call).
+            if _kbd_kind in ("press", "type") and _kbd_seq:
+                self._record_pressed_keys(_kbd_seq)
             try:
                 result = await self._execute_keyword_serialized(
                     session, keyword, arguments, browser_library_manager,
@@ -1939,8 +1946,9 @@ class KeywordExecutor:
                 # dispatches). keyboard_release is a fast input dispatch, not a
                 # tree query, so the brief on-loop cost is acceptable.
                 if _kbd:
-                    self._release_desktop_modifiers()
+                    self._release_desktop_keys()
                 raise
+            _released_here = False
             if (
                 _kbd
                 and isinstance(result, dict)
@@ -1952,28 +1960,86 @@ class KeywordExecutor:
                 and not self._is_steering_downgrade(result)
             ):
                 # F4: offload the release off the event loop on the normal
-                # failure-return path (no cancellation concern here).
-                await asyncio.to_thread(self._release_desktop_modifiers)
-                # F16 steering (wording only): point the agent at the atomic
-                # Keyboard Type, which cannot leave a key held.
+                # failure-return path (no cancellation concern here). Releases
+                # the exact tracked held set (incl. non-modifiers) + clears state.
+                await asyncio.to_thread(self._release_desktop_keys)
+                _released_here = True
+                # Steering: point the agent at the atomic Keyboard Type, which
+                # cannot leave a key held.
                 try:
                     hints = result.setdefault("hints", [])
                     if isinstance(hints, list):
                         hints.append({
                             "type": "platynui_keyboard_release_safety",
                             "message": (
-                                "Released all keyboard modifiers after this "
-                                "keyboard keyword failed. Prefer the atomic "
-                                "'Keyboard Type <Ctrl+A>' (self-contained "
+                                "Released all held keyboard keys (including any "
+                                "non-modifier such as a letter/F-key/Escape) "
+                                "after this keyboard keyword failed. Prefer the "
+                                "atomic 'Keyboard Type <Ctrl+A>' (self-contained "
                                 "press+release) over a bare 'Keyboard Press', "
-                                "which sends key-DOWN only and must be paired "
+                                "which sends key-DOWN only and MUST be paired "
                                 "with 'Keyboard Release'."
                             ),
                         })
                 except Exception:  # pragma: no cover - defensive
                     pass
+            # On a SUCCESSFUL Keyboard Type / Keyboard Release, the paired key-UP
+            # already happened — clear those keys from the registry. (Press keeps
+            # its recorded keys held until an explicit Keyboard Release.)
+            if not _released_here and _kbd_kind in ("type", "release") and _kbd_seq:
+                self._record_released_keys(_kbd_seq)
             return result
 
+    @staticmethod
+    def _desktop_keyboard_op(keyword, arguments):
+        """Return ``(kind, sequence)`` for a desktop keyboard keyword, where
+        kind is ``"press"``/``"type"``/``"release"`` and sequence is the key
+        text argument (2nd positional, or a ``text=`` named arg). Non-raising;
+        returns ``(None, None)`` when it cannot classify. change:
+        harden-platynui-stuck-key-release."""
+        try:
+            norm = str(keyword or "").lower().rsplit(".", 1)[-1].strip()
+            kind = {
+                "keyboard press": "press",
+                "keyboard type": "type",
+                "keyboard release": "release",
+            }.get(norm)
+            if kind is None:
+                return (None, None)
+            seq = None
+            args = list(arguments or [])
+            for a in args:
+                if isinstance(a, str) and a.startswith("text="):
+                    seq = a[len("text="):]
+                    break
+            if seq is None and len(args) >= 2:
+                seq = args[1]
+            return (kind, seq)
+        except Exception:  # pragma: no cover - defensive
+            return (None, None)
+
+    @staticmethod
+    def _record_pressed_keys(sequence) -> None:
+        """Record keys a desktop Press/Type is about to hold. Never raises.
+        change: harden-platynui-stuck-key-release."""
+        try:
+            from robotmcp.plugins.builtin.platynui_plugin import record_pressed_keys
+
+            record_pressed_keys(sequence)
+        except Exception as exc:  # pragma: no cover - defensive
+            logger.debug("record_pressed_keys failed: %s", exc)
+
+    @staticmethod
+    def _record_released_keys(sequence) -> None:
+        """Remove keys released by a desktop Release/Type from the registry.
+        Never raises. change: harden-platynui-stuck-key-release."""
+        try:
+            from robotmcp.plugins.builtin.platynui_plugin import record_released_keys
+
+            record_released_keys(sequence)
+        except Exception as exc:  # pragma: no cover - defensive
+            logger.debug("record_released_keys failed: %s", exc)
+
     @staticmethod
     def _is_steering_downgrade(result: dict) -> bool:
         """True when a desktop keyword's success was flipped to failure by the
@@ -1993,17 +2059,19 @@ class KeywordExecutor:
         return bool(result.get("steering_confidence") == SC_CONTRADICTED)
 
     @staticmethod
-    def _release_desktop_modifiers() -> None:
-        """Best-effort release of all held keyboard modifiers via the PlatynUI
-        runtime (change: fix-platynui-windows-runtime, F16). Never raises."""
+    def _release_desktop_keys() -> None:
+        """Best-effort release of the EXACT tracked held-key set (incl.
+        non-modifiers) via the PlatynUI runtime, clearing the registry + state
+        file. Falls back to a modifier blast internally. Never raises.
+        change: harden-platynui-stuck-key-release."""
         try:
             from robotmcp.plugins.builtin.platynui_plugin import (
-                release_all_modifiers,
+                release_tracked_keys,
             )
 
-            release_all_modifiers()
+            release_tracked_keys()
         except Exception as exc:  # pragma: no cover - defensive
-            logger.debug("desktop modifier release failed: %s", exc)
+            logger.debug("desktop key release failed: %s", exc)
 
     async def _execute_keyword_serialized(
         self,

{rf_mcp-0.34.0.dev4 → rf_mcp-0.34.0.dev5}/src/robotmcp/plugins/builtin/platynui_plugin.py

@@ -173,6 +173,21 @@ _RELEASE_ALL_SEQUENCE = "<LCtrl+RCtrl+LAlt+RAlt+AltGr+LShift+RShift+LWin+RWin>"
 # bind (guarded under _RUNTIME_LOCK), so a killed process still releases keys.
 _RELEASE_HANDLERS_REGISTERED = False
 
+# --- Held-key registry (change: harden-platynui-stuck-key-release) -----------
+#
+# The modifiers-only F16 blast (_RELEASE_ALL_SEQUENCE) cannot lift a stuck
+# NON-modifier key (a bare ``Keyboard Press A``/``<F12>``/``<Escape>`` that was
+# never released). The registry records the EXACT keys rf-mcp is holding so the
+# teardown/failure/exit paths release precisely those, and it is mirrored to a
+# per-PID state file so a HARD kill (SIGKILL/TerminateProcess — which run
+# neither atexit nor SIGTERM) is recovered by the next desktop session start.
+_HELD_KEYS: set[str] = set()
+_HELD_KEYS_LOCK = threading.RLock()
+# Subdir under the OS temp dir holding ``held_<pid>.json`` files. A live process
+# only ever replays a file owned by a DEAD pid, so a concurrent healthy session
+# is never robbed of a key it is deliberately holding.
+_HELD_KEYS_DIRNAME = "robotmcp_platynui_held_keys"
+
 
 def runtime_unavailable_reason() -> Optional[str]:
     """Classify why the PlatynUI runtime is unavailable, or None when it is
@@ -270,6 +285,259 @@ def release_all_modifiers() -> bool:
         return False
 
 
+# --- Held-key registry: normalize / record / release / recover --------------
+#
+# change: harden-platynui-stuck-key-release.
+
+
+def _normalize_key_tokens(sequence: Optional[str]) -> list[str]:
+    """Parse a PlatynUI key sequence into the individual key tokens that a
+    ``Keyboard Press`` of that sequence leaves HELD (key-DOWN, no key-UP).
+
+    Best-effort and never raises. ``<Ctrl+A>`` -> ``["Ctrl", "A"]``; ``<F12>``
+    -> ``["F12"]``; a bare ``A`` -> ``["A"]``; literal text ``hi`` ->
+    ``["h", "i"]``. Bracketed groups split on ``+``; unbracketed characters
+    each become their own token. Whitespace and empty tokens are dropped.
+    """
+    tokens: list[str] = []
+    if not sequence:
+        return tokens
+    try:
+        i = 0
+        n = len(sequence)
+        while i < n:
+            ch = sequence[i]
+            if ch == "<":
+                end = sequence.find(">", i + 1)
+                if end == -1:
+                    # Unterminated '<' — treat the rest as literal chars.
+                    for c in sequence[i + 1:]:
+                        if not c.isspace():
+                            tokens.append(c)
+                    break
+                inner = sequence[i + 1:end]
+                for part in inner.split("+"):
+                    part = part.strip()
+                    if part:
+                        tokens.append(part)
+                i = end + 1
+            else:
+                if not ch.isspace():
+                    tokens.append(ch)
+                i += 1
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("_normalize_key_tokens failed for %r: %s", sequence, exc)
+    return tokens
+
+
+def _release_sequence_for(tokens) -> str:
+    """Build a PlatynUI release sequence that lifts each token individually,
+    e.g. ``["A", "Ctrl"]`` -> ``"<A><Ctrl>"``."""
+    return "".join(f"<{t}>" for t in tokens)
+
+
+def record_pressed_keys(sequence: Optional[str]) -> None:
+    """Record the keys a ``Keyboard Press``/``Keyboard Type`` is about to hold,
+    and mirror the held set to the per-PID state file so a hard kill is
+    recoverable. Never raises. change: harden-platynui-stuck-key-release."""
+    tokens = _normalize_key_tokens(sequence)
+    if not tokens:
+        return
+    with _HELD_KEYS_LOCK:
+        _HELD_KEYS.update(tokens)
+        _write_state_locked()
+
+
+def record_released_keys(sequence: Optional[str]) -> None:
+    """Remove keys released by ``Keyboard Release`` (or the paired UP inside
+    ``Keyboard Type``) from the registry, updating the state file. Never
+    raises. change: harden-platynui-stuck-key-release."""
+    tokens = _normalize_key_tokens(sequence)
+    if not tokens:
+        return
+    with _HELD_KEYS_LOCK:
+        for t in tokens:
+            _HELD_KEYS.discard(t)
+        _write_state_locked()
+
+
+def release_tracked_keys() -> bool:
+    """Release EXACTLY the keys the registry records as held (including
+    non-modifiers), then defensively blast all modifiers, and clear the
+    registry + state file.
+
+    Best-effort and non-raising; a no-op observationally when nothing is held
+    (releasing a not-held key has no effect). Never starts the runtime solely
+    to release — acts only when the runtime is already open (mirrors
+    ``release_all_modifiers``). change: harden-platynui-stuck-key-release.
+    """
+    if _RUNTIME is None or _RUNTIME_STATE != "open":
+        return False
+    with _HELD_KEYS_LOCK:
+        held = sorted(_HELD_KEYS)
+        dispatched = False
+        try:
+            if held:
+                _RUNTIME.keyboard_release(_release_sequence_for(held))
+                dispatched = True
+            # Fallback blast: covers any modifier that slipped registry tracking.
+            _RUNTIME.keyboard_release(_RELEASE_ALL_SEQUENCE)
+            dispatched = True
+        except Exception as exc:  # pragma: no cover - env dependent
+            logger.debug("release_tracked_keys dispatch failed: %s", exc)
+        _HELD_KEYS.clear()
+        _clear_state_locked()
+        return dispatched
+
+
+# --- Per-PID state file (hard-kill recovery) --------------------------------
+
+
+def _held_keys_dir() -> Optional[str]:
+    """Return (creating if needed) the directory holding per-PID held-key state
+    files, or None on failure. Never raises."""
+    try:
+        import tempfile
+
+        d = os.path.join(tempfile.gettempdir(), _HELD_KEYS_DIRNAME)
+        os.makedirs(d, exist_ok=True)
+        return d
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("_held_keys_dir failed: %s", exc)
+        return None
+
+
+def _state_file_path(pid: Optional[int] = None) -> Optional[str]:
+    d = _held_keys_dir()
+    if d is None:
+        return None
+    return os.path.join(d, f"held_{pid if pid is not None else os.getpid()}.json")
+
+
+def _write_state_locked() -> None:
+    """Atomically write the current held set (with owning PID) to this process's
+    state file, or delete the file when the set is empty. Caller holds
+    ``_HELD_KEYS_LOCK``. Never raises."""
+    path = _state_file_path()
+    if path is None:
+        return
+    try:
+        if not _HELD_KEYS:
+            _clear_state_locked()
+            return
+        import json
+
+        payload = json.dumps({"pid": os.getpid(), "keys": sorted(_HELD_KEYS)})
+        tmp = f"{path}.{os.getpid()}.tmp"
+        with open(tmp, "w", encoding="utf-8") as fh:
+            fh.write(payload)
+        os.replace(tmp, path)
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("_write_state_locked failed: %s", exc)
+
+
+def _clear_state_locked() -> None:
+    """Delete this process's state file. Caller holds ``_HELD_KEYS_LOCK``.
+    Never raises."""
+    path = _state_file_path()
+    if path is None:
+        return
+    try:
+        if os.path.exists(path):
+            os.remove(path)
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("_clear_state_locked failed: %s", exc)
+
+
+def _pid_alive(pid: int) -> bool:
+    """Best-effort liveness check for ``pid``. On any uncertainty returns True
+    (fail-safe: do not replay a file that might belong to a live process)."""
+    if pid <= 0:
+        return False
+    if pid == os.getpid():
+        return True
+    try:
+        if sys.platform == "win32":
+            import ctypes
+
+            PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+            STILL_ACTIVE = 259
+            kernel32 = ctypes.windll.kernel32
+            handle = kernel32.OpenProcess(
+                PROCESS_QUERY_LIMITED_INFORMATION, False, pid
+            )
+            if not handle:
+                return False  # cannot open -> gone (or access denied ~ rare)
+            try:
+                code = ctypes.c_ulong()
+                if kernel32.GetExitCodeProcess(handle, ctypes.byref(code)):
+                    return code.value == STILL_ACTIVE
+                return True
+            finally:
+                kernel32.CloseHandle(handle)
+        else:
+            try:
+                os.kill(pid, 0)
+                return True
+            except ProcessLookupError:
+                return False
+            except PermissionError:
+                return True  # exists but not ours
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("_pid_alive(%s) failed: %s", pid, exc)
+        return True
+
+
+def recover_orphaned_held_keys() -> int:
+    """Replay key-UPs for any state file owned by a DEAD pid (a prior run
+    hard-killed with keys held), then delete the file. Files owned by a live
+    pid are left untouched. Returns the number of files recovered. Best-effort;
+    never raises; never starts the runtime. change:
+    harden-platynui-stuck-key-release."""
+    if _RUNTIME is None or _RUNTIME_STATE != "open":
+        return 0
+    d = _held_keys_dir()
+    if d is None:
+        return 0
+    recovered = 0
+    try:
+        import json
+
+        for name in os.listdir(d):
+            if not (name.startswith("held_") and name.endswith(".json")):
+                continue
+            path = os.path.join(d, name)
+            try:
+                with open(path, "r", encoding="utf-8") as fh:
+                    data = json.loads(fh.read() or "{}")
+            except Exception:
+                # Unreadable/partial file: remove it defensively.
+                try:
+                    os.remove(path)
+                except Exception:
+                    pass
+                continue
+            pid = int(data.get("pid", -1) or -1)
+            keys = data.get("keys") or []
+            if pid == os.getpid() or _pid_alive(pid):
+                continue  # ours or a live session's — do not touch
+            try:
+                if keys:
+                    _RUNTIME.keyboard_release(_release_sequence_for(keys))
+                # Defensive modifier blast for the orphaned session too.
+                _RUNTIME.keyboard_release(_RELEASE_ALL_SEQUENCE)
+                recovered += 1
+            except Exception as exc:  # pragma: no cover - env dependent
+                logger.debug("orphan replay dispatch failed: %s", exc)
+            try:
+                os.remove(path)
+            except Exception:
+                pass
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("recover_orphaned_held_keys failed: %s", exc)
+    return recovered
+
+
 def _register_release_handlers_once() -> None:
     """Arm atexit + SIGTERM handlers that release held modifiers on process
     exit (F16). Called once from ``get_runtime`` under ``_RUNTIME_LOCK`` after
@@ -283,7 +551,7 @@ def _register_release_handlers_once() -> None:
     try:
         import atexit
 
-        atexit.register(release_all_modifiers)
+        atexit.register(release_tracked_keys)
     except Exception as exc:  # pragma: no cover - defensive
         logger.debug("atexit release registration failed: %s", exc)
     try:
@@ -293,7 +561,7 @@ def _register_release_handlers_once() -> None:
         _prior = signal.getsignal(signal.SIGTERM)
 
         def _release_on_sigterm(signum, frame):  # pragma: no cover - signal path
-            release_all_modifiers()
+            release_tracked_keys()
             if callable(_prior) and _prior not in (
                 signal.SIG_DFL,
                 signal.SIG_IGN,
@@ -644,6 +912,11 @@ class PlatynUILibraryPlugin(StaticLibraryPlugin):
                 # process-kill safety net. Registration is idempotent and the
                 # release itself no-ops until the runtime is open. F16.
                 _register_release_handlers_once()
+                # Recover keys left HELD by a prior process that was hard-killed
+                # (SIGKILL/TerminateProcess ran no atexit/SIGTERM handler): replay
+                # key-UPs from any state file owned by a dead pid, then clear it.
+                # change: harden-platynui-stuck-key-release.
+                recover_orphaned_held_keys()
                 # Defensively clear any modifier a PRIOR crashed run left held
                 # (no-op unless the runtime is already open) — F16.
                 release_all_modifiers()
@@ -651,14 +924,15 @@ class PlatynUILibraryPlugin(StaticLibraryPlugin):
             logger.debug("PlatynUI session-start hook failed: %s", exc)
 
     def on_session_end(self, session: "ExecutionSession") -> None:
-        """Release any held keyboard modifiers when a PlatynUI desktop session
-        closes (change: fix-platynui-windows-runtime, F16).
+        """Release any held keyboard keys when a PlatynUI desktop session closes
+        (change: fix-platynui-windows-runtime, F16; harden-platynui-stuck-key-release).
 
         ``session_manager.on_session_end`` invokes this for every plugin; the
         release is a no-op when the runtime is not open or nothing is held, so
-        it is safe for non-desktop sessions too. Never raises."""
+        it is safe for non-desktop sessions too. Never raises. Releases the
+        exact tracked held-key set (incl. non-modifiers), not just modifiers."""
         try:
-            release_all_modifiers()
+            release_tracked_keys()
         except Exception as exc:  # pragma: no cover - defensive
             logger.debug("PlatynUI session-end release failed: %s", exc)