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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rf-mcp
-Version: 0.34.0.dev2
+Version: 0.34.0.dev4
 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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rf-mcp"
-version = "0.34.0.dev2"
+version = "0.34.0.dev4"
 description = "Robot Framework MCP Server - Natural Language Test Automation Bridge"
 authors = [{ name = "Many Kasiriha" }]
 license = { text = "Apache-2.0" }

{rf_mcp-0.34.0.dev2 → rf_mcp-0.34.0.dev4}/src/robotmcp/components/execution/desktop_display_safety.py

@@ -40,12 +40,39 @@ ISOLATION_MARKER_ENV = "ROBOTMCP_PLATYNUI_ISOLATED_DISPLAY"
 ISOLATION_XPID_ENV = "ROBOTMCP_PLATYNUI_ISOLATED_XPID"
 ALLOW_ACTIVE_ENV = "ROBOTMCP_PLATYNUI_ALLOW_ACTIVE_DESKTOP"
 SAFETY_GUARD_ENV = "ROBOTMCP_PLATYNUI_SAFETY_GUARD"  # "warn" => log, don't block
+# Strict opt-IN to enforce isolation on Windows (change:
+# fix-platynui-windows-runtime, F4). Windows has no headless-isolation model
+# (no Xvfb/Xephyr equivalent), so the guard is permissive by default there;
+# operators who insist on isolation set this to refuse instead.
+REQUIRE_ISOLATED_ENV = "ROBOTMCP_PLATYNUI_REQUIRE_ISOLATED"
 
 _X_SERVER_BINARIES = ("xvfb", "xephyr", "xorg", "/x ", "/x\x00", "x11")
 
 ISOLATED = "isolated"
 ACTIVE = "active"
 UNKNOWN = "unknown"
+# Windows has exactly one interactive desktop and no X11 isolated-display
+# model; the X11/EWMH/marker probes never apply (change:
+# fix-platynui-windows-runtime, F4).
+WINDOWS = "windows"
+
+# Windows-accurate isolation note — NEVER the Linux nested-X-server recipe.
+_WINDOWS_ISOLATION_NOTE = (
+    "On Windows there is no headless nested-display isolation model. Desktop "
+    "automation drives the active session's desktop. To isolate it, run rf-mcp "
+    "in a dedicated Windows user session or over RDP to a separate session."
+)
+
+
+def _is_windows() -> bool:
+    """True on Windows (patchable via ``os.name`` in tests)."""
+    return os.name == "nt"
+
+
+def require_isolated(environ: Optional[Dict[str, str]] = None) -> bool:
+    """Strict opt-in to enforce isolation on Windows (F4)."""
+    env = environ if environ is not None else os.environ
+    return env.get(REQUIRE_ISOLATED_ENV, "").strip().lower() in {"1", "true", "yes"}
 
 
 def _bound_display(environ: Dict[str, str]) -> Optional[str]:
