fix: prepare transient controls inside native action sequences

artemis/mcp/actuators/adb.py

@@ -256,6 +256,37 @@ class AdbActuator:
             receipt["completed_taps"] += 1
         return None
 
+    async def _ensure_visible_target(self, step: dict, receipt: dict) -> None:
+        """Prepare explicit UI once; poll only reads, never retry the opener."""
+        receipt.update(execution="not_started", completed_taps=0, visibility_attempts=0)
+        elements = await self._live_ui_elements()
+        guard = await self._visibility_guard(step["target"], elements)
+        receipt["visibility_guard"] = guard
+        receipt["visibility_attempts"] += 1
+        if guard["visible"]:
+            self._live_target_coordinates(step["target"], elements)
+            receipt["execution"] = "skipped"
+            return
+        error = await self._tap_native_target(step["opener"], receipt, elements=elements)
+        if error:
+            raise RuntimeError(error)
+        try:
+            async with asyncio.timeout(step["timeout_ms"] / 1000):
+                while True:
+                    elements = await self._live_ui_elements()
+                    guard = await self._visibility_guard(step["target"], elements)
+                    receipt["visibility_guard"] = guard
+                    receipt["visibility_attempts"] += 1
+                    if guard["visible"]:
+                        self._live_target_coordinates(step["target"], elements)
+                        receipt["execution"] = "completed"
+                        return
+                    await asyncio.sleep(0.1)
+        except TimeoutError as exc:
+            raise TimeoutError(
+                f"Panel target {step['target']} did not become visible within {step['timeout_ms']}ms after one opener tap. No opener retry; re-observe before continuing."
+            ) from exc
+
     async def action_sequence(self, steps: list[Any]) -> ActionResult:
         """Execute once; optional visibility guards read live UI without model turns."""
         import time
@@ -296,7 +327,20 @@ class AdbActuator:
                 receipt["execution"] = "unknown"
                 member_execution = "completed"
                 try:
-                    if step["action"] == "click":
+                    if step["action"] == "ensure_visible":
+                        try:
+                            await self._ensure_visible_target(step, receipt)
+                            member_execution = receipt["execution"]
+                            error = None
+                        except (LookupError, TimeoutError) as exc:
+                            error = str(exc)
+                            member_execution = receipt["execution"]
+                            failed_code = (
+                                ActionCode.TIMEOUT
+                                if isinstance(exc, TimeoutError)
+                                else ActionCode.TARGET_NOT_FOUND
+                            )
+                    elif step["action"] == "click":
                         guard = None
                         elements = None
                         error = None
@@ -396,7 +440,7 @@ class AdbActuator:
             )
         return ActionResult.success(
             "action_sequence",
-            f"Executed {completed} gesture steps consecutively; skipped {skipped} unnecessary opener clicks. Verify actual ticks/handle endpoints in the final screen.",
+            f"Executed {completed} gesture steps consecutively; skipped {skipped} unnecessary UI-opening steps. Verify the intended result in the final screen.",
             metadata=metadata,
         )