Stage 3 review: clear passes through when unbound, like the rest

The pass-through guard reached every intercepted method except this one. A
retained delegating wrapper therefore had a retired bridge take its lock and
invalidate its state on someone else's behalf -- and taking the lock is not
harmless: the caller may hold a higher-level lock, and the ordering rule
forbids that nesting, so acting as owner turned someone else's clear into an
exception.

The test could not have caught it. It asserted the delegated call returned,
which it did whenever nothing else held a lock. It now asserts what the guard
is actually for: no terminal transaction is taken, under a higher-level lock,
and the retired bridge's own state is left alone.

Author: tleonhardt

cmd2/prompt_toolkit_bridge.py

@@ -546,7 +546,14 @@ def _clear_through_bridge(self) -> None:
         the remembered origin is forgotten rather than carried across -- recovery would
         otherwise place the next frame where the prompt used to be. Cursor reports already in
         flight describe the screen before the clear and are discarded with it.
+
+        Unbound, this passes straight through, for the reason given on the render wrapper: a
+        retired bridge is not the terminal's owner, and taking its lock or invalidating its
+        state on someone else's behalf would be acting as one.
         """
+        if not self._bound:
+            self._originals["clear"]()
+            return
         self._last_emission_committed = False
         with self._lock.transaction("clear"):
             try:

tests/test_prompt_toolkit_bridge.py

@@ -32,7 +32,7 @@
     ReservedModeFailureError,
 )
 from cmd2.terminal_display import TerminalDisplay
-from cmd2.terminal_transaction import TerminalLock, current_transaction
+from cmd2.terminal_transaction import HigherLevelLock, TerminalLock, current_transaction
 
 
 class TtyStringIO(io.StringIO):
@@ -1514,7 +1514,13 @@ def tracing_fire() -> None:
         assert fired == [1]
         assert handled == [1]
 
-    def test_delegated_erase_and_clear_still_work_after_unbinding(self) -> None:
+    def test_delegated_erase_and_clear_take_no_transaction_after_unbinding(self) -> None:
+        """A retired bridge is not the terminal's owner and must not act as one.
+
+        Taking its lock is not harmless: the caller may hold a higher-level lock, and the
+        ordering rule forbids that nesting -- so acting as owner turns someone else's clear
+        into an exception.
+        """
         harness = self.bound()
         harness.renderer.request_absolute_cursor_position = lambda: None  # type: ignore[method-assign]
         erase, clear = harness.renderer.erase, harness.renderer.clear
@@ -1528,11 +1534,33 @@ def passing_clear() -> None:
         harness.renderer.erase = passing_erase  # type: ignore[method-assign]
         harness.renderer.clear = passing_clear  # type: ignore[method-assign]
         harness.bridge.unbind()
+        harness.bridge.require_resynchronization("before the delegated calls")
 
-        with set_app(harness.app):
+        harness.stream_recorder.transactions.clear()
+        with set_app(harness.app), HigherLevelLock("routing"):
             harness.renderer.erase()
             harness.renderer.clear()
 
+        assert harness.stream_recorder.transactions
+        assert all(state is None for state in harness.stream_recorder.transactions)
+
+    def test_a_delegated_clear_does_not_invalidate_the_retired_bridge(self) -> None:
+        """Its state describes a terminal it no longer owns; changing it means nothing."""
+        harness = self.bound()
+        harness.renderer.request_absolute_cursor_position = lambda: None  # type: ignore[method-assign]
+        harness.bridge.set_prompt_anchor(7)
+        clear = harness.renderer.clear
+
+        def passing_clear() -> None:
+            clear()
+
+        harness.renderer.clear = passing_clear  # type: ignore[method-assign]
+        harness.bridge.unbind()
+
+        with set_app(harness.app):
+            harness.renderer.clear()
+        assert harness.bridge.prompt_anchor == 7
+
     def test_delegated_cursor_reports_still_work_after_unbinding(self) -> None:
         harness = self.bound()
         request = harness.renderer.request_absolute_cursor_position