mobile-debug-mcp 0.36.0 → 0.37.0

package/test/fixtures/contracts/tool-definitions.json

@@ -883,9 +883,40 @@
       ]
     }
   },
+  {
+    "name": "get_interaction_diagnostics",
+    "description": "Read the retained original interaction or journey result without replaying input or observing the device. Pass diagnostics.session_id/result_id as sessionId/resultId. Session-local memory: ten minutes, 100 results, 16 MiB total, 1 MiB per result. Expired, evicted or restarted results are unavailable. May contain private UI text and errors; compact output is not redaction.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "sessionId",
+        "resultId"
+      ],
+      "properties": {
+        "sessionId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "resultId": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "allOf": [
+        {
+          "not": {
+            "required": [
+              "expectedState"
+            ]
+          }
+        }
+      ]
+    }
+  },
   {
     "name": "get_app_readiness",
-    "description": "Observe readiness with at most two fresh UI-tree samples. Reports loading, transitioning, settled or unknown with evidence and limitations. Managed Android debugger pauses are reported from debugger evidence; unresponsive detection remains unsupported. Settled normalized foreground UI is not proof of app identity, responsiveness or backend completion.",
+    "description": "Observe readiness with at most two fresh UI-tree samples. Reports loading, transitioning, settled or unknown with evidence and limitations. Managed Android and supported iOS simulator debugger pauses are reported from debugger evidence; unresponsive detection remains unsupported. Settled normalized foreground UI is not proof of app identity, responsiveness or backend completion.\nResults include device_readiness with timestamped device blocker evidence. Android reports supported power/keyguard signals; iOS signals may be unknown or explicitly unsupported. Launch/input dispatch success does not establish app visibility or input readiness. No automatic unlock or wake is performed.",
     "inputSchema": {
       "type": "object",
       "additionalProperties": false,
@@ -930,7 +961,7 @@
   },
   {
     "name": "wait_for_app_ready",
-    "description": "Wait within a single bounded budget for settled UI evidence. Reports loading, transitioning, settled or unknown with evidence and limitations. Managed Android debugger pauses are reported from debugger evidence; unresponsive detection remains unsupported. Settled normalized foreground UI is not proof of app identity, responsiveness or backend completion.",
+    "description": "Wait within a single bounded budget for settled UI evidence. Reports loading, transitioning, settled or unknown with evidence and limitations. Managed Android and supported iOS simulator debugger pauses are reported from debugger evidence; unresponsive detection remains unsupported. Settled normalized foreground UI is not proof of app identity, responsiveness or backend completion.\nResults include device_readiness with timestamped device blocker evidence. Android reports supported power/keyguard signals; iOS signals may be unknown or explicitly unsupported. Launch/input dispatch success does not establish app visibility or input readiness. No automatic unlock or wake is performed.",
     "inputSchema": {
       "type": "object",
       "additionalProperties": false,
@@ -981,7 +1012,7 @@
   },
   {
     "name": "start_app",
-    "description": "Purpose:\nLaunch a mobile app on Android or iOS.\n\nInputs:\n- platform\n- appId\n- deviceId (optional)\n\nOutput Structure:\n - action_id, timestamp (ISO 8601), action_type\n - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n - source_module: runtime source of the action envelope\n - target.selector = { appId }\n- success = true when launch was dispatched successfully\n- failure_code/retryable when launch dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Define the expected landing screen when it is known\n2. Call start_app\n3. If needed, wait for transition using wait_for_*\n4. Verify with expect_screen\n5. If verification fails, retry once or capture a snapshot\n\nVerification Guidance:\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- expect_screen is the authoritative verification step when the landing screen is known\n- Do not treat timing or screen change alone as final verification\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → inspect snapshot/logs before retrying",
+    "description": "Purpose:\nLaunch a mobile app on Android or iOS.\n\nInputs:\n- platform\n- appId\n- deviceId (optional)\n\nOutput Structure:\n - action_id, timestamp (ISO 8601), action_type\n - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n - source_module: runtime source of the action envelope\n - target.selector = { appId }\n- success = true when launch was dispatched successfully\n- failure_code/retryable when launch dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Define the expected landing screen when it is known\n2. Call start_app\n3. If needed, wait for transition using wait_for_*\n4. Verify with expect_screen\n5. If verification fails, retry once or capture a snapshot\n\nVerification Guidance:\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- expect_screen is the authoritative verification step when the landing screen is known\n- Do not treat timing or screen change alone as final verification\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → inspect snapshot/logs before retrying\nCompact results summarize observations, condition trees, state deltas and readiness probe evidence within a byte budget. Use get_interaction_diagnostics with the returned diagnostics session_id/result_id to retrieve the original result without replaying input. Debug output is unchanged.\nResults include device_readiness with timestamped device blocker evidence. Android reports supported power/keyguard signals; iOS signals may be unknown or explicitly unsupported. Launch/input dispatch success does not establish app visibility or input readiness. No automatic unlock or wake is performed.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -1080,7 +1111,7 @@
   },
   {
     "name": "restart_app",
-    "description": "Purpose:\nRestart a mobile app on Android or iOS.\n\nInputs:\n- platform\n- appId\n- deviceId (optional)\n\nOutput Structure:\n - action_id, timestamp (ISO 8601), action_type\n - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n - source_module: runtime source of the action envelope\n - target.selector = { appId }\n- success = true when the restart command completed\n- failure_code/retryable when restart dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Define the expected landing screen when it is known\n2. Call restart_app\n3. If needed, wait for transition using wait_for_*\n4. Verify with expect_screen\n5. If verification fails, retry once or capture a snapshot\n\nVerification Guidance:\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- expect_screen is the authoritative verification step when the reopened screen is known\n- Do not treat timing or screen change alone as final verification\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → inspect snapshot/logs before retrying",
+    "description": "Purpose:\nRestart a mobile app on Android or iOS.\n\nInputs:\n- platform\n- appId\n- deviceId (optional)\n\nOutput Structure:\n - action_id, timestamp (ISO 8601), action_type\n - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n - source_module: runtime source of the action envelope\n - target.selector = { appId }\n- success = true when the restart command completed\n- failure_code/retryable when restart dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Define the expected landing screen when it is known\n2. Call restart_app\n3. If needed, wait for transition using wait_for_*\n4. Verify with expect_screen\n5. If verification fails, retry once or capture a snapshot\n\nVerification Guidance:\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- expect_screen is the authoritative verification step when the reopened screen is known\n- Do not treat timing or screen change alone as final verification\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → inspect snapshot/logs before retrying\nCompact results summarize observations, condition trees, state deltas and readiness probe evidence within a byte budget. Use get_interaction_diagnostics with the returned diagnostics session_id/result_id to retrieve the original result without replaying input. Debug output is unchanged.\nResults include device_readiness with timestamped device blocker evidence. Android reports supported power/keyguard signals; iOS signals may be unknown or explicitly unsupported. Launch/input dispatch success does not establish app visibility or input readiness. No automatic unlock or wake is performed.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -1361,7 +1392,7 @@
   },
   {
     "name": "list_devices",
-    "description": "List connected devices and their metadata (android + ios).",
+    "description": "List Android devices and iOS simulators. Supply appId for device-specific installation status; unknown checks do not imply absence.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -1371,6 +1402,11 @@
             "android",
             "ios"
           ]
+        },
+        "appId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]+(\\.[A-Za-z0-9_-]+)*$",
+          "description": "Optional package or bundle identifier to check on each device."
         }
       },
       "allOf": [
@@ -1829,7 +1865,7 @@
   },
   {
     "name": "wait_for_ui_change",
-    "description": "Purpose:\nWait for a non-navigation UI mutation or in-place update to become stable.\n\nInputs:\n- expected_change (optional): hierarchy_diff, text_change, or state_change\n- timeout_ms (optional)\n- stability_window_ms (optional)\n- scope (optional): screen or subtree\n- target (optional): element_id when scope=subtree\n\nGuidance:\n- Prefer wait_for_screen_change for navigation transitions.\n- Prefer wait_for_ui_change for in-place mutations and non-navigation updates.\n- Use the returned snapshot_revision as the observed synchronization point when available.\n- Scoped waits return scope-aware stability metadata and a lightweight change summary.\n\nFailure Handling:\n- TIMEOUT means the UI did not change in a stable way within the allotted time.\nSet requireReady=true to require both the existing predicate and settled UI readiness, using the same fresh samples and one timeout budget. The readiness summary explains uncertainty. Default predicate semantics are unchanged.",
+    "description": "Purpose:\nWait for a non-navigation UI mutation or in-place update to become stable.\n\nInputs:\n- expected_change (optional): hierarchy_diff, text_change, or state_change\n- timeout_ms (optional)\n- stability_window_ms (optional)\n- scope (optional): screen or subtree\n- target (optional): element_id when scope=subtree\n\nGuidance:\n- Prefer wait_for_screen_change for navigation transitions.\n- Prefer wait_for_ui_change for in-place mutations and non-navigation updates.\n- Use the returned snapshot_revision as the observed synchronization point when available.\n- Scoped waits return scope-aware stability metadata and a lightweight change summary.\n\nFailure Handling:\n- TIMEOUT means the UI did not change in a stable way within the allotted time.\nDevice-readiness blockers prevent readiness success; unknown/unsupported device signals remain explicit.\nSet requireReady=true to require both the existing predicate and settled UI readiness, using the same fresh samples and one timeout budget. The readiness summary explains uncertainty. Default predicate semantics are unchanged.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -2073,7 +2109,7 @@
   },
   {
     "name": "adjust_control",
-    "description": "Purpose:\nAdjust a numeric control value with verification.\n\nThis is the initial adjustable-control surface for slider-like controls and other controls that expose a numeric value or value_range.\n\nInputs:\n- exactly one of selector or element_id\n- property (defaults to \"value\")\n- targetValue\n- tolerance (optional; discrete default is 0, continuous default is max(step / 2, 1% of range) when omitted)\n- maxAttempts (optional; defaults to 5)\n- platform/deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target_state / actual_state / within_tolerance / converged / attempts / adjustment_mode\n- target.selector = original selector or element handle\n- success = true when the control converges within tolerance\n\nVerification Guidance:\n- Prefer direct platform adjustment when the runtime exposes it; then verified increment/decrement actions; use coordinate fallback only as degraded mode\n- Use expect_state for the control value readback\n- Do not use derived semantic metadata as proof of success\n\nFailure Handling:\n- ELEMENT_NOT_FOUND → re-resolve the control\n- ELEMENT_NOT_INTERACTABLE → the control cannot be adjusted through the current runtime\n- CONTROL_CONVERGENCE_FAILED → the control did not converge within bounded retries or the requested value is out of range\n- UNKNOWN → capture a snapshot and stop",
+    "description": "Purpose:\nAdjust a numeric control value with verification.\n\nThis is the initial adjustable-control surface for slider-like controls and other controls that expose a numeric value or value_range.\n\nInputs:\n- exactly one of selector or element_id\n- property (defaults to \"value\")\n- targetValue\n- tolerance (optional; discrete default is 0, continuous default is max(step / 2, 1% of range) when omitted)\n- maxAttempts (optional; defaults to 5)\n- platform/deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target_state / actual_state / within_tolerance / converged / attempts / adjustment_mode\n- target.selector = original selector or element handle\n- success = true when the control converges within tolerance\n\nVerification Guidance:\n- Prefer direct platform adjustment when the runtime exposes it; then verified increment/decrement actions; use coordinate fallback only as degraded mode\n- Use expect_state for the control value readback\n- Do not use derived semantic metadata as proof of success\n\nFailure Handling:\n- ELEMENT_NOT_FOUND → re-resolve the control\n- ELEMENT_NOT_INTERACTABLE → the control cannot be adjusted through the current runtime\n- CONTROL_CONVERGENCE_FAILED → the control did not converge within bounded retries or the requested value is out of range\n- UNKNOWN → capture a snapshot and stop\nResults include device_readiness with timestamped device blocker evidence. Android reports supported power/keyguard signals; iOS signals may be unknown or explicitly unsupported. Launch/input dispatch success does not establish app visibility or input readiness. No automatic unlock or wake is performed.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -2158,7 +2194,7 @@
   },
   {
     "name": "wait_for_ui",
-    "description": "Purpose:\nResolve elements and/or detect that a UI transition or availability condition has occurred.\n\nCapabilities:\n- Deterministic element resolution\n- Synchronization when element timing or availability is uncertain\n\nConstraints:\n- Does not verify correctness of the resulting state\n- Must not be used alone to confirm action success when an applicable expect_* tool exists\n\nRecommended Usage:\n1. Use wait_for_ui to resolve an element before acting or to wait for UI readiness\n2. Call the action tool\n3. If the expected outcome is known, follow with expect_* as final verification\nSet requireReady=true to require both the existing predicate and settled UI readiness, using the same fresh samples and one timeout budget. The readiness summary explains uncertainty. Default predicate semantics are unchanged.",
+    "description": "Purpose:\nResolve elements and/or detect that a UI transition or availability condition has occurred.\n\nCapabilities:\n- Deterministic element resolution\n- Synchronization when element timing or availability is uncertain\n\nConstraints:\n- Does not verify correctness of the resulting state\n- Must not be used alone to confirm action success when an applicable expect_* tool exists\n\nRecommended Usage:\n1. Use wait_for_ui to resolve an element before acting or to wait for UI readiness\n2. Call the action tool\n3. If the expected outcome is known, follow with expect_* as final verification\nDevice-readiness blockers prevent readiness success; unknown/unsupported device signals remain explicit.\nSet requireReady=true to require both the existing predicate and settled UI readiness, using the same fresh samples and one timeout budget. The readiness summary explains uncertainty. Default predicate semantics are unchanged.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -2297,7 +2333,7 @@
   },
   {
     "name": "tap",
-    "description": "Purpose:\nDispatch a tap at specific screen coordinates.\n\nInputs:\n- x, y coordinates\n- platform (optional)\n- deviceId (optional)\n\nOutput Structure:\n - action_id, timestamp (ISO 8601), action_type\n - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n - source_module: runtime source of the action envelope\n - target.selector = { x, y }\n- success = true when the tap was dispatched\n- failure_code/retryable when dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Resolve coordinates deterministically\n2. Call tap\n3. If needed, wait for transition using wait_for_*\n4. Verify with expect_screen or expect_element_visible depending on the intended outcome\n\nVerification Guidance:\n- Prefer tap_element over tap when an element can be resolved\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Use expect_screen for navigation and expect_element_visible for local UI changes\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → capture a snapshot and stop\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures include the fresh UI tree. This is not atomic with OS input delivery.",
+    "description": "Purpose:\nDispatch a tap at specific screen coordinates.\n\nInputs:\n- x, y coordinates\n- platform (optional)\n- deviceId (optional)\n\nOutput Structure:\n - action_id, timestamp (ISO 8601), action_type\n - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n - source_module: runtime source of the action envelope\n - target.selector = { x, y }\n- success = true when the tap was dispatched\n- failure_code/retryable when dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Resolve coordinates deterministically\n2. Call tap\n3. If needed, wait for transition using wait_for_*\n4. Verify with expect_screen or expect_element_visible depending on the intended outcome\n\nVerification Guidance:\n- Prefer tap_element over tap when an element can be resolved\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Use expect_screen for navigation and expect_element_visible for local UI changes\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → capture a snapshot and stop\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures summarize the fresh condition evidence; use get_interaction_diagnostics with the returned diagnostics reference for the retained UI tree. This is not atomic with OS input delivery.\nCompact results summarize observations, condition trees, state deltas and readiness probe evidence within a byte budget. Use get_interaction_diagnostics with the returned diagnostics session_id/result_id to retrieve the original result without replaying input. Debug output is unchanged.\nResults include device_readiness with timestamped device blocker evidence. Android reports supported power/keyguard signals; iOS signals may be unknown or explicitly unsupported. Launch/input dispatch success does not establish app visibility or input readiness. No automatic unlock or wake is performed.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -2414,7 +2450,7 @@
   },
   {
     "name": "tap_element",
-    "description": "Purpose:\nTap a previously resolved UI element using its elementId.\n\nInputs:\n- elementId: a resolved UI element identifier returned by wait_for_ui\n\nOutput Structure:\n- action_id: unique timestamp-based action identifier\n- timestamp: ISO 8601 timestamp for the action attempt\n- action_type: \"tap_element\"\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector: original target handle ({ elementId })\n- target.resolved: minimal resolved element info used for the tap\n- success: true when the tap was dispatched\n- failure_code: present when success=false\n- retryable: present when failure_code exists\n- ui_fingerprint_before/ui_fingerprint_after: optional fingerprints captured around the action\n\nRecommended Usage:\n1. Resolve the target with wait_for_ui or another deterministic resolver\n2. Call tap_element\n3. If needed, wait for transition using wait_for_*\n4. Verify outcome using expect_*\n   - use expect_screen when navigation is expected\n   - use expect_element_visible when the UI change is local\n5. If verification fails, inspect failure_code and follow the retry strategy below\n\nVerification Guidance:\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Prefer expect_screen for navigation or modal transitions\n- Prefer expect_element_visible when the tap should reveal or update a specific element\n- wait_for_* may be used for resolution and synchronization, but not as the final verification step when an applicable expect_* tool exists\n- Do not treat tap_element.success as outcome success; it only means the tap was executed\n\nFailure Handling:\n- STALE_REFERENCE → re-resolve the element, then retry\n- ELEMENT_NOT_INTERACTABLE → wait or refine the target, then retry\n- UNKNOWN → capture a snapshot and stop\n\nThis tool reports execution success only. Verification must be done with a separate expect_* tool.\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures include the fresh UI tree. This is not atomic with OS input delivery.",
+    "description": "Purpose:\nTap a previously resolved UI element using its elementId.\n\nInputs:\n- elementId: a resolved UI element identifier returned by wait_for_ui\n\nOutput Structure:\n- action_id: unique timestamp-based action identifier\n- timestamp: ISO 8601 timestamp for the action attempt\n- action_type: \"tap_element\"\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector: original target handle ({ elementId })\n- target.resolved: minimal resolved element info used for the tap\n- success: true when the tap was dispatched\n- failure_code: present when success=false\n- retryable: present when failure_code exists\n- ui_fingerprint_before/ui_fingerprint_after: optional fingerprints captured around the action\n\nRecommended Usage:\n1. Resolve the target with wait_for_ui or another deterministic resolver\n2. Call tap_element\n3. If needed, wait for transition using wait_for_*\n4. Verify outcome using expect_*\n   - use expect_screen when navigation is expected\n   - use expect_element_visible when the UI change is local\n5. If verification fails, inspect failure_code and follow the retry strategy below\n\nVerification Guidance:\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Prefer expect_screen for navigation or modal transitions\n- Prefer expect_element_visible when the tap should reveal or update a specific element\n- wait_for_* may be used for resolution and synchronization, but not as the final verification step when an applicable expect_* tool exists\n- Do not treat tap_element.success as outcome success; it only means the tap was executed\n\nFailure Handling:\n- STALE_REFERENCE → re-resolve the element, then retry\n- ELEMENT_NOT_INTERACTABLE → wait or refine the target, then retry\n- UNKNOWN → capture a snapshot and stop\n\nThis tool reports execution success only. Verification must be done with a separate expect_* tool.\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures summarize the fresh condition evidence; use get_interaction_diagnostics with the returned diagnostics reference for the retained UI tree. This is not atomic with OS input delivery.\nCompact results summarize observations, condition trees, state deltas and readiness probe evidence within a byte budget. Use get_interaction_diagnostics with the returned diagnostics session_id/result_id to retrieve the original result without replaying input. Debug output is unchanged.\nResults include device_readiness with timestamped device blocker evidence. Android reports supported power/keyguard signals; iOS signals may be unknown or explicitly unsupported. Launch/input dispatch success does not establish app visibility or input readiness. No automatic unlock or wake is performed.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -2591,7 +2627,7 @@
   },
   {
     "name": "swipe",
-    "description": "Purpose:\nDispatch a swipe gesture on Android or iOS.\n\nInputs:\n- start and end coordinates\n- duration\n- platform/deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector = { x1, y1, x2, y2, duration }\n- success = true when the swipe was dispatched\n- failure_code/retryable when dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Determine swipe coordinates\n2. Call swipe\n3. If needed, wait for transition using wait_for_*\n4. Verify with expect_screen or expect_element_visible when a deterministic outcome is expected\n\nVerification Guidance:\n- Swipe outcomes are less predictable; choose the most specific verifier available for the intended effect\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → capture a snapshot and stop\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures include the fresh UI tree. This is not atomic with OS input delivery.",
+    "description": "Purpose:\nDispatch a swipe gesture on Android or iOS.\n\nInputs:\n- start and end coordinates\n- duration\n- platform/deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector = { x1, y1, x2, y2, duration }\n- success = true when the swipe was dispatched\n- failure_code/retryable when dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Determine swipe coordinates\n2. Call swipe\n3. If needed, wait for transition using wait_for_*\n4. Verify with expect_screen or expect_element_visible when a deterministic outcome is expected\n\nVerification Guidance:\n- Swipe outcomes are less predictable; choose the most specific verifier available for the intended effect\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → capture a snapshot and stop\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures summarize the fresh condition evidence; use get_interaction_diagnostics with the returned diagnostics reference for the retained UI tree. This is not atomic with OS input delivery.\nCompact results summarize observations, condition trees, state deltas and readiness probe evidence within a byte budget. Use get_interaction_diagnostics with the returned diagnostics session_id/result_id to retrieve the original result without replaying input. Debug output is unchanged.\nResults include device_readiness with timestamped device blocker evidence. Android reports supported power/keyguard signals; iOS signals may be unknown or explicitly unsupported. Launch/input dispatch success does not establish app visibility or input readiness. No automatic unlock or wake is performed.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -2723,7 +2759,7 @@
   },
   {
     "name": "scroll_to_element",
-    "description": "Purpose:\nScroll until a target element becomes visible.\n\nInputs:\n- platform\n- selector\n- direction, maxScrolls, scrollAmount, deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector = original selector\n- target.resolved = minimal resolved element info when found\n- success = true when scrolling produced a visible target element\n- failure_code/retryable when the target was not reached\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Resolve the target selector\n2. Call scroll_to_element\n3. If needed, wait for UI stabilization using wait_for_*\n4. Verify with expect_element_visible when the expected element visibility is known\n5. If success=false, follow failure handling before retrying\n\nVerification Guidance:\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Use expect_element_visible when you need an explicit post-scroll confirmation\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- NAVIGATION_NO_CHANGE → adjust scroll direction or stop\n- TIMEOUT → retry with refined selector or larger scroll budget\n- UNKNOWN → capture a snapshot and stop",
+    "description": "Purpose:\nScroll until a target element becomes visible.\n\nInputs:\n- platform\n- selector\n- direction, maxScrolls, scrollAmount, deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector = original selector\n- target.resolved = minimal resolved element info when found\n- success = true when scrolling produced a visible target element\n- failure_code/retryable when the target was not reached\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Resolve the target selector\n2. Call scroll_to_element\n3. If needed, wait for UI stabilization using wait_for_*\n4. Verify with expect_element_visible when the expected element visibility is known\n5. If success=false, follow failure handling before retrying\n\nVerification Guidance:\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Use expect_element_visible when you need an explicit post-scroll confirmation\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- NAVIGATION_NO_CHANGE → adjust scroll direction or stop\n- TIMEOUT → retry with refined selector or larger scroll budget\n- UNKNOWN → capture a snapshot and stop\nCompact results summarize observations, condition trees, state deltas and readiness probe evidence within a byte budget. Use get_interaction_diagnostics with the returned diagnostics session_id/result_id to retrieve the original result without replaying input. Debug output is unchanged.\nResults include device_readiness with timestamped device blocker evidence. Android reports supported power/keyguard signals; iOS signals may be unknown or explicitly unsupported. Launch/input dispatch success does not establish app visibility or input readiness. No automatic unlock or wake is performed.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -2815,7 +2851,7 @@
   },
   {
     "name": "type_text",
-    "description": "Purpose:\nType text into the currently focused Android input field.\n\nInputs:\n- text\n- platform/deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector = { text }\n- success = true when text input was dispatched\n- failure_code/retryable when dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Resolve or focus the target input first\n2. Call type_text\n3. If needed, wait for UI stabilization using wait_for_*\n4. Verify with expect_element_visible or expect_screen, depending on the intended outcome\n\nVerification Guidance:\n- Prefer verifying the next expected element or screen state instead of inferring success from the text action alone\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → re-focus the input or capture a snapshot\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures include the fresh UI tree. This is not atomic with OS input delivery.",
+    "description": "Purpose:\nType text into the currently focused Android input field.\n\nInputs:\n- text\n- platform/deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector = { text }\n- success = true when text input was dispatched\n- failure_code/retryable when dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Resolve or focus the target input first\n2. Call type_text\n3. If needed, wait for UI stabilization using wait_for_*\n4. Verify with expect_element_visible or expect_screen, depending on the intended outcome\n\nVerification Guidance:\n- Prefer verifying the next expected element or screen state instead of inferring success from the text action alone\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → re-focus the input or capture a snapshot\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures summarize the fresh condition evidence; use get_interaction_diagnostics with the returned diagnostics reference for the retained UI tree. This is not atomic with OS input delivery.\nCompact results summarize observations, condition trees, state deltas and readiness probe evidence within a byte budget. Use get_interaction_diagnostics with the returned diagnostics session_id/result_id to retrieve the original result without replaying input. Debug output is unchanged.\nResults include device_readiness with timestamped device blocker evidence. Android reports supported power/keyguard signals; iOS signals may be unknown or explicitly unsupported. Launch/input dispatch success does not establish app visibility or input readiness. No automatic unlock or wake is performed.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -2925,7 +2961,7 @@
   },
   {
     "name": "press_back",
-    "description": "Purpose:\nDispatch the Android Back action.\n\nInputs:\n- platform/deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector = { key: \"back\" }\n- success = true when the back action was dispatched\n- failure_code/retryable when dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Call press_back\n2. If needed, wait for transition using wait_for_*\n3. Verify with expect_screen when a known destination is expected\n4. If verification fails, retry once or recover explicitly\n\nVerification Guidance:\n- Back outcomes can vary by screen, so verify against the intended destination when possible\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → capture a snapshot and stop\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures include the fresh UI tree. This is not atomic with OS input delivery.",
+    "description": "Purpose:\nDispatch the Android Back action.\n\nInputs:\n- platform/deviceId (optional)\n\nOutput Structure:\n- action_id, timestamp (ISO 8601), action_type\n- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)\n- source_module: runtime source of the action envelope\n- target.selector = { key: \"back\" }\n- success = true when the back action was dispatched\n- failure_code/retryable when dispatch fails\n- ui_fingerprint_before/ui_fingerprint_after when available\n\nRecommended Usage:\n1. Call press_back\n2. If needed, wait for transition using wait_for_*\n3. Verify with expect_screen when a known destination is expected\n4. If verification fails, retry once or recover explicitly\n\nVerification Guidance:\n- Back outcomes can vary by screen, so verify against the intended destination when possible\n- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT\n- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists\n\nFailure Handling:\n- TIMEOUT → retry once\n- UNKNOWN → capture a snapshot and stop\n\nConditional input: optionally supply expectedState { snapshotSessionId, snapshotRevision, timeoutMs? } from a successful get_ui_tree on the same explicit platform/deviceId. A fresh normalized UI-tree check runs immediately before input, even with verification disabled. PRECONDITION_FAILED or PRECONDITION_UNAVAILABLE means no input was dispatched; inspect condition evidence and re-observe before deciding what to do next. Compact failures summarize the fresh condition evidence; use get_interaction_diagnostics with the returned diagnostics reference for the retained UI tree. This is not atomic with OS input delivery.\nCompact results summarize observations, condition trees, state deltas and readiness probe evidence within a byte budget. Use get_interaction_diagnostics with the returned diagnostics session_id/result_id to retrieve the original result without replaying input. Debug output is unchanged.\nResults include device_readiness with timestamped device blocker evidence. Android reports supported power/keyguard signals; iOS signals may be unknown or explicitly unsupported. Launch/input dispatch success does not establish app visibility or input readiness. No automatic unlock or wake is performed.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -3091,7 +3127,7 @@
   },
   {
     "name": "run_journey",
-    "description": "Run an ordered, bounded sequence of start_app, tap, wait, and deterministic assertion steps against one device. Stops after the first failed step.\nTap steps may include expectedState from a successful same-device get_ui_tree. A failed condition blocks that input, retains fresh condition evidence even in compact mode, and stops subsequent steps. Conditions are not journey defaults or supported on other step types.",
+    "description": "Run an ordered, bounded sequence of start_app, tap, wait, and deterministic assertion steps against one device. Stops after the first failed step.\nTap steps may include expectedState from a successful same-device get_ui_tree. A failed condition blocks that input, retains fresh condition evidence through a diagnostics reference in compact mode, and stops subsequent steps. Conditions are not journey defaults or supported on other step types.",
     "inputSchema": {
       "type": "object",
       "properties": {

package/test/fixtures/latency-journey-app/build.ts

@@ -1,5 +1,5 @@
 import { execFileSync } from 'node:child_process'
-import { mkdirSync } from 'node:fs'
+import { existsSync, mkdirSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -11,7 +11,7 @@ export function buildFixture() {
   const androidJar = path.join(sdk, 'platforms', 'android-36', 'android.jar')
   const java = process.env.JAVA_HOME
   const tool = (name: string) => java ? path.join(java, 'bin', name) : name
-  const run = (cmd: string, args: string[]) => execFileSync(cmd, args, { cwd: out, stdio: 'pipe' })
+  const run = (cmd: string, args: string[]) => execFileSync(cmd, args, { cwd: out, stdio: 'pipe', timeout: 60000, killSignal: 'SIGKILL' })
   mkdirSync(path.join(out, 'classes'), { recursive: true })
   run(tool('javac'), ['--release', '8', '-classpath', androidJar, '-d', 'classes', path.join(root, 'src/MainActivity.java')])
   run(tool('jar'), ['cf', 'classes.jar', '-C', 'classes', '.'])
@@ -20,7 +20,7 @@ export function buildFixture() {
   run('zip', ['-q', 'unsigned.apk', 'classes.dex'])
   run(path.join(buildTools, 'zipalign'), ['-f', '4', 'unsigned.apk', 'aligned.apk'])
   // Ephemeral signing material is generated outside version control.
-  try { run(tool('keytool'), ['-genkeypair', '-keystore', 'fixture.jks', '-storepass', 'android', '-keypass', 'android', '-alias', 'fixture', '-dname', 'CN=Latency Fixture', '-keyalg', 'RSA', '-validity', '3650']) } catch { /* Existing local fixture key. */ }
+  if (!existsSync(path.join(out, 'fixture.jks'))) run(tool('keytool'), ['-genkeypair', '-keystore', 'fixture.jks', '-storepass', 'android', '-keypass', 'android', '-alias', 'fixture', '-dname', 'CN=Latency Fixture', '-keyalg', 'RSA', '-validity', '3650'])
   run(path.join(buildTools, 'apksigner'), ['sign', '--ks', 'fixture.jks', '--ks-pass', 'pass:android', '--out', 'fixture.apk', 'aligned.apk'])
   return path.join(out, 'fixture.apk')
 }

package/test/unit/debugger/handle-guards.test.ts

@@ -52,7 +52,8 @@ try {
   for (const hints of [{}, { deviceId: 'ios-a' }, { platform: 'ios' }]) {
     const blocked = await call(ios, hints)
     assert.equal(blocked.failure_code, 'DEBUGGER_PAUSED')
-    assert.equal(blocked.debugger.debug_session_id, 'ios-session')
+    const details = payload(await handleToolCall('get_interaction_diagnostics', { sessionId: blocked.diagnostics.session_id, resultId: blocked.diagnostics.result_id }))
+    assert.equal(details.result.debugger.debug_session_id, 'ios-session')
     assert.equal(blocked.delivery_status, 'not_delivered'); assert.equal(blocked.dispatch_started, false)
   }
   assert.equal(reads, 0, 'A known pause must block before hierarchy reads')

package/test/unit/interact/ui-change-readiness-interruption.test.ts

@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict'
+import { ReadinessTracker, withReadinessTracker } from '../../../src/observe/readiness.js'
+import { withDeviceReadinessProbe } from '../../../src/observe/device-readiness.js'
+import { getSnapshotSessionId } from '../../../src/observe/snapshot-metadata.js'
+import { waitForUIChange } from '../../../src/interact/waits/ui-change-wait.js'
+import { resolveUiChangeScope } from '../../../src/interact/targeting/target-scope.js'
+import type { Clock } from '../../../src/runtime/clock.js'
+
+async function run() {
+  let now = 10000
+  const clock: Clock = { now: () => now, sleep: async ms => { now += ms } }
+  class Tracker extends ReadinessTracker {
+    override observe(tree: unknown, started: number) { return super.observe(tree, started, now) }
+  }
+  const tracker = new Tracker('android', 'fixture', 100)
+  const readTimes: number[] = []
+  const result = await withDeviceReadinessProbe(async (_command, args) => ({
+    exitCode: 0, stderr: '', stdout: args.includes('power')
+      ? `mWakefulness=${now >= 10600 && now < 11200 ? 'Asleep' : 'Awake'}\nmWakefulnessChanging=false`
+      : 'KeyguardServiceDelegate\n showing=false\n mIsShowing=false'
+  }), () => withReadinessTracker(tracker, () => waitForUIChange({ platform: 'android', deviceId: 'fixture', timeout_ms: 3000, stability_window_ms: 1200, expected_change: 'text_change' }, {
+    clock,
+    observe: async () => {
+      const text = readTimes.length ? 'After' : 'Before'
+      readTimes.push(now)
+      return { device: { platform: 'android', id: 'fixture' }, screen: '', resolution: { width: 100, height: 100 },
+        elements: [{ text, type: 'TextView', stable_id: 'label', visible: true, bounds: [0, 0, 100, 40] }],
+        captured_at_ms: now, snapshot_revision: readTimes.length, snapshot_session_id: getSnapshotSessionId() }
+    },
+    scope: (tree, scope, target) => resolveUiChangeScope(tree, scope, target, () => null)
+  })))
+  assert.equal(result.success, true)
+  assert.deepEqual(readTimes, [10000, 10300, 11200, 11500, 11800, 12100, 12400])
+  assert.equal(result.elapsed_ms, 2400, 'the full change stability window starts again after the blocker')
+  console.log('PASS readiness interruption resets UI-change stability, excluding blocked time')
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/observe/capture_debug_snapshot.test.ts

@@ -1,6 +1,8 @@
 import { ToolsObserve } from '../../../src/observe/index.js'
 import assert from 'assert'
 import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+import { computeScreenFingerprint } from '../../../src/utils/ui/index.js'
+import type { DeviceInfo } from '../../../src/types.js'
 
 async function run() {
   console.log('Starting capture_debug_snapshot unit tests...')
@@ -13,7 +15,7 @@ async function run() {
   const origReadLogStreamHandler = (ToolsObserve as any).readLogStreamHandler
   const origGetLogsHandler = (ToolsObserve as any).getLogsHandler
 
-  const device = { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true }
+  const device: DeviceInfo = { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true }
   let resolutions = 0
   _setDeviceListersForTests({
     listAndroidDevices: async () => { resolutions++; return [device] },
@@ -30,17 +32,23 @@ async function run() {
       assertTarget(args)
       return { device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true }, screenshot: 'BASE64PNG', resolution: { width: 1080, height: 1920 } }
     }
+    const current = { device, package: 'com.example', activity: 'com.example.Main', shortActivity: 'Main' }
+    const postTreeActivity = { ...current, activity: 'com.example.After' }
+    let activityCalls = 0
     ;(ToolsObserve as any).getCurrentScreenHandler = async function(args: any) {
       assert.strictEqual(args.deviceId, device.id)
-      return { device: { platform: 'android', id: 'mock' }, package: 'com.example', activity: 'com.example.Main', shortActivity: 'Main' }
+      return ++activityCalls === 1 ? current : postTreeActivity
     }
-    ;(ToolsObserve as any).getScreenFingerprintHandler = async function(args: any) {
-      assertTarget(args)
-      return { fingerprint: 'abc123', activity: 'Main' }
+    let independentFingerprints = 0
+    ;(ToolsObserve as any).getScreenFingerprintHandler = async function() {
+      independentFingerprints++
+      return { fingerprint: 'independent' }
     }
+    let treeReads = 0
     ;(ToolsObserve as any).getUITreeHandler = async function(args: any) {
       assertTarget(args)
-      return { device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true }, screen: '', resolution: { width: 1080, height: 1920 }, elements: [] }
+      treeReads++
+      return { device, screen: '', resolution: { width: 1080, height: 1920 }, elements: [] }
     }
     ;(ToolsObserve as any).readLogStreamHandler = async function(args: any) {
       assertTarget(args)
@@ -53,8 +61,11 @@ async function run() {
 
     const res1: any = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'android', includeLogs: true, logLines: 50, sessionId: 's1' })
     console.log('res1:', JSON.stringify(res1, null, 2))
-    const pass1 = res1 && res1.raw && res1.raw.screenshot === 'BASE64PNG' && res1.raw.activity && res1.raw.fingerprint === 'abc123' && Array.isArray(res1.raw.logs) && res1.raw.logs.length === 1
+    const pass1 = res1 && res1.raw && res1.raw.screenshot === 'BASE64PNG' && res1.raw.activity === current.activity && Array.isArray(res1.raw.logs) && res1.raw.logs.length === 1
     assert.ok(pass1, 'captureDebugSnapshot should aggregate successful handler results')
+    assert.equal(treeReads, 1)
+    assert.equal(independentFingerprints, 0)
+    assert.equal(res1.raw.fingerprint, computeScreenFingerprint(res1.raw.ui_tree, postTreeActivity, 'android').fingerprint)
     assert.strictEqual(res1.semantic.screen, 'Main')
     assert.strictEqual(res1.semantic.confidence >= 0.7, true)
     assert.deepStrictEqual(res1.semantic.actions_available, null)
@@ -63,7 +74,7 @@ async function run() {
 
     // --- Test 2: screenshot and ui tree fail; logs fallback to getLogs ---
     ;(ToolsObserve as any).captureScreenshotHandler = async function(args: any) { assertTarget(args); throw new Error('screencap failed') }
-    ;(ToolsObserve as any).getUITreeHandler = async function(args: any) { assertTarget(args); throw new Error('uie_error') }
+    ;(ToolsObserve as any).getUITreeHandler = async function(args: any) { assertTarget(args); treeReads++; throw new Error('ACTION_TIMEOUT') }
     ;(ToolsObserve as any).readLogStreamHandler = async function(args: any) { assertTarget(args); return { entries: [] } }
     ;(ToolsObserve as any).getLogsHandler = async function(args: any) { assertTarget(args); return { device: { platform: 'android', id: 'mock' }, logs: ['INFO starting','ERROR crash here'], logCount: 2 } }
 
@@ -71,33 +82,76 @@ async function run() {
     console.log('res2:', JSON.stringify(res2, null, 2))
     const pass2 = res2 && res2.raw && res2.raw.screenshot_error && res2.raw.ui_tree_error && Array.isArray(res2.raw.logs) && res2.raw.logs.length === 2
     assert.ok(pass2, 'captureDebugSnapshot should surface partial failures and fallback logs')
+    assert.equal(res2.raw.ui_tree_error, 'ACTION_TIMEOUT')
+    assert.equal(res2.raw.fingerprint_error, 'ACTION_TIMEOUT')
+    assert.equal(res2.raw.fingerprint, null)
+    assert.equal(treeReads, 2)
     console.log('Test 2:', pass2 ? 'PASS' : 'FAIL')
 
     // --- Test 3: includeLogs=false should omit logs ---
     ;(ToolsObserve as any).captureScreenshotHandler = async function(args: any) { assertTarget(args); return { device: { platform: 'android', id: 'mock' }, screenshot: null } }
-    ;(ToolsObserve as any).getCurrentScreenHandler = async function(args: any) { assert.strictEqual(args.deviceId, device.id); return { device: { platform: 'android', id: 'mock' }, package: '', activity: '', shortActivity: '' } }
-    ;(ToolsObserve as any).getScreenFingerprintHandler = async function(args: any) { assertTarget(args); return { fingerprint: null } }
-    ;(ToolsObserve as any).getUITreeHandler = async function(args: any) { assertTarget(args); return { device: { platform: 'android', id: 'mock' }, screen: '', resolution: { width: 0, height: 0 }, elements: [] } }
+    ;(ToolsObserve as any).getCurrentScreenHandler = async function(args: any) { assert.strictEqual(args.deviceId, device.id); throw new Error('activity unavailable') }
+    ;(ToolsObserve as any).getUITreeHandler = async function(args: any) {
+      assertTarget(args)
+      const revision = ++treeReads
+      return { device, screen: '', snapshot_revision: revision, captured_at_ms: 1000 + revision,
+        resolution: { width: 1080, height: 1920 }, elements: [{ visible: true, text: `State ${revision}` }] }
+    }
     ;(ToolsObserve as any).readLogStreamHandler = async function(args: any) { assertTarget(args); return { entries: [] } }
 
     const res3: any = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'android', includeLogs: false })
     console.log('res3:', JSON.stringify(res3, null, 2))
     const pass3 = res3 && res3.raw && typeof res3.raw.logs !== 'undefined' && res3.raw.logs.length === 0
     assert.ok(pass3, 'captureDebugSnapshot should return an empty logs array when includeLogs is false')
+    assert.equal(res3.raw.activity_error, 'activity unavailable')
+    assert.equal(res3.raw.fingerprint, computeScreenFingerprint(res3.raw.ui_tree, null, 'android').fingerprint)
     console.log('Test 3:', pass3 ? 'PASS' : 'FAIL')
 
     let screenshotCalls = 0
     ;(ToolsObserve as any).captureScreenshotHandler = async function(args: any) { assertTarget(args); screenshotCalls++; return { screenshot: 'unexpected' } }
-    const res4: any = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'android', includeLogs: false, includeScreenshot: false })
+    const res4: any = await ToolsObserve.captureDebugSnapshotHandler({ includeLogs: false, includeScreenshot: false })
     assert.strictEqual(screenshotCalls, 0, 'includeScreenshot=false must not invoke screenshot capture')
     assert.strictEqual(res4.raw.screenshot, null)
     assert.strictEqual(resolutions, 4, 'Each snapshot resolves its own target once')
+    assert.equal(treeReads, 4)
+    assert.notEqual(res4.raw.fingerprint, res3.raw.fingerprint)
+    assert.equal(res4.raw.snapshot_revision, 4)
+    assert.equal(res4.raw.captured_at_ms, 1004)
+    assert.equal(independentFingerprints, 0)
 
     // Discovery failure must not collect from an arbitrary/default device.
     _setDeviceListersForTests({ listAndroidDevices: async () => { throw new Error('fixture discovery unavailable') } })
     await assert.rejects(() => ToolsObserve.captureDebugSnapshotHandler({ platform: 'android' }), /fixture discovery unavailable/)
     assert.strictEqual(screenshotCalls, 0, 'No component capture should run without a resolved target')
 
+    const other: DeviceInfo = { ...device, id: 'other-fixture' }
+    _setDeviceListersForTests({ listAndroidDevices: async () => [device, other] })
+    ;(ToolsObserve as any).getUITreeHandler = async ({ deviceId }: { deviceId: string }) => ({
+      device: deviceId === device.id ? device : other, screen: '',
+      resolution: { width: 100, height: 200 }, elements: [{ visible: true, text: deviceId }]
+    })
+    ;(ToolsObserve as any).getCurrentScreenHandler = async ({ deviceId }: { deviceId: string }) => ({
+      activity: 'com.example.Main', device: deviceId === device.id ? device : other
+    })
+    const [first, second] = await Promise.all([device, other].map(target => ToolsObserve.captureDebugSnapshotHandler({
+      platform: 'android', deviceId: target.id, includeLogs: false, includeScreenshot: false
+    })))
+    assert.equal(first.raw.ui_tree?.device.id, device.id)
+    assert.equal(second.raw.ui_tree?.device.id, other.id)
+    assert.notEqual(first.raw.fingerprint, second.raw.fingerprint)
+    assert.equal(independentFingerprints, 0)
+
+    const ios: DeviceInfo = { ...device, platform: 'ios', id: 'ios-fixture' }
+    _setDeviceListersForTests({ listIOSDevices: async () => [ios] })
+    ;(ToolsObserve as any).getUITreeHandler = async ({ platform, deviceId }: { platform: string; deviceId: string }) => {
+      assert.equal(platform, 'ios')
+      assert.equal(deviceId, ios.id)
+      return { device: ios, screen: '', resolution: { width: 100, height: 200 }, elements: [] }
+    }
+    const iosResult = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'ios', deviceId: ios.id, includeLogs: false, includeScreenshot: false })
+    assert.equal(iosResult.raw.fingerprint, 'independent')
+    assert.equal(independentFingerprints, 1)
+
   } finally {
     _resetDeviceListersForTests()
     ;(ToolsObserve as any).captureScreenshotHandler = origCaptureHandler

package/test/unit/observe/device-readiness-cleanup.test.ts

@@ -0,0 +1,24 @@
+import assert from 'node:assert/strict'
+import { cleanupReadinessDevice } from '../../device/automated/observe/device-readiness-cleanup.js'
+
+async function run() {
+  for (const failedStep of [0, 1, 2]) {
+    const commands: string[][] = []
+    let closed = 0
+    const commandFailure = new Error('disconnected')
+    const closeFailure = new Error('close failed')
+    const failures = await cleanupReadinessDevice(true, (...args) => {
+      commands.push(args)
+      if (commands.length - 1 === failedStep) throw commandFailure
+    }, async () => { closed++; throw closeFailure })
+    assert.equal(commands.length, 3, 'a failed restoration must not skip later steps')
+    assert.equal(commands[2].at(-1), '3', 'Home is attempted')
+    assert.equal(closed, 1, 'client close always attempted')
+    assert.deepEqual(failures, [commandFailure, closeFailure])
+  }
+  let closed = false
+  assert.deepEqual(await cleanupReadinessDevice(false, () => { assert.fail('restoration disabled') }, async () => { closed = true }), [])
+  assert.equal(closed, true)
+  console.log('PASS readiness cleanup continues after each ADB failure and closes the client')
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/observe/device-readiness.test.ts

@@ -0,0 +1,97 @@
+import { handleAdjustControl } from '../../../src/server/handlers/interact.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import type { AdjustControlResponse } from '../../../src/types.js'
+import { ReadinessTracker } from '../../../src/observe/readiness.js'
+import { getSnapshotSessionId } from '../../../src/observe/snapshot-metadata.js'
+import assert from 'node:assert/strict'
+import { parseAndroidPower, parseAndroidLock, observeDeviceReadiness, parseIosLock, withDeviceReadinessProbe } from '../../../src/observe/device-readiness.js'
+import { registerDebuggerPauseProvider } from '../../../src/debugger/guard.js'
+import { runWithBudget } from '../../../src/utils/operation-budget.js'
+import { compactAction, actionHandler } from '../../../src/server/handlers/action-execution.js'
+import { wrapResponse } from '../../../src/server/common.js'
+import { withResolvedDevice } from '../../../src/utils/resolve-device.js'
+
+const power = (state: string, changing = 'false') => `mWakefulness=${state}\nmWakefulnessChanging=${changing}`
+const lock = (state: string) => `KeyguardServiceDelegate\n showing=${state}\n KeyguardStateMonitor\n mIsShowing=${state}`
+for (const [text, expected] of [[power('Awake'), 'awake'], [power('Asleep'), 'asleep'], [power('Dozing'), 'asleep'], [power('Awake', 'true'), 'transitioning'], [power('Dreaming'), 'unknown'], ['mWakefulness=Awake', 'unknown'], [power('Awake') + '\nmWakefulness=Asleep', 'unknown']]) assert.equal(parseAndroidPower(text), expected)
+assert.equal(parseAndroidPower('Power Manager State:\n' + power('Dozing') + '\nSettings and Configuration:\nmWakefulness=3'), 'asleep', 'vendor debug fields outside current-state section cannot conflict with it')
+assert.equal(parseAndroidLock(lock('true')), 'locked')
+assert.equal(parseAndroidLock(lock('false')), 'unlocked')
+for (const text of ['', 'deviceHasKeyguard=true', 'showing=false', lock('true').replace('mIsShowing=true', 'mIsShowing=false')]) assert.equal(parseAndroidLock(text), 'unknown')
+const unsupported = JSON.stringify({ error: { domain: 'com.apple.dt.CoreDeviceError', code: 1001, userInfo: { CapabilityFeatureIdentifier: { string: 'com.apple.coredevice.feature.getlockstate' } } } })
+assert.equal(parseIosLock(unsupported), 'unsupported')
+assert.equal(parseIosLock(unsupported.replace('getlockstate', 'other')), 'unknown')
+assert.equal(parseIosLock('{"result":{"passcodeRequired":false}}'), 'unknown', 'unverified success semantics cannot establish unlocked')
+const device = { platform: 'android', id: 'fixture', model: 'Fixture', osVersion: '16', simulator: true }
+async function run() {
+  const calls: string[][] = []
+  const probe = async (_command: string, args: string[], timeout: number) => {
+    calls.push(args)
+    assert.ok(timeout > 0 && timeout <= 1000)
+    return { exitCode: 0, stdout: args.includes('power') ? power('Asleep') : lock('true'), stderr: '' }
+  }
+  const started = Date.now()
+  const state = await runWithBudget(500, () => observeDeviceReadiness(device, probe))
+  assert.deepEqual(state.blockers, ['DEVICE_ASLEEP', 'DEVICE_LOCKED'])
+  assert.equal(state.input_ready, false)
+  assert.ok(state.evidence.every(item => item.captured_at_ms >= started))
+  assert.ok(calls.every(args => args[0] === '-s' && args[1] === device.id))
+  assert.ok(!JSON.stringify(state).includes('mWakefulness'))
+  const partial = await observeDeviceReadiness(device, async (...args) => {
+    if (args[1].includes('power')) throw new Error('private diagnostic')
+    return probe(...args)
+  })
+  assert.equal(partial.wakefulness, 'unknown')
+  assert.equal(partial.lock_state, 'locked')
+  assert.ok(!JSON.stringify(partial).includes('private diagnostic'))
+  const recovered = await observeDeviceReadiness(device, async (_cmd, args) => ({ exitCode: 0, stdout: args.includes('power') ? power('Awake') : lock('false'), stderr: '' }))
+  assert.equal(recovered.input_ready, null)
+  assert.deepEqual(recovered.blockers, [])
+  const tracker = new ReadinessTracker(device.platform, device.id, 100)
+  const tree = { device, captured_at_ms: Date.now(), snapshot_revision: 1, snapshot_session_id: getSnapshotSessionId(), resolution: { width: 100, height: 100 }, elements: [{ type: 'Button', visible: true, text: 'Ready' }] }
+  tracker.observe(tree, tree.captured_at_ms, 0)
+  assert.equal(tracker.observe(tree, tree.captured_at_ms, 100).state, 'settled')
+  await withDeviceReadinessProbe(probe, () => tracker.observeDevice())
+  assert.equal(tracker.ready, false)
+  await withDeviceReadinessProbe(async (_cmd, args) => ({ exitCode: 0, stdout: args.includes('power') ? power('Awake') : lock('false'), stderr: '' }), () => tracker.observeDevice())
+  assert.equal(tracker.observe(tree, tree.captured_at_ms, 500).state, 'unknown', 'blocker breaks UI stability continuity')
+  assert.equal(tracker.observe(tree, tree.captured_at_ms, 600).state, 'settled')
+  const before = calls.length
+  const expired = await runWithBudget(0, () => observeDeviceReadiness(device, probe))
+  assert.equal(calls.length, before, 'no probe starts after expiry')
+  assert.equal(expired.wakefulness, 'unknown')
+  assert.equal((await observeDeviceReadiness(null, probe)).limitations[0], 'DEVICE_TARGET_UNAVAILABLE')
+  const ios = await observeDeviceReadiness({ platform: 'ios', id: 'ios-fixture' }, async (_cmd, args, timeout) => { assert.equal(args[args.indexOf('--timeout') + 1], '5'); assert.ok(timeout <= 1000); return { exitCode: 1, stdout: unsupported, stderr: '' } })
+  assert.equal(ios.lock_state, 'unsupported')
+  assert.equal(ios.wakefulness, 'unknown')
+  registerDebuggerPauseProvider(() => ({ debug_session_id: 'paused', captured_at_ms: started, target: {} }))
+  try {
+    const paused = await observeDeviceReadiness(device, probe)
+    assert.deepEqual(paused.blockers, ['DEBUGGER_PAUSED'])
+    assert.equal(calls.length, before)
+  } finally { registerDebuggerPauseProvider(() => null) }
+  assert.deepEqual(compactAction({ success: true, device_readiness: state }, 'none').device_readiness, state)
+  for (const responseMode of ['debug', 'compact']) {
+    const response = await withDeviceReadinessProbe(probe, () => withResolvedDevice(device, () => actionHandler('start_app', async () => wrapResponse({ success: true, device }))( { platform: 'android', deviceId: device.id, responseMode, verificationMode: 'none', actionTimeoutMs: 500 })))
+    const result = JSON.parse(response.content[0].text!)
+    assert.equal(result.success, true, 'blocker observation preserves dispatch outcome')
+    assert.equal(result.verification.status, 'not_requested')
+    assert.deepEqual(result.device_readiness.blockers, ['DEVICE_ASLEEP', 'DEVICE_LOCKED'])
+  }
+  const failedProbe = await withDeviceReadinessProbe(async () => { throw new Error('private'); }, () => withResolvedDevice(device, () => actionHandler('tap', async () => wrapResponse({ success: true, device }))({ responseMode: 'compact', verificationMode: 'none', actionTimeoutMs: 200 })))
+  const unknown = JSON.parse(failedProbe.content[0].text!)
+  assert.equal(unknown.success, true)
+  assert.equal(unknown.device_readiness.wakefulness, 'unknown')
+  assert.equal(unknown.device_readiness.lock_state, 'unknown')
+  assert.ok(!JSON.stringify(unknown.device_readiness).includes('private'))
+  const adjust = ToolsInteract.adjustControlHandler
+  ToolsInteract.adjustControlHandler = async () => ({ success: true, device } as AdjustControlResponse)
+  try {
+    const response = await withDeviceReadinessProbe(probe, () => handleAdjustControl({ selector: { text: 'Volume' }, targetValue: 50 }))
+    const result = JSON.parse(response.content[0].text!)
+    assert.equal(result.success, true)
+    assert.equal(result.device_readiness.input_ready, false, 'adjust_control carries the same blocker contract')
+  } finally { ToolsInteract.adjustControlHandler = adjust }
+  console.log('Device readiness: parsing, probes, budgets, recovery, debugger and action contracts PASS')
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })