python-libei 0.3.0__tar.gz → 0.4.0__tar.gz

{python_libei-0.3.0/src/python_libei.egg-info → python_libei-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-libei
-Version: 0.3.0
+Version: 0.4.0
 Summary: Inject and receive input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis
 Author: Dennis K. Paulsen
 License-Expression: MIT
@@ -9,7 +9,7 @@ Project-URL: repository, https://github.com/ctrondlp/python-libei
 Project-URL: issues, https://github.com/ctrondlp/python-libei/issues
 Project-URL: changelog, https://github.com/ctrondlp/python-libei/blob/main/CHANGELOG.md
 Keywords: wayland,libei,libeis,liboeffis,input,input-emulation,emulated-input,portal,xdg-desktop-portal,remote-desktop,automation,gui-testing,accessibility,ctypes
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
@@ -136,7 +136,7 @@ pointer.
 
 ## Status
 
-Alpha (`0.3.0`), published on [PyPI](https://pypi.org/project/python-libei/)
+Beta (`0.4.0`), published on [PyPI](https://pypi.org/project/python-libei/)
 since `0.1.0`, and the API is not frozen — expect renames before 1.0. What
 that qualifier covers, concretely:
 
@@ -151,7 +151,8 @@ that qualifier covers, concretely:
   verified by hand, since they need an interactive consent dialog that
   nothing here can drive automatically — `tests/test_portal.py` covers
   `libei.portal`'s orchestration (raceless subscribe-before-call, the
-  `session_handle_token` crash workaround, persist_mode/restore_token)
+  `session_handle_token` crash workaround, persist_mode/restore_token, and
+  closing the portal session on a negotiation that fails part-way)
   against a fake D-Bus connection only. `libei.oeffis` was verified by hand
   on 2026-08-25 (see [Troubleshooting](#troubleshooting)), and
   `libei.portal` on 2026-09-01 against a real GNOME Wayland session

{python_libei-0.3.0 → python_libei-0.4.0}/README.md

@@ -100,7 +100,7 @@ pointer.
 
 ## Status
 
-Alpha (`0.3.0`), published on [PyPI](https://pypi.org/project/python-libei/)
+Beta (`0.4.0`), published on [PyPI](https://pypi.org/project/python-libei/)
 since `0.1.0`, and the API is not frozen — expect renames before 1.0. What
 that qualifier covers, concretely:
 
@@ -115,7 +115,8 @@ that qualifier covers, concretely:
   verified by hand, since they need an interactive consent dialog that
   nothing here can drive automatically — `tests/test_portal.py` covers
   `libei.portal`'s orchestration (raceless subscribe-before-call, the
-  `session_handle_token` crash workaround, persist_mode/restore_token)
+  `session_handle_token` crash workaround, persist_mode/restore_token, and
+  closing the portal session on a negotiation that fails part-way)
   against a fake D-Bus connection only. `libei.oeffis` was verified by hand
   on 2026-08-25 (see [Troubleshooting](#troubleshooting)), and
   `libei.portal` on 2026-09-01 against a real GNOME Wayland session

{python_libei-0.3.0 → python_libei-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-libei"
-version = "0.3.0"
+version = "0.4.0"
 description = "Inject and receive input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis"
 readme = "README.md"
 license = "MIT"
@@ -27,7 +27,7 @@ keywords = [
     "ctypes",
 ]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "Operating System :: POSIX :: Linux",
     "Programming Language :: Python :: 3",

{python_libei-0.3.0 → python_libei-0.4.0}/src/libei/__init__.py

@@ -26,9 +26,9 @@ evdev keycodes -- key positions, not characters -- though ``text_utf8()``
 sends characters directly where libei 1.6 is available. See the README for
 the full breakdown, including which features need which libei version.
 
-Alpha: the API is not frozen.
+Beta: the API is not frozen.
 """
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 __all__ = ["__version__"]

{python_libei-0.3.0 → python_libei-0.4.0}/src/libei/portal.py

@@ -63,6 +63,7 @@ from __future__ import annotations
 import enum
 import logging
 import os
+import time
 import uuid
 from typing import Any
 
@@ -95,6 +96,23 @@ to see and answer the consent dialog `Start` raises -- but bounded, because
 the alternative is a caller wedged forever if the portal dies after
 accepting the call and before sending its `Response`."""
 
+_GIO_DEFAULT_TIMEOUT_MSEC = 25_000
+"""What GDBus's ``-1`` reply timeout actually is.
+
+``call_sync(..., -1, ...)`` does not mean "wait forever" -- that is
+``G_MAXINT`` -- it means GIO's own default, which is 25 seconds. Only used
+to report the right number when a call left on that default runs out of
+time; see `_call_sync`."""
+
+_G_IO_ERROR_DOMAIN = "g-io-error-quark"
+"""The GLib error domain GDBus reports its own reply timeout in.
+
+Not one of the ``org.freedesktop.DBus.Error.*`` codes, as one might expect:
+a ``call_sync()`` whose reply never arrives raises ``G_IO_ERROR_TIMED_OUT``
+in this domain with the message "Timeout was reached" (checked against a
+service that accepts a call and then deliberately never answers). See
+`_is_reply_timeout`."""
+
 _ALL_DEVICE_TYPES = DeviceType.KEYBOARD | DeviceType.POINTER | DeviceType.TOUCHSCREEN
 """Every bit the RemoteDesktop `types` bitmask defines.
 
@@ -189,6 +207,43 @@ def _glib_error(GLib: Any) -> Any:
     return getattr(GLib, "Error", ())
 
 
+def _is_reply_timeout(Gio: Any, exc: Exception) -> bool:
+    """Whether a GDBus failure is its own reply timeout expiring.
+
+    Worth telling apart from every other ``GLib.Error``, because it means
+    exactly what the nested loop's own timeout means -- nobody answered in
+    the time allowed -- and so should raise the `PortalTimeoutError` a
+    caller is documented to catch for that, not a generic `PortalError`.
+
+    Defensive throughout: a test double standing in for ``Gio`` need not
+    define ``IOErrorEnum``, and one standing in for ``GLib.Error`` need not
+    carry a domain or a code. An attribute that isn't there just means
+    "not a timeout", which is the safe answer -- the failure still reaches
+    the caller, only as the more general error.
+    """
+    timed_out = getattr(getattr(Gio, "IOErrorEnum", None), "TIMED_OUT", None)
+    if timed_out is None:
+        return False
+    return (
+        getattr(exc, "domain", None) == _G_IO_ERROR_DOMAIN
+        and getattr(exc, "code", None) == timed_out
+    )
+
+
+def _msec_until(deadline: float) -> int:
+    """Milliseconds left before ``deadline``, never negative.
+
+    Both legs of a round trip -- the call that returns the request handle,
+    then the wait for its ``Response`` signal -- draw down the same
+    deadline, so ``timeout`` bounds the round trip rather than each half of
+    it separately, which would let a slow first leg quietly double the wait
+    a caller asked for. Zero is a legitimate answer: GLib fires a 0ms
+    timeout on the next main-loop iteration, which is the right thing for a
+    deadline that has already passed.
+    """
+    return max(0, int((deadline - time.monotonic()) * 1000))
+
+
 def _call_sync(
     connection: Any,
     Gio: Any,
@@ -199,6 +254,7 @@ def _call_sync(
     method: str,
     parameters: Any,
     reply_type: Any,
+    timeout_msec: int = -1,
 ) -> Any:
     """``call_sync``, with GDBus failures translated to `PortalError`.
 
@@ -206,6 +262,13 @@ def _call_sync(
     no-portal-backend cases -- exactly the ones `is_available()` documents
     as surfacing here, since it deliberately checks neither -- escape a
     caller's `except PortalError`.
+
+    ``timeout_msec`` is GDBus's own reply timeout, and defaults to its
+    ``-1`` -- GIO's 25 seconds (see `_GIO_DEFAULT_TIMEOUT_MSEC`), which is
+    what `RemoteDesktopSession.close` leaves it at, having no caller-facing
+    timeout to honour. Anything reached from `negotiate` passes the
+    caller's own ``timeout`` instead, so that the bound on a round trip is
+    the documented one rather than a number this module never chose.
     """
     try:
         return connection.call_sync(
@@ -216,13 +279,47 @@ def _call_sync(
             parameters,
             reply_type,
             Gio.DBusCallFlags.NONE,
-            -1,
+            timeout_msec,
             None,
         )
     except _glib_error(GLib) as exc:
+        if _is_reply_timeout(Gio, exc):
+            expired = timeout_msec if timeout_msec >= 0 else _GIO_DEFAULT_TIMEOUT_MSEC
+            raise PortalTimeoutError(method, expired / 1000) from exc
         raise PortalError(f"{method} failed on the D-Bus: {exc}") from exc
 
 
+def _close_session(
+    connection: Any,
+    Gio: Any,
+    GLib: Any,
+    busname: str,
+    session_handle: str,
+) -> None:
+    """Call ``Session.Close()``, logging rather than raising on failure.
+
+    Shared by `RemoteDesktopSession.close` and `negotiate`'s failure path,
+    which need the same thing of it: the session may already be gone (the
+    portal restarted, the user revoked the grant), and neither a caller
+    tidying up nor an exception already unwinding is helped by a second
+    failure thrown over the top of the first.
+    """
+    try:
+        _call_sync(
+            connection,
+            Gio,
+            GLib,
+            busname,
+            session_handle,
+            _SESSION_INTERFACE,
+            "Close",
+            None,
+            None,
+        )
+    except PortalError as exc:
+        logger.debug("closing the portal session failed: %s", exc)
+
+
 def _returned_handle(reply: Any) -> str | None:
     """The request object path a Request-returning call replied with.
 
@@ -269,11 +366,16 @@ def _request(
     call at all -- the pattern xdg-desktop-portal's own documentation
     describes.
 
-    Raises :class:`PortalTimeoutError` if no ``Response`` arrives within
-    ``timeout``. The nested loop is otherwise unbounded, and a portal that
-    dies after accepting the call sends no ``Response`` and no error --
-    leaving the caller wedged with nothing to poll and no way out.
+    Raises :class:`PortalTimeoutError` if the whole round trip -- the call
+    that returns the request handle, then the ``Response`` that answers it
+    -- exceeds ``timeout``. The nested loop is otherwise unbounded, and a
+    portal that dies after accepting the call sends no ``Response`` and no
+    error, leaving the caller wedged with nothing to poll and no way out.
+    Both legs share one deadline (see `_msec_until`), since a caller asking
+    for 60 seconds means the answer arrives inside 60 seconds, not inside
+    however many 60-second waits the sequence happens to be built from.
     """
+    deadline = time.monotonic() + timeout
     unique_name = connection.get_unique_name()
     escaped_sender = unique_name[1:].replace(".", "_")
     token = uuid.uuid4().hex
@@ -337,6 +439,7 @@ def _request(
             method,
             parameters,
             None,
+            _msec_until(deadline),
         )
         # The spec says the handle the call returns matches the path derived
         # from our own handle_token, but a portal is free to hand back
@@ -353,7 +456,7 @@ def _request(
         # is not running yet does not stop the later run(), so running it
         # then would block with the reply already delivered.
         if not result:
-            timeout_source = GLib.timeout_add(int(timeout * 1000), on_timeout)
+            timeout_source = GLib.timeout_add(_msec_until(deadline), on_timeout)
             try:
                 loop.run()
             finally:
@@ -377,12 +480,18 @@ def _call_for_fd(
     interface: str,
     method: str,
     session_handle: str,
+    timeout: float,
 ) -> int:
     """Call a method that returns a fd via a GUnixFDList index.
 
     The fd that comes back is *owned* -- `g_unix_fd_list_get()` dups it --
     so whoever receives it has to close it. See
     :meth:`RemoteDesktopSession.close`.
+
+    ``ConnectToEIS`` returns no `Request`, so there is no ``Response`` to
+    wait on and nothing here beyond the call itself -- but it is a call to
+    the same portal that just made the caller wait on a consent dialog, so
+    it is bounded by the same ``timeout`` rather than by GIO's default.
     """
     try:
         reply, fd_list = connection.call_with_unix_fd_list_sync(
@@ -393,17 +502,22 @@ def _call_for_fd(
             GLib.Variant("(oa{sv})", (session_handle, {})),
             GLib.VariantType.new("(h)"),
             Gio.DBusCallFlags.NONE,
-            -1,
+            int(timeout * 1000),
             None,
             None,
         )
     except _glib_error(GLib) as exc:
+        if _is_reply_timeout(Gio, exc):
+            raise PortalTimeoutError(method, timeout) from exc
         raise PortalError(f"{method} failed on the D-Bus: {exc}") from exc
     (handle_index,) = reply.unpack()
     return fd_list.get(handle_index)
 
 
-def _remote_desktop_version(connection: Any, Gio: Any, GLib: Any, busname: str) -> int:
+def _remote_desktop_version(
+    connection: Any, Gio: Any, GLib: Any, busname: str, timeout: float
+) -> int:
+    """Read the RemoteDesktop portal's ``version`` property."""
     reply = _call_sync(
         connection,
         Gio,
@@ -414,6 +528,7 @@ def _remote_desktop_version(connection: Any, Gio: Any, GLib: Any, busname: str)
         "Get",
         GLib.Variant("(ss)", (_REMOTE_DESKTOP, "version")),
         None,
+        int(timeout * 1000),
     )
     (version,) = reply.unpack()
     return int(version)
@@ -446,10 +561,15 @@ class RemoteDesktopSession:
         eis_fd: int,
         restore_token: str | None,
         session_handle: str | None = None,
+        busname: str = _BUS_NAME,
     ) -> None:
         self._connection = connection
         self._eis_fd: int | None = eis_fd
         self._session_handle = session_handle
+        # Whichever bus name negotiate() used, not the default: a session
+        # created on an alternate portal name has to be closed on that same
+        # name, or Session.Close() goes to a portal that never heard of it.
+        self._busname = busname
         # Mirrors libei.oeffis.Oeffis's ownership rule: reading `eis_fd`
         # hands the fd to the caller, so close() must not also close it once
         # that has happened -- but nothing else will ever close it if the
@@ -516,19 +636,13 @@ class RemoteDesktopSession:
             return
         Gio, GLib = gio_modules
         try:
-            _call_sync(
+            _close_session(
                 self._connection,
                 Gio,
                 GLib,
-                _BUS_NAME,
+                self._busname,
                 self._session_handle,
-                _SESSION_INTERFACE,
-                "Close",
-                None,
-                None,
             )
-        except PortalError as exc:
-            logger.debug("closing the portal session failed: %s", exc)
         finally:
             self._session_handle = None
             self._connection = None
@@ -578,7 +692,11 @@ class RemoteDesktopSession:
         :class:`PortalDeniedError` if any step is declined, and
         :class:`PortalTimeoutError` if any one round trip exceeds
         ``timeout`` seconds (60 by default -- generous, since ``Start``
-        waits on a human answering a dialog).
+        waits on a human answering a dialog). Any of those raised after
+        ``CreateSession`` has succeeded closes the session it created on
+        the way out; nothing else could, since no `RemoteDesktopSession`
+        exists yet to own it and the portal would keep it alive for the
+        life of the bus connection.
 
         ``devices`` selects what to ask for. ``DeviceType.ALL_DEVICES`` is
         liboeffis's sentinel for "everything" and is literally ``0``, which
@@ -628,7 +746,7 @@ class RemoteDesktopSession:
             except _glib_error(GLib) as exc:
                 raise PortalError(f"cannot reach the session bus: {exc}") from exc
 
-        version = _remote_desktop_version(connection, Gio, GLib, busname)
+        version = _remote_desktop_version(connection, Gio, GLib, busname, timeout)
         if version < _MIN_REMOTE_DESKTOP_VERSION:
             raise PortalVersionError(
                 f"RemoteDesktop version {version} is too old for "
@@ -653,8 +771,60 @@ class RemoteDesktopSession:
         )
         if code != 0:
             raise PortalDeniedError("CreateSession")
-        session_handle = results["session_handle"]
+        session_handle = results.get("session_handle")
+        if not isinstance(session_handle, str):
+            # Approved, but with no handle to address the rest of the
+            # sequence to. `results` is portal-supplied data like any other
+            # reply, so a malformed one fails the way the rest of this
+            # module's do -- rather than as the KeyError a direct index
+            # would raise straight past a caller's `except PortalError`.
+            raise PortalError("CreateSession returned no session_handle")
+
+        # Past this point a session exists inside xdg-desktop-portal, and
+        # nothing else can close it: no RemoteDesktopSession owns it yet,
+        # and the connection it was created on is GLib's shared session-bus
+        # singleton, which outlives this failure rather than taking the
+        # session down with it. So every exit from here closes it.
+        try:
+            return cls._connect_devices(
+                connection,
+                Gio,
+                GLib,
+                busname,
+                session_handle,
+                devices=devices,
+                persist_mode=persist_mode,
+                restore_token=restore_token,
+                timeout=timeout,
+            )
+        except BaseException:
+            # BaseException, not Exception: `Start` blocks on a human
+            # answering a consent dialog, so Ctrl-C during that wait is a
+            # routine way out of this function -- and it strands an
+            # approved session exactly as a decline does.
+            _close_session(connection, Gio, GLib, busname, session_handle)
+            raise
+
+    @classmethod
+    def _connect_devices(
+        cls,
+        connection: Any,
+        Gio: Any,
+        GLib: Any,
+        busname: str,
+        session_handle: str,
+        *,
+        devices: DeviceType,
+        persist_mode: PersistMode,
+        restore_token: str | None,
+        timeout: float,
+    ) -> RemoteDesktopSession:
+        """``SelectDevices`` -> ``Start`` -> ``ConnectToEIS``, given a session.
 
+        Split out of :meth:`negotiate` only so that the caller can wrap the
+        whole of it in one ``try`` -- every step here can fail, and every
+        one of those failures leaves the same session behind to be closed.
+        """
         # ALL_DEVICES is 0, which SelectDevices reads as "no device types"
         # rather than "every device type" -- see _ALL_DEVICE_TYPES.
         types = _ALL_DEVICE_TYPES if devices == DeviceType.ALL_DEVICES else devices
@@ -704,5 +874,12 @@ class RemoteDesktopSession:
             _REMOTE_DESKTOP,
             "ConnectToEIS",
             session_handle,
+            timeout,
+        )
+        return cls(
+            connection,
+            eis_fd,
+            new_restore_token,
+            session_handle,
+            busname,
         )
-        return cls(connection, eis_fd, new_restore_token, session_handle)

{python_libei-0.3.0 → python_libei-0.4.0/src/python_libei.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-libei
-Version: 0.3.0
+Version: 0.4.0
 Summary: Inject and receive input on Wayland from Python: ctypes bindings for libei, libeis and liboeffis
 Author: Dennis K. Paulsen
 License-Expression: MIT
@@ -9,7 +9,7 @@ Project-URL: repository, https://github.com/ctrondlp/python-libei
 Project-URL: issues, https://github.com/ctrondlp/python-libei/issues
 Project-URL: changelog, https://github.com/ctrondlp/python-libei/blob/main/CHANGELOG.md
 Keywords: wayland,libei,libeis,liboeffis,input,input-emulation,emulated-input,portal,xdg-desktop-portal,remote-desktop,automation,gui-testing,accessibility,ctypes
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
@@ -136,7 +136,7 @@ pointer.
 
 ## Status
 
-Alpha (`0.3.0`), published on [PyPI](https://pypi.org/project/python-libei/)
+Beta (`0.4.0`), published on [PyPI](https://pypi.org/project/python-libei/)
 since `0.1.0`, and the API is not frozen — expect renames before 1.0. What
 that qualifier covers, concretely:
 
@@ -151,7 +151,8 @@ that qualifier covers, concretely:
   verified by hand, since they need an interactive consent dialog that
   nothing here can drive automatically — `tests/test_portal.py` covers
   `libei.portal`'s orchestration (raceless subscribe-before-call, the
-  `session_handle_token` crash workaround, persist_mode/restore_token)
+  `session_handle_token` crash workaround, persist_mode/restore_token, and
+  closing the portal session on a negotiation that fails part-way)
   against a fake D-Bus connection only. `libei.oeffis` was verified by hand
   on 2026-08-25 (see [Troubleshooting](#troubleshooting)), and
   `libei.portal` on 2026-09-01 against a real GNOME Wayland session

{python_libei-0.3.0 → python_libei-0.4.0}/tests/test_portal.py

@@ -21,6 +21,7 @@ from __future__ import annotations
 
 import os
 import sys
+import time
 import types
 from collections.abc import Iterator
 from typing import Any
@@ -54,7 +55,18 @@ class FakeUnixFDList:
 
 
 class FakeGLibError(Exception):
-    """Stands in for `GLib.Error`, which every GDBus failure arrives as."""
+    """Stands in for `GLib.Error`, which every GDBus failure arrives as.
+
+    `domain` and `code` are what portal._is_reply_timeout reads to tell
+    GDBus's own reply timeout from every other D-Bus failure. They default
+    to values that match nothing, so a bare FakeGLibError still stands for
+    "some other failure" as it did before.
+    """
+
+    def __init__(self, message: str = "", domain: str = "", code: int = 0) -> None:
+        super().__init__(message)
+        self.domain = domain
+        self.code = code
 
 
 _OPEN_PIPES: list[tuple[int, int]] = []
@@ -97,6 +109,9 @@ class FakeMainLoop:
     """
 
     pending_timeout: Any = None
+    # What GLib.timeout_add was asked to wait, so a test can check the
+    # Response leg got only the time the call leg left of the deadline.
+    pending_timeout_msec: int | None = None
 
     def __init__(self) -> None:
         self._quit = False
@@ -141,6 +156,9 @@ class FakeConnection:
         self.version = version
         self.fd_responses = fd_responses or {"ConnectToEIS": _fresh_fd()}
         self.calls: list[tuple[str, Any]] = []
+        # Kept separate from `calls`, whose two-tuple shape several tests
+        # compare against exactly: (method, bus name, object path, timeout).
+        self.call_targets: list[tuple[str, Any, Any, Any]] = []
         self._unique_name = unique_name
         self._subscriptions: dict[str, Any] = {}
         self._pending_reply: tuple[str, int, dict[str, Any]] | None = None
@@ -168,6 +186,7 @@ class FakeConnection:
         # `parameters` is None for a method that takes no arguments, which
         # is exactly what real Gio expects and what Session.Close() sends.
         self.calls.append((method, None if parameters is None else parameters.value))
+        self.call_targets.append((method, bus_name, object_path, timeout))
         if parameters is None:
             return FakeReply(())
         if method == "Get":
@@ -242,6 +261,7 @@ class FakeConnection:
         cancellable: Any,
     ) -> tuple[FakeReply, FakeUnixFDList]:
         self.calls.append((method, parameters.value))
+        self.call_targets.append((method, bus_name, object_path, timeout))
         return FakeReply((0,)), FakeUnixFDList(self.fd_responses[method])
 
 
@@ -254,6 +274,9 @@ def install_fake_gi(connection: FakeConnection | None = None) -> Any:
     Gio.BusType = types.SimpleNamespace(SESSION=1)  # type: ignore[attr-defined]
     Gio.DBusCallFlags = types.SimpleNamespace(NONE=0)  # type: ignore[attr-defined]
     Gio.DBusSignalFlags = types.SimpleNamespace(NONE=0)  # type: ignore[attr-defined]
+    # 24 is G_IO_ERROR_TIMED_OUT, the code a real call_sync() raises in the
+    # g-io-error-quark domain when its reply never comes.
+    Gio.IOErrorEnum = types.SimpleNamespace(TIMED_OUT=24)  # type: ignore[attr-defined]
     Gio.bus_get_sync = (  # type: ignore[attr-defined]
         lambda *a, **kw: connection or FakeConnection()
     )
@@ -268,8 +291,9 @@ def install_fake_gi(connection: FakeConnection | None = None) -> Any:
 
     # timeout_add stashes the callback rather than scheduling it; only the
     # timeout tests, which never quit() the loop, actually let it fire.
-    def timeout_add(_ms: int, callback: Any) -> int:
+    def timeout_add(ms: int, callback: Any) -> int:
         FakeMainLoop.pending_timeout = callback
+        FakeMainLoop.pending_timeout_msec = ms
         return 1
 
     def source_remove(_id: int) -> None:
@@ -630,3 +654,266 @@ def test_a_failed_session_close_does_not_propagate() -> None:
     with install_fake_gi(connection):
         session = portal.RemoteDesktopSession.negotiate(connection=connection)
         session.close()  # must not raise
+
+
+def _closed_sessions(connection: FakeConnection) -> list[Any]:
+    """Object paths ``Session.Close()`` was called on, in order."""
+    return [call[2] for call in connection.call_targets if call[0] == "Close"]
+
+
+class _SilentAfterCreateConnection(FakeConnection):
+    """Answers CreateSession, then accepts Start and never responds.
+
+    Stands in for a portal that dies (or a compositor whose dialog never
+    returns) after a session already exists -- the case where a caller is
+    left holding nothing at all, since `negotiate` raises rather than
+    returning the object whose `close()` would clean up.
+    """
+
+    def call_sync(
+        self,
+        bus_name: Any,
+        object_path: Any,
+        interface: Any,
+        method: str,
+        parameters: FakeVariant | None,
+        reply_type: Any,
+        flags: Any,
+        timeout: Any,
+        cancellable: Any,
+    ) -> FakeReply:
+        if method == "Start":
+            self.calls.append((method, parameters.value if parameters else None))
+            self.call_targets.append((method, bus_name, object_path, timeout))
+            return FakeReply(())  # accepted, but no Response ever fires
+        return super().call_sync(
+            bus_name,
+            object_path,
+            interface,
+            method,
+            parameters,
+            reply_type,
+            flags,
+            timeout,
+            cancellable,
+        )
+
+
+def test_a_declined_select_devices_closes_the_portal_session() -> None:
+    # CreateSession has already created a session inside xdg-desktop-portal
+    # by this point, and nothing else will ever close it: negotiate() raises
+    # instead of returning the object whose close() would, and the session
+    # outlives the failure on the shared session-bus connection.
+    connection = FakeConnection(
+        responses={
+            "CreateSession": (0, {"session_handle": "/session/1"}),
+            "SelectDevices": (1, {}),
+        }
+    )
+    with install_fake_gi(connection):
+        with pytest.raises(portal.PortalDeniedError):
+            portal.RemoteDesktopSession.negotiate(connection=connection)
+    assert _closed_sessions(connection) == ["/session/1"]
+
+
+def test_a_declined_start_closes_the_portal_session() -> None:
+    # The most likely failure of the lot: the user says no to the consent
+    # dialog. An approved-then-declined session left open is a grant the
+    # portal keeps listing for a process that gave up on it.
+    connection = FakeConnection(
+        responses={
+            "CreateSession": (0, {"session_handle": "/session/1"}),
+            "SelectDevices": (0, {}),
+            "Start": (1, {}),
+        }
+    )
+    with install_fake_gi(connection):
+        with pytest.raises(portal.PortalDeniedError):
+            portal.RemoteDesktopSession.negotiate(connection=connection)
+    assert _closed_sessions(connection) == ["/session/1"]
+
+
+def test_a_timed_out_request_closes_the_portal_session() -> None:
+    connection = _SilentAfterCreateConnection()
+    with install_fake_gi(connection):
+        with pytest.raises(portal.PortalTimeoutError) as excinfo:
+            portal.RemoteDesktopSession.negotiate(connection=connection, timeout=0.01)
+    assert excinfo.value.step == "Start"
+    assert _closed_sessions(connection) == ["/session/1"]
+
+
+def test_a_failed_connect_to_eis_closes_the_portal_session() -> None:
+    # The last step, and the one with no Request of its own: a session that
+    # was fully approved and then failed to hand back an EIS fd is still a
+    # session, and still has to be closed.
+    class NoEisConnection(FakeConnection):
+        def call_with_unix_fd_list_sync(
+            self, *args: Any, **kwargs: Any
+        ) -> tuple[FakeReply, FakeUnixFDList]:
+            raise FakeGLibError("org.freedesktop.DBus.Error.Failed")
+
+    connection = NoEisConnection()
+    with install_fake_gi(connection):
+        with pytest.raises(portal.PortalError, match="D-Bus"):
+            portal.RemoteDesktopSession.negotiate(connection=connection)
+    assert _closed_sessions(connection) == ["/session/1"]
+
+
+def test_an_interrupted_consent_dialog_closes_the_portal_session() -> None:
+    # Why the cleanup catches BaseException: Start blocks on a human, so
+    # Ctrl-C during that wait is a routine way out of negotiate() -- and it
+    # strands an approved session exactly as a decline does.
+    class InterruptedConnection(FakeConnection):
+        def call_sync(
+            self,
+            bus_name: Any,
+            object_path: Any,
+            interface: Any,
+            method: str,
+            parameters: FakeVariant | None,
+            reply_type: Any,
+            flags: Any,
+            timeout: Any,
+            cancellable: Any,
+        ) -> FakeReply:
+            if method == "Start":
+                raise KeyboardInterrupt
+            return super().call_sync(
+                bus_name,
+                object_path,
+                interface,
+                method,
+                parameters,
+                reply_type,
+                flags,
+                timeout,
+                cancellable,
+            )
+
+    connection = InterruptedConnection()
+    with install_fake_gi(connection):
+        with pytest.raises(KeyboardInterrupt):
+            portal.RemoteDesktopSession.negotiate(connection=connection)
+    assert _closed_sessions(connection) == ["/session/1"]
+
+
+def test_a_successful_negotiation_closes_nothing() -> None:
+    # The other half of the cleanup: a session that negotiated fine belongs
+    # to the caller until they close it.
+    connection = FakeConnection()
+    with install_fake_gi(connection):
+        session = portal.RemoteDesktopSession.negotiate(connection=connection)
+        assert _closed_sessions(connection) == []
+        session.close()
+    assert _closed_sessions(connection) == ["/session/1"]
+
+
+def test_a_missing_session_handle_raises_portal_error() -> None:
+    # Approved, but with nothing to address the rest of the sequence to.
+    # A direct index would raise KeyError straight past `except PortalError`.
+    connection = FakeConnection(responses={"CreateSession": (0, {})})
+    with install_fake_gi(connection):
+        with pytest.raises(portal.PortalError, match="session_handle"):
+            portal.RemoteDesktopSession.negotiate(connection=connection)
+    # And nothing to close: no handle means no session to end.
+    assert _closed_sessions(connection) == []
+
+
+def test_the_session_is_closed_on_the_bus_name_it_was_negotiated_on() -> None:
+    # A session created on an alternate portal name has to be closed on
+    # that same name; sending Session.Close() to the default bus name
+    # reaches a portal that never heard of this session.
+    connection = FakeConnection()
+    with install_fake_gi(connection):
+        session = portal.RemoteDesktopSession.negotiate(
+            connection=connection, busname="org.example.Portal"
+        )
+        session.close()
+    closes = [call for call in connection.call_targets if call[0] == "Close"]
+    assert [call[1] for call in closes] == ["org.example.Portal"]
+
+
+def test_a_failed_negotiation_closes_on_the_bus_name_it_used() -> None:
+    connection = FakeConnection(
+        responses={
+            "CreateSession": (0, {"session_handle": "/session/1"}),
+            "SelectDevices": (1, {}),
+        }
+    )
+    with install_fake_gi(connection):
+        with pytest.raises(portal.PortalDeniedError):
+            portal.RemoteDesktopSession.negotiate(
+                connection=connection, busname="org.example.Portal"
+            )
+    closes = [call for call in connection.call_targets if call[0] == "Close"]
+    assert [call[1] for call in closes] == ["org.example.Portal"]
+
+
+def test_every_negotiation_call_is_bounded_by_the_callers_timeout() -> None:
+    # GDBus's -1 is not "no timeout" (that is G_MAXINT) but GIO's own 25s
+    # default -- a number this module never chose and a caller cannot see.
+    # Every leg carries the timeout the caller asked for instead, including
+    # ConnectToEIS, which returns no Request and so has no Response leg of
+    # its own for the nested loop to bound.
+    connection = FakeConnection()
+    with install_fake_gi(connection):
+        portal.RemoteDesktopSession.negotiate(connection=connection, timeout=12.0)
+    timeouts = {call[0]: call[3] for call in connection.call_targets}
+    assert timeouts["Get"] == 12_000
+    assert timeouts["ConnectToEIS"] == 12_000
+    # The Request-returning legs draw on a shared deadline, so they get at
+    # most the full timeout, never more, and never GIO's default.
+    for method in ("CreateSession", "SelectDevices", "Start"):
+        assert 0 < timeouts[method] <= 12_000
+
+
+def test_the_response_wait_gets_only_what_the_call_leg_left(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # One deadline covers the whole round trip. Bounding each leg by the
+    # full timeout separately would let a request that spent 4s getting its
+    # handle wait another 10s for the Response -- 14 seconds, asked for 10.
+    class Clock:
+        def __init__(self) -> None:
+            self.now = 100.0
+
+        def __call__(self) -> float:
+            return self.now
+
+    clock = Clock()
+
+    class SlowCallConnection(_SilentAfterCreateConnection):
+        """Takes 4s to answer Start, then never sends a Response."""
+
+        def call_sync(self, *args: Any, **kwargs: Any) -> FakeReply:
+            reply = super().call_sync(*args, **kwargs)
+            if args[3] == "Start":
+                clock.now += 4.0
+            return reply
+
+    # portal.py reads the stdlib clock directly, so this is the one to
+    # replace -- and replacing it beats sleeping for the real 4 seconds.
+    monkeypatch.setattr(time, "monotonic", clock)
+    connection = SlowCallConnection()
+    with install_fake_gi(connection):
+        with pytest.raises(portal.PortalTimeoutError):
+            portal.RemoteDesktopSession.negotiate(connection=connection, timeout=10.0)
+    assert FakeMainLoop.pending_timeout_msec == 6_000
+
+
+def test_a_dbus_reply_timeout_raises_portal_timeout_error() -> None:
+    # GDBus reports its own reply timeout as G_IO_ERROR_TIMED_OUT in the
+    # g-io-error-quark domain -- not as an org.freedesktop.DBus.Error.*
+    # code -- and it means what the nested loop's timeout means: nobody
+    # answered in time. So it raises what a caller catches for that.
+    class TimingOutConnection(FakeConnection):
+        def call_sync(self, *args: Any, **kwargs: Any) -> FakeReply:
+            raise FakeGLibError(
+                "Timeout was reached", domain="g-io-error-quark", code=24
+            )
+
+    connection = TimingOutConnection()
+    with install_fake_gi(connection):
+        with pytest.raises(portal.PortalTimeoutError) as excinfo:
+            portal.RemoteDesktopSession.negotiate(connection=connection, timeout=30.0)
+    assert excinfo.value.step == "Get"