@@ -201,6 +228,14 @@ def classify_bound_display_detailed(
     ``none`` (no display bound / probe inconclusive).
     """
     env = environ if environ is not None else os.environ
+    # Windows: no X11/EWMH/marker model applies — classify as `windows` before
+    # any probe (change: fix-platynui-windows-runtime, F4).
+    if _is_windows():
+        return {
+            "display": None,
+            "isolation": WINDOWS,
+            "isolation_source": "windows_console",
+        }
     display = _bound_display(env)
     if _has_isolation_marker(env, display):
         # Corroborate the marker against a recorded X-server PID (change:
@@ -286,6 +321,30 @@ def evaluate_safety(
             "classification": classification, "enforcing": True,
             "allowed": True, "bypassed": False, "reason": None,
         }
+    if classification == WINDOWS:
+        # F4: Windows has no isolated-display model — refusing every keyword
+        # (with an impossible Xephyr recipe) blocks all Windows automation.
+        # Allow by default with a one-time active-desktop warning; a strict
+        # opt-in enforces isolation for operators who want it. No Xephyr recipe.
+        if require_isolated(env):
+            return {
+                "classification": classification, "enforcing": True,
+                "allowed": False, "bypassed": False,
+                "reason": (
+                    "ROBOTMCP_PLATYNUI_REQUIRE_ISOLATED is set and this is a "
+                    "Windows active desktop. " + _WINDOWS_ISOLATION_NOTE
+                ),
+                "windows_note": _WINDOWS_ISOLATION_NOTE,
+            }
+        return {
+            "classification": classification, "enforcing": True,
+            "allowed": True, "bypassed": False,
+            "reason": (
+                "PlatynUI will drive the ACTIVE Windows desktop. "
+                + _WINDOWS_ISOLATION_NOTE
+            ),
+            "windows_note": _WINDOWS_ISOLATION_NOTE,
+        }
     reason = (
         f"bound display classified '{classification}': refusing desktop input "
         "to avoid leaking onto the user's active session. Run on an isolated "

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

@@ -535,6 +535,22 @@ class KeywordExecutor:
             logger.debug("desktop input-effect snapshot skipped: %s", exc)
             return None
 
+    @staticmethod
+    def _is_desktop_keyboard_keyword(session, keyword) -> bool:
+        """True when this is a PlatynUI keyboard keyword on a desktop session
+        (change: fix-platynui-windows-runtime, F16). Used to release held
+        modifiers when a keyboard keyword fails or is killed mid-chord."""
+        try:
+            is_desktop = getattr(session, "is_desktop_session", None)
+            if not (callable(is_desktop) and is_desktop() is True):
+                return False
+            norm = str(keyword or "").lower().rsplit(".", 1)[-1].strip()
+            return norm in (
+                "keyboard press", "keyboard type", "keyboard release",
+            )
+        except Exception:  # pragma: no cover - defensive
+            return False
+
     def _platynui_safety_guard(self, session, keyword):
         """Active-desktop safety guard for PlatynUI interaction keywords
         (change: platynui-desktop-safety-isolation).
@@ -565,6 +581,18 @@ class KeywordExecutor:
                 "PlatynUI safety guard: refused on %s desktop",
                 outcome["classification"],
             )
+        elif outcome["classification"] == "windows":
+            # F4: one-time warning that Windows automation drives the active
+            # desktop (there is no isolated-display model on Windows).
+            if not getattr(session, "_platynui_windows_warned", False):
+                try:
+                    session._platynui_windows_warned = True
+                except Exception:
+                    pass
+                logger.warning(
+                    "PlatynUI: driving the ACTIVE Windows desktop — %s",
+                    outcome.get("reason") or "",
+                )
         return outcome
 
     def _platynui_focus_before_act(self, session, keyword, arguments):
@@ -1886,13 +1914,97 @@ 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:
-            return await self._execute_keyword_serialized(
-                session, keyword, arguments, browser_library_manager,
-                detail_level, library_prefix, assign_to, use_context, timeout_ms,
-                record=record,
-                pre_validate_timeout_ms=pre_validate_timeout_ms,
+            # 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.
+            _kbd = self._is_desktop_keyboard_keyword(session, keyword)
+            try:
+                result = await self._execute_keyword_serialized(
+                    session, keyword, arguments, browser_library_manager,
+                    detail_level, library_prefix, assign_to, use_context,
+                    timeout_ms,
+                    record=record,
+                    pre_validate_timeout_ms=pre_validate_timeout_ms,
+                )
+            except BaseException:
+                # An exception (incl. CancelledError from a killed run) is the
+                # canonical "killed mid-chord" case. Release SYNCHRONOUSLY here
+                # so it is guaranteed to run even while the task is being
+                # cancelled (an awaited offload could be interrupted before it
+                # 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()
+                raise
+            if (
+                _kbd
+                and isinstance(result, dict)
+                and not result.get("success", True)
+                # F2: a steering-confidence downgrade means the native keyword
+                # actually SUCCEEDED (the key is held as intended) — releasing
+                # would corrupt a deliberate Press/Release chord. Only release
+                # on a genuine execution failure.
+                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.
+                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 "
+                                "press+release) over a bare 'Keyboard Press', "
+                                "which sends key-DOWN only and must be paired "
+                                "with 'Keyboard Release'."
+                            ),
+                        })
+                except Exception:  # pragma: no cover - defensive
+                    pass
+            return result
+
+    @staticmethod
+    def _is_steering_downgrade(result: dict) -> bool:
+        """True when a desktop keyword's success was flipped to failure by the
+        steering-confidence gate rather than a genuine execution failure
+        (change: fix-platynui-windows-runtime, F16/F2).
+
+        A steering downgrade means the native keyword DID execute (its key is
+        held as intended), so F16 must not release its modifiers. The gate only
+        downgrades in the RF-success path, so this marker uniquely identifies
+        the case."""
+        try:
+            from robotmcp.components.execution.desktop_execution_signals import (
+                SC_CONTRADICTED,
+            )
+        except Exception:  # pragma: no cover - defensive
+            SC_CONTRADICTED = "contradicted"
+        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."""
+        try:
+            from robotmcp.plugins.builtin.platynui_plugin import (
+                release_all_modifiers,
             )
 
+            release_all_modifiers()
+        except Exception as exc:  # pragma: no cover - defensive
+            logger.debug("desktop modifier release failed: %s", exc)
+
     async def _execute_keyword_serialized(
         self,
         session: ExecutionSession,
@@ -1924,6 +2036,19 @@ class KeywordExecutor:
                     )
 
                     ensure_x11_session_env()
+                    # F3 (change: fix-platynui-windows-runtime): a caller who
+                    # passes an explicit timeout_ms wants desktop query/wait
+                    # keywords to wait that long; stash it so the query-settings
+                    # default (applied in _execute_keyword_with_context) honors
+                    # it. This is PER-CALL — reset to None when absent so a
+                    # one-off long timeout never becomes a session-sticky
+                    # default that defeats the fast-fail behaviour on later
+                    # steps (the short default is restored automatically).
+                    session._platynui_query_timeout_ms = (
+                        timeout_ms
+                        if isinstance(timeout_ms, int) and timeout_ms > 0
+                        else None
+                    )
                     # D2: if a recent desktop launch marked the tree stale,
                     # refresh the cached accessibility tree before the FIRST
                     # tree-resolving keyword so a newly-launched app resolves by
@@ -2029,8 +2154,18 @@ class KeywordExecutor:
                     # the AUT window is visible/in-scope (change:
                     # platynui-focused-execution). FocusError fails fast under
                     # opt-in policy; otherwise warnings ride along on the step.
-                    _focus_outcome = self._platynui_focus_before_act(
-                        session, keyword, arguments
+                    # F14 (change: fix-platynui-windows-runtime): the focus
+                    # manager drives raw runtime.evaluate() (find/activate/
+                    # highlight the AUT window) with NO timeout knob — a broad
+                    # or busy-tree query blocks the event loop for tens of
+                    # seconds, wedging metadata calls. Offload to a worker
+                    # thread so the loop stays free; the global _execution_lock
+                    # already serializes desktop dispatch so no native
+                    # concurrency is introduced. FocusError still propagates
+                    # out of to_thread to the except below.
+                    _focus_outcome = await asyncio.to_thread(
+                        self._platynui_focus_before_act,
+                        session, keyword, arguments,
                     )
                     # Resolve a desktop Process launch/recovery executable to an
                     # absolute path against the server PATH (maintainer-report
@@ -2052,8 +2187,10 @@ class KeywordExecutor:
                     # so a success-with-no-effect can be flagged afterward
                     # (change: desktop-input-and-runtime-diagnostics). Native /
                     # non-reentrant; best-effort.
-                    _input_effect_before = self._desktop_text_count_before(
-                        keyword, arguments
+                    # F14: native CharacterCount query — also offload off the
+                    # loop (change: fix-platynui-windows-runtime).
+                    _input_effect_before = await asyncio.to_thread(
+                        self._desktop_text_count_before, keyword, arguments
                     )
             except Exception as _focus_exc:
                 from robotmcp.components.execution.platynui_focus import FocusError
@@ -2551,7 +2688,13 @@ class KeywordExecutor:
                         # but the target's CharacterCount did not change.
                         _after = None
                         if _input_effect_before is not None:
-                            _after = self._desktop_text_count_before(keyword, arguments)
+                            # F14 (change: fix-platynui-windows-runtime): the
+                            # AFTER CharacterCount probe is the same native
+                            # runtime.evaluate() as the offloaded BEFORE probe —
+                            # offload it off the loop too for symmetry.
+                            _after = await asyncio.to_thread(
+                                self._desktop_text_count_before, keyword, arguments
+                            )
                             _eh = input_effect_hint(
                                 keyword=keyword,
                                 success=True,
@@ -3089,6 +3232,90 @@ class KeywordExecutor:
             return mapped
         return None
 
+    # Short default desktop query timeout (F3). PlatynUI.BareMetal's
+    # QuerySettings default is 30s, so an honest-miss Query/wait waits the full
+    # 30s and stacks across retries (up to ~180s in the Windows eval). A short
+    # default fails fast; a caller can still request a longer wait via
+    # timeout_ms. Overridable via ROBOTMCP_PLATYNUI_QUERY_TIMEOUT_MS.
+    _DEFAULT_PLATYNUI_QUERY_TIMEOUT_MS = 1500
+
+    def _ensure_desktop_query_timeout(self, session) -> None:
+        """Give desktop PlatynUI query/wait keywords a short default timeout so
+        an honest-miss fails fast (change: fix-platynui-windows-runtime, F3).
+
+        Mirrors ``Set Query Settings scope=SUITE`` by writing a short-timeout
+        ``QuerySettings`` into ``${PLATYNUI_QUERY_SETTINGS}`` in the live RF
+        context, once per session (re-applied only if the desired value
+        changed). A caller-supplied ``timeout_ms`` (stashed on the session)
+        overrides the short default. Best-effort; never raises — on any failure
+        the library keeps its 30s default (no worse than before)."""
+        try:
+            checker = getattr(session, "is_desktop_session", None)
+            if not (callable(checker) and checker() is True):
+                return
+        except Exception:
+            return
+        try:
+            default_ms = int(
+                os.environ.get(
+                    "ROBOTMCP_PLATYNUI_QUERY_TIMEOUT_MS",
+                    str(self._DEFAULT_PLATYNUI_QUERY_TIMEOUT_MS),
+                )
+            )
+        except (ValueError, TypeError):
+            default_ms = self._DEFAULT_PLATYNUI_QUERY_TIMEOUT_MS
+        desired_ms = getattr(session, "_platynui_query_timeout_ms", None) or default_ms
+        if desired_ms <= 0:
+            return
+        if getattr(session, "_platynui_query_timeout_applied_ms", None) == desired_ms:
+            return
+        try:
+            from dataclasses import replace as _dc_replace
+
+            from robot.running.context import EXECUTION_CONTEXTS as _EC
+            from PlatynUI.BareMetal import (  # library-sanctioned mechanism
+                PLATYNUI_QUERY_SETTINGS,
+                QuerySettings,
+            )
+
+            ctx = _EC.current
+            if ctx is None:
+                return
+            variables = ctx.variables
+            name = f"${{{PLATYNUI_QUERY_SETTINGS}}}"
+            # Preserve any non-timeout query settings already in scope
+            # (retry_interval / ignore_exceptions) instead of resetting them to
+            # class defaults — only the timeout is ours to change.
+            base = None
+            try:
+                if PLATYNUI_QUERY_SETTINGS in variables:
+                    existing = variables[name]
+                    if isinstance(existing, QuerySettings):
+                        base = existing
+            except Exception:
+                base = None
+            timeout_s = desired_ms / 1000.0
+            settings = (
+                _dc_replace(base, timeout=timeout_s)
+                if base is not None
+                else QuerySettings(timeout=timeout_s)
+            )
+            # set_suite(children=True): a bare write into the SUITE store is
+            # invisible because rf-mcp already holds a live TEST scope copied
+            # from suite BEFORE the write, and PlatynUI resolves the variable
+            # via variables.current (the test scope). set_suite(children=True)
+            # both persists at SUITE (surviving per-step test-scope resets) AND
+            # propagates down to the current/test scope so the library sees it
+            # immediately (mirrors Set Query Settings scope=SUITE).
+            variables.set_suite(name, settings, children=True)
+            session._platynui_query_timeout_applied_ms = desired_ms
+            logger.debug(
+                "Applied desktop query timeout %sms via ${PLATYNUI_QUERY_SETTINGS}",
+                desired_ms,
+            )
+        except Exception as exc:  # pragma: no cover - env/internals dependent
+            logger.debug("desktop query-settings apply skipped: %s", exc)
+
     def _inject_timeout_into_arguments(
         self,
         keyword: str,
@@ -3675,6 +3902,10 @@ class KeywordExecutor:
             except Exception:
                 pass
 
+            # F3: give desktop query/wait keywords a short fast-fail timeout
+            # now that the RF context exists (no-op for non-desktop sessions).
+            self._ensure_desktop_query_timeout(session)
+
             # Execute keyword using RF native context with session variables
             result = await asyncio.to_thread(
                 self.rf_native_context.execute_keyword_with_context,

{rf_mcp-0.34.0.dev2 → rf_mcp-0.34.0.dev4}/src/robotmcp/components/test_builder.py

@@ -110,6 +110,39 @@ class GeneratedTestSuite:
     column_headers: Optional[List[str]] = None
 
 
+# change: fix-suite-arg-escape-roundtrip. RF recognizes only \n \r \t (+ \xHH \uHHHH
+# \UHHHHHHHH) as escapes and drops the backslash for anything else. Preserve those and the
+# syntax escapes rf-mcp/agents rely on; double every other literal backslash so RF's parser
+# recovers the value. Idempotent: an already-doubled \\ is kept as a pair.
+_RF_ESCAPE_PRESERVE_NEXT = frozenset("nrtxuU=#$@&%{} ")
+
+
+def _escape_aware_backslashes(s: str) -> str:
+    """Double literal backslashes that RF would drop, preserving real/intended escapes."""
+    if "\\" not in s:
+        return s
+    out: List[str] = []
+    i, n = 0, len(s)
+    while i < n:
+        c = s[i]
+        if c == "\\":
+            nxt = s[i + 1] if i + 1 < n else ""
+            if nxt == "\\":
+                out.append("\\\\")      # keep an existing \\ pair verbatim (idempotent)
+                i += 2
+                continue
+            if nxt in _RF_ESCAPE_PRESERVE_NEXT:
+                out.append("\\")        # recognized/intended escape — do not double
+                i += 1
+                continue
+            out.append("\\\\")          # unrecognized escape / trailing lone \ — double it
+            i += 1
+            continue
+        out.append(c)
+        i += 1
+    return "".join(out)
+
+
 class TestBuilder:
     """Builds Robot Framework test suites from successful execution steps."""
 
@@ -4098,6 +4131,24 @@ class TestBuilder:
         # Fix malformed evaluation namespace expressions first
         arg = self._fix_malformed_evaluation_namespace(arg)
 
+        # Platform-independent path form (change: fix-suite-path-escaping): a Windows
+        # DRIVE-LETTER path is rewritten to forward slashes — valid for Start Process/
+        # subprocess and the OperatingSystem keywords on BOTH Windows and POSIX, and
+        # RF-escape-safe. Without this, RF's escape processing corrupts a literal
+        # backslash path (C:\WINDOWS -> C:WINDOWS; C:\name -> embedded newline).
+        # Only the unambiguous drive-letter shape is touched; flags (/w), URLs
+        # (https://…) and variable references do NOT match and are left unchanged.
+        if re.match(r"^[A-Za-z]:[\\/]", arg):
+            arg = arg.replace("\\", "/")
+
+        # Escape-aware backslash round-trip (change: fix-suite-arg-escape-roundtrip). RF
+        # drops the backslash for every escape it does not recognize (\d -> d, \W -> W), so
+        # a literal backslash (regex, relative Windows path) is corrupted on parse. Double
+        # a backslash ONLY where RF would drop it; PRESERVE RF's real escapes (\n \r \t,
+        # \x \u \U), an already-doubled \\, and the intended syntax escapes (\= \# \$ \{ \}
+        # \@ \& \% \<space>). Idempotent, and leaves ${..} references (no backslash) intact.
+        arg = _escape_aware_backslashes(arg)
+
         # Escape literal newlines/tabs so they don't break the .robot line structure.
         # RF uses \n / \t as escape sequences, so we emit \\n / \\t in the text
         # which RF interprets back as the literal characters at runtime.

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

@@ -162,6 +162,17 @@ _RUNTIME_STATE = "new"
 # Last bind/connect failure text (for classification). None once open.
 _RUNTIME_LAST_ERROR: Optional[str] = None
 
+# Stuck-key safety net (change: fix-platynui-windows-runtime, F16). ``Keyboard
+# Press`` sends key-DOWN only, and runs that time out / are killed mid-chord can
+# leave a modifier physically held at the OS level — the operator's keyboard is
+# then wedged until reboot. Releasing keys that are not held is a proven no-op,
+# so a broad release sequence is always safe. Left+right variants + AltGr + Win
+# cover every modifier the native keyboard recognizes.
+_RELEASE_ALL_SEQUENCE = "<LCtrl+RCtrl+LAlt+RAlt+AltGr+LShift+RShift+LWin+RWin>"
+# atexit/SIGTERM release handlers are registered exactly once, on first runtime
+# bind (guarded under _RUNTIME_LOCK), so a killed process still releases keys.
+_RELEASE_HANDLERS_REGISTERED = False
+
 
 def runtime_unavailable_reason() -> Optional[str]:
     """Classify why the PlatynUI runtime is unavailable, or None when it is
@@ -225,6 +236,9 @@ def get_runtime():
             _RUNTIME = pn.Runtime()
             _RUNTIME_STATE = "open"
             _RUNTIME_LAST_ERROR = None
+            # First successful bind: arm the stuck-key safety net so a killed
+            # process still releases held modifiers (F16). Under _RUNTIME_LOCK.
+            _register_release_handlers_once()
         except Exception as exc:  # pragma: no cover - env dependent
             logger.debug("PlatynUI runtime broker bind failed: %s", exc)
             _RUNTIME = None
@@ -235,6 +249,72 @@ def get_runtime():
         return _RUNTIME
 
 
+def release_all_modifiers() -> bool:
+    """Best-effort release of every keyboard modifier (change:
+    fix-platynui-windows-runtime, F16).
+
+    Releases Ctrl/Alt/AltGr/Shift/Win (left+right) against the ALREADY-OPEN
+    native runtime. Releasing a key that is not held is a no-op, so this is
+    always safe to call from teardown, keyword-failure ``finally`` paths, and
+    process-exit handlers. Never raises; never starts the runtime just to
+    release (teardown must not spin up the native broker). Returns True when a
+    release was dispatched.
+    """
+    if _RUNTIME is None or _RUNTIME_STATE != "open":
+        return False
+    try:
+        _RUNTIME.keyboard_release(_RELEASE_ALL_SEQUENCE)
+        return True
+    except Exception as exc:  # pragma: no cover - env dependent
+        logger.debug("release_all_modifiers failed: %s", exc)
+        return False
+
+
+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
+    the first successful bind — the safety net for a run killed mid-chord (e.g.
+    a ``claude -p`` process terminated before ``on_session_end`` runs). Never
+    raises."""
+    global _RELEASE_HANDLERS_REGISTERED
+    if _RELEASE_HANDLERS_REGISTERED:
+        return
+    _RELEASE_HANDLERS_REGISTERED = True
+    try:
+        import atexit
+
+        atexit.register(release_all_modifiers)
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("atexit release registration failed: %s", exc)
+    try:
+        import signal
+
+        # Chain to any prior SIGTERM handler so we don't swallow shutdown.
+        _prior = signal.getsignal(signal.SIGTERM)
+
+        def _release_on_sigterm(signum, frame):  # pragma: no cover - signal path
+            release_all_modifiers()
+            if callable(_prior) and _prior not in (
+                signal.SIG_DFL,
+                signal.SIG_IGN,
+            ):
+                _prior(signum, frame)
+            elif _prior == signal.SIG_IGN:
+                # Prior handler explicitly ignored SIGTERM — preserve that.
+                return
+            else:
+                # SIG_DFL, None, or unknown: restore the default and re-raise so
+                # the process still terminates on SIGTERM (never leave it
+                # un-killable by swallowing the signal).
+                signal.signal(signal.SIGTERM, signal.SIG_DFL)
+                os.kill(os.getpid(), signum)
+
+        signal.signal(signal.SIGTERM, _release_on_sigterm)
+    except (ValueError, OSError, AttributeError) as exc:
+        # signal.signal only works on the main thread; best-effort otherwise.
+        logger.debug("SIGTERM release registration skipped: %s", exc)
+
+
 def runtime_state() -> str:
     return _RUNTIME_STATE
 
@@ -555,9 +635,33 @@ class PlatynUILibraryPlugin(StaticLibraryPlugin):
             libraries.append(preference)
             if any("platynui" in str(lib).lower() for lib in libraries):
                 ensure_x11_session_env()
+                # Arm the stuck-key release handlers HERE, on the main thread
+                # (session creation runs on the event loop). The first runtime
+                # bind often happens inside the F14 to_thread-offloaded focus
+                # call on a WORKER thread, where signal.signal() raises — so
+                # arming only at bind time would silently skip the SIGTERM net
+                # (and default SIGTERM also skips atexit), defeating the F16
+                # process-kill safety net. Registration is idempotent and the
+                # release itself no-ops until the runtime is open. F16.
+                _register_release_handlers_once()
+                # Defensively clear any modifier a PRIOR crashed run left held
+                # (no-op unless the runtime is already open) — F16.
+                release_all_modifiers()
         except Exception as exc:  # pragma: no cover - defensive
             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).
+
+        ``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."""
+        try:
+            release_all_modifiers()
+        except Exception as exc:  # pragma: no cover - defensive
+            logger.debug("PlatynUI session-end release failed: %s", exc)
+
     def before_keyword_execution(
         self,
         session: "ExecutionSession",