mobile-debug-mcp 0.35.0 → 0.37.0

package/docs/specs/032-ios-runtime-debugger/spec.md

@@ -0,0 +1,153 @@
+# iOS runtime debugger — specification
+
+Source: [issue #70](https://github.com/clivejefferies/mobile-debug-tools/issues/70).
+Scope: [accepted intent](intent.md), approved by the user's “ok” on 2026-11-04.
+Status: **approved** by the user's “ok” on 2026-11-04 in response to the complete
+specification and approval request in this chat. Implementation authorised.
+
+## Behaviour and supported environment
+
+Add optional LLDB-backed debugging for an already-running development app on an
+explicit iOS simulator UDID, on macOS with full Xcode and its Swift-enabled LLDB.
+Initial verification targets the installed Xcode 27.2, LLDB 2103.0.34.407 and Swift
+6.4.2 toolchain; other versions remain unverified until separately exercised.
+Physical devices, remote hosts and production/optimised apps are unsupported in
+this initial matrix. Normal mobile tools must not acquire an LLDB dependency.
+
+Provide source breakpoints, stop events, bounded stacks and shallow locals,
+into/over/out stepping, resume and detach through the existing eleven tools.
+Attach may briefly stop the process for setup, but returns running unless an
+actual stop event has been retained; never discard a racing breakpoint stop.
+LLDB stops suspend the target process, not the whole simulator.
+
+## Tool contract and compatibility
+
+Extend `get_debugger_capabilities` and `attach_debugger` to accept
+`platform: "android" | "ios"`, existing explicit `deviceId`, `appId` and optional
+positive `processId`. For iOS, require a simulator UDID and valid bundle identifier.
+Probe without attaching or launching the app. Report missing prerequisites,
+unsupported target types, absent apps/processes and ambiguous candidates
+explicitly. A probe cannot guarantee that later attach permission will succeed.
+
+Preserve all existing Android requests. Extend `set_debugger_breakpoint` with
+optional `sourceFile` (nonempty absolute local source path, maximum 512 characters).
+Require exactly one of `className` or `sourceFile`, with the existing positive
+1-based `line`. Android sessions require `className`; iOS sessions require
+`sourceFile`. Invalid combinations fail `INVALID_ARGUMENT`. Resolve the full
+path against loaded debug information, never a basename fallback or shell search.
+Return owned breakpoint ID, pending/resolved/rejected status and actual locations.
+Unloaded images can remain pending. Only exact executable line matches may be
+enabled; locations silently moved by LLDB are rejected and removed.
+
+Keep session, stop, thread and frame arguments, tool names, response modes,
+pagination, defaults and timeout bounds unchanged. Existing common response and
+error shapes remain: `success`, session/target/device metadata, state, timestamp,
+capabilities, limitations, cleanup, reason, stop, operation `result`, and sanitized
+`error: {code, message, retryable, diagnostic?}`. Device platform is correct on
+success and failure. iOS target metadata carries bundle ID, PID, executable name,
+process-start identity and nullable UID; Android retains its existing fields.
+
+Capability values are backend-specific. iOS advertises supported core operations;
+`evaluation`, `mutation`, `coroutines` and `native` remain false (`native` denotes
+an exposed native-specific inspection capability, not LLDB's implementation).
+Add iOS-only boolean `async_execution_inspection` and `async_stepping`; the former
+requires the async acceptance journey below, the latter a separate demonstrated
+step across suspension. False values carry explanatory limitations. No suspended
+task enumeration, task identity API or logical-task reconstruction is promised.
+Preserve compact mode's existing omissions and full attach/capabilities/state
+responses. Unknown fields remain rejected.
+
+## Async semantics
+
+Source breakpoints must work before and after a controlled Swift `await`, with
+useful known primitive locals at each actual stop. Include nested child work,
+actor/executor transitions and a separately triggered task cancellation path.
+Use deterministic fixture gates and completion/cancellation UI state.
+
+Stepping acknowledges delivery and resumes; only a subsequent event establishes
+where execution stopped. Exercise ordinary helper into/over/out and an `await`
+boundary. Delegate stepping to Swift-enabled LLDB; do not equate a physical
+thread ID with stable task identity. If the tested LLDB route follows the async
+continuation, report the observed source stop and advertise `async_stepping`.
+Otherwise report it false with the limitation and demonstrate recovery through
+independent after-await breakpoints. Unexpected missing async locals or source
+stops fail core async acceptance rather than being labelled support.
+
+Stacks describe LLDB's observed frames; label unavailable source/variable data
+and generated frames honestly. Do not claim a complete logical async ancestry.
+No expression evaluation, object descriptions, custom formatters that execute
+code, property getters, dynamic method calls or continuation-field traversal.
+
+## Ownership, failure and safety
+
+Resolve simulator, bundle executable and running PID together; validate executable
+path, start identity and simulator membership before and after attach. Never attach
+to an arbitrary host PID, launch a missing app or replace another debugger.
+Reject identity changes and duplicate owned sessions. Serialize session mutations;
+isolate sessions and guards by platform plus device, including identical IDs.
+
+Reuse stop-scoped opaque references, the 256-event ring/100-event response limit,
+1000-frame cap, default 20/max 100 stack page, max 100 locals and 256-character
+string bound. Object locals expose type/opaque identity only. Missing or
+inaccessible variables are explicit; an empty list cannot prove availability.
+
+Generalise pause guards/readiness to iOS lifecycle actions, input, waits and
+assertions. Preserve device-wide conservative guarding, racing-dispatch
+uncertainty and observation access within existing deadlines. Do not claim
+foreground identity from debugger state.
+
+Use a dedicated owned LLDB worker with bounded structured IPC, argument-array
+subprocess calls, disabled user init files and no arbitrary command interface.
+Sanitize errors using the existing bounded diagnostic catalog; iOS recovery
+guidance names Xcode/LLDB rather than JDK/ADB. Never log worker messages, locals,
+raw stderr, exception text or source contents. Debug inspection stays local and
+request-scoped; public evidence uses only the disposable fixture.
+
+Retain 100–30000 ms request bounds, 60-second pause, five-minute idle and
+30-minute session expiry, including independent worker watchdogs. Event-wait
+cancellation preserves a usable session. Inspection timeouts preserve a known
+session; uncertain attach or mutation outcomes trigger owned teardown and report
+execution uncertainty. No automatic retries of attach/step/resume.
+
+Detach releases owned suspension, breakpoints, step plans and worker resources;
+never kill the app, another debugger or simulator. EOF/shutdown/expiry attempt
+detach. Cleanup is idempotent and retryable with explicit remaining resources;
+transport loss or forced host termination cannot imply confirmed recovery.
+
+## Acceptance and verification
+
+1. Real MCP simulator journey: attach, exact and pending source breakpoint,
+   stop, source stack, known locals, helper stepping, resume, removal and detach.
+2. Async journey: before/after-await locals, nested work and executor transition,
+   completion, cancellation recovery, and recorded boundary-step outcome.
+3. Safety: stale references, cross-session/device isolation, paused input and
+   readiness, cancelled event wait, process exit, attach failure, timeout,
+   automatic expiry and repeatable cleanup. Verify app usability after detach.
+4. Contract checks cover registration, runtime validation, dispatch, both response
+   modes, diagnostics and Android compatibility. Run `npm run verify`, applicable
+   `npm run test:device`, focused iOS MCP journeys and Android debugger regressions.
+5. Record fixture/server hashes, Xcode/LLDB/Swift/runtime versions, target UDID,
+   exact actions, observed values and independent UI-tree assertions. Report
+   physical-device and unavailable coverage as unrun, never inferred.
+
+Likely affected areas: `src/debugger/`, debugger schemas/handlers/serialization,
+iOS interaction/readiness boundaries, fixture/device/unit trees, packaging and
+debugger tool documentation/README/changelog. Reuse worker/session abstractions
+without routing Android through LLDB. Main risks are simulator process attribution,
+LLDB/Python distribution, async metadata, source relocation and teardown races.
+
+## Investigation evidence and remaining prerequisites
+
+On 2026-11-04, local version probes found the toolchain above. Sandboxed simctl
+could not contact CoreSimulator; an authorised outside-sandbox read succeeded and
+found no booted simulators. No existing iOS debugger implementation or live iOS
+debug journey is claimed. Implementation verification requires booting an
+available simulator and installing only the disposable development fixture.
+
+Apple documents async-aware stepping since Swift 6.2 in
+[What's new in Swift](https://developer.apple.com/videos/play/wwdc2025/245/).
+The [LLDB SBFrame API](https://lldb.llvm.org/python_reference/lldb.SBFrame-class.html)
+provides frame-variable access. These support the proposed route, not proof of
+this server's behaviour; exact worker loading, attach and safe variable extraction
+must be validated before claiming support. If unavailable, record the concrete
+blocker and return for a scope decision rather than weakening acceptance.

package/docs/specs/033-device-readiness-blockers/android-evidence.json

@@ -0,0 +1,437 @@
+{
+  "deviceId": "emulator-5554",
+  "server": "dist/server.js",
+  "server_sha256": "49fa8b8969b5f6bae270c56912b3b1259edb400087b551538dcf0b45855aae34",
+  "runtime": "v23.11.0",
+  "observations": [
+    {
+      "tool": "get_app_readiness",
+      "args": {},
+      "result": {
+        "success": true,
+        "device": {
+          "platform": "android",
+          "id": "emulator-5554",
+          "osVersion": "16",
+          "model": "sdk_gphone64_arm64",
+          "simulator": true,
+          "appInstalled": false
+        },
+        "readiness": {
+          "state": "settled",
+          "scope": "device_ui",
+          "basis": "observed",
+          "captured_at_ms": 1793824169556,
+          "snapshot_session_id": "760cfc72-9c17-4855-8a9e-4491f35284c1",
+          "snapshot_revision": 1,
+          "sample_count": 2,
+          "stable_for_ms": 2774.727875,
+          "evidence": [
+            {
+              "code": "INSUFFICIENT_SAMPLES",
+              "source": "ui_tree",
+              "captured_at_ms": 1793824166781,
+              "snapshot_revision": 1
+            },
+            {
+              "code": "SNAPSHOT_STABLE",
+              "source": "ui_tree",
+              "captured_at_ms": 1793824169556,
+              "snapshot_revision": 1
+            }
+          ],
+          "limitations": [
+            "NORMALIZED_UI_ONLY",
+            "FOREGROUND_APP_UNVERIFIED",
+            "UNRESPONSIVE_SIGNAL_UNSUPPORTED",
+            "MANAGED_DEBUGGER_ONLY"
+          ],
+          "capabilities": {
+            "loading": true,
+            "transitioning": true,
+            "settled": true,
+            "unresponsive": false,
+            "debugger_paused": true
+          }
+        },
+        "device_readiness": {
+          "wakefulness": "awake",
+          "lock_state": "unlocked",
+          "input_ready": null,
+          "blockers": [],
+          "evidence": [
+            {
+              "code": "DEVICE_AWAKE",
+              "source": "android_power",
+              "captured_at_ms": 1793824167338
+            },
+            {
+              "code": "DEVICE_UNLOCKED",
+              "source": "android_window",
+              "captured_at_ms": 1793824167382
+            }
+          ],
+          "limitations": []
+        },
+        "elapsed_ms": 5454.18075
+      }
+    },
+    {
+      "tool": "get_app_readiness",
+      "args": {},
+      "result": {
+        "success": true,
+        "device": {
+          "platform": "android",
+          "id": "emulator-5554",
+          "osVersion": "16",
+          "model": "sdk_gphone64_arm64",
+          "simulator": true,
+          "appInstalled": false
+        },
+        "readiness": {
+          "state": "unknown",
+          "scope": "device_ui",
+          "basis": "insufficient",
+          "captured_at_ms": null,
+          "sample_count": 0,
+          "stable_for_ms": 0,
+          "snapshot_session_id": null,
+          "snapshot_revision": null,
+          "evidence": [],
+          "limitations": [
+            "NORMALIZED_UI_ONLY",
+            "FOREGROUND_APP_UNVERIFIED",
+            "UNRESPONSIVE_SIGNAL_UNSUPPORTED",
+            "MANAGED_DEBUGGER_ONLY",
+            "INSUFFICIENT_SAMPLES",
+            "DEVICE_BLOCKED"
+          ],
+          "capabilities": {
+            "loading": true,
+            "transitioning": true,
+            "settled": true,
+            "unresponsive": false,
+            "debugger_paused": true
+          }
+        },
+        "device_readiness": {
+          "wakefulness": "asleep",
+          "lock_state": "unlocked",
+          "input_ready": false,
+          "blockers": [
+            "DEVICE_ASLEEP"
+          ],
+          "evidence": [
+            {
+              "code": "DEVICE_ASLEEP",
+              "source": "android_power",
+              "captured_at_ms": 1793824170627
+            },
+            {
+              "code": "DEVICE_UNLOCKED",
+              "source": "android_window",
+              "captured_at_ms": 1793824170662
+            }
+          ],
+          "limitations": []
+        },
+        "elapsed_ms": 1055.0427499999996
+      }
+    },
+    {
+      "tool": "start_app",
+      "args": {
+        "appId": "com.android.settings",
+        "verificationMode": "none",
+        "responseMode": "compact",
+        "actionTimeoutMs": 10000
+      },
+      "result": {
+        "action_id": "fad30314-3242-43b7-b61c-97ec974bf9b4",
+        "device_readiness": {
+          "wakefulness": "asleep",
+          "lock_state": "unlocked",
+          "input_ready": false,
+          "blockers": [
+            "DEVICE_ASLEEP"
+          ],
+          "evidence": [
+            {
+              "code": "DEVICE_ASLEEP",
+              "source": "android_power",
+              "captured_at_ms": 1793824171199
+            },
+            {
+              "code": "DEVICE_UNLOCKED",
+              "source": "android_window",
+              "captured_at_ms": 1793824171242
+            }
+          ],
+          "limitations": []
+        },
+        "action_type": "start_app",
+        "success": true,
+        "lifecycle_state": "pending_verification",
+        "delivery_status": "delivered",
+        "dispatch_started": true,
+        "verification": {
+          "mode": "none",
+          "status": "not_requested"
+        },
+        "timing": {
+          "total_ms": 579.8293329999997
+        },
+        "evidence": {
+          "session_id": "fe501f9e-b707-4763-854c-4a1c81931fe1",
+          "correlation_id": "fad30314-3242-43b7-b61c-97ec974bf9b4",
+          "action_id": "fad30314-3242-43b7-b61c-97ec974bf9b4",
+          "device": {
+            "platform": "android",
+            "id": "emulator-5554"
+          },
+          "association": "self",
+          "association_reason": null,
+          "operation_started_at_ms": 1793824170663,
+          "operation_completed_at_ms": 1793824171242,
+          "dispatch_started_at_ms": 1793824170713,
+          "dispatch_completed_at_ms": 1793824171015,
+          "verification_completed_at_ms": null,
+          "observations": [
+            {
+              "evidence_id": "2d8052cc-f6f2-4f77-98e9-ff1ca0f2e3a5",
+              "kind": "activity",
+              "status": "captured",
+              "capture_started_at_ms": 1793824171015,
+              "capture_completed_at_ms": 1793824171135,
+              "source_captured_at_ms": 1793824171135,
+              "age_ms": 106.934326171875,
+              "freshness": "fresh",
+              "freshness_reasons": [],
+              "device": {
+                "platform": "android",
+                "id": "emulator-5554"
+              },
+              "session_id": "fe501f9e-b707-4763-854c-4a1c81931fe1",
+              "correlation_id": "fad30314-3242-43b7-b61c-97ec974bf9b4",
+              "action_id": "fad30314-3242-43b7-b61c-97ec974bf9b4",
+              "association": "internal"
+            }
+          ],
+          "trace_context": {
+            "supported": false,
+            "trace_id": null,
+            "markers": []
+          }
+        }
+      }
+    },
+    {
+      "tool": "wait_for_app_ready",
+      "args": {
+        "timeoutMs": 1200,
+        "pollIntervalMs": 100
+      },
+      "result": {
+        "success": false,
+        "device": {
+          "platform": "android",
+          "id": "emulator-5554",
+          "osVersion": "16",
+          "model": "sdk_gphone64_arm64",
+          "simulator": true,
+          "appInstalled": false
+        },
+        "readiness": {
+          "state": "unknown",
+          "scope": "device_ui",
+          "basis": "insufficient",
+          "captured_at_ms": null,
+          "sample_count": 0,
+          "stable_for_ms": 0,
+          "snapshot_session_id": null,
+          "snapshot_revision": null,
+          "evidence": [],
+          "limitations": [
+            "NORMALIZED_UI_ONLY",
+            "FOREGROUND_APP_UNVERIFIED",
+            "UNRESPONSIVE_SIGNAL_UNSUPPORTED",
+            "MANAGED_DEBUGGER_ONLY",
+            "INSUFFICIENT_SAMPLES",
+            "DEVICE_BLOCKED",
+            "DEADLINE_EXCEEDED"
+          ],
+          "capabilities": {
+            "loading": true,
+            "transitioning": true,
+            "settled": true,
+            "unresponsive": false,
+            "debugger_paused": true
+          }
+        },
+        "device_readiness": {
+          "wakefulness": "unknown",
+          "lock_state": "unknown",
+          "input_ready": null,
+          "blockers": [],
+          "evidence": [],
+          "limitations": [
+            "DEVICE_POWER_OBSERVATION_FAILED",
+            "DEVICE_LOCK_OBSERVATION_FAILED"
+          ]
+        },
+        "elapsed_ms": 1245.8765839999996,
+        "failure_code": "READINESS_TIMEOUT"
+      }
+    },
+    {
+      "tool": "get_app_readiness",
+      "args": {},
+      "result": {
+        "success": true,
+        "device": {
+          "platform": "android",
+          "id": "emulator-5554",
+          "osVersion": "16",
+          "model": "sdk_gphone64_arm64",
+          "simulator": true,
+          "appInstalled": false
+        },
+        "readiness": {
+          "state": "settled",
+          "scope": "device_ui",
+          "basis": "observed",
+          "captured_at_ms": 1793824178604,
+          "snapshot_session_id": "760cfc72-9c17-4855-8a9e-4491f35284c1",
+          "snapshot_revision": 2,
+          "sample_count": 2,
+          "stable_for_ms": 2779.1579999999994,
+          "evidence": [
+            {
+              "code": "INSUFFICIENT_SAMPLES",
+              "source": "ui_tree",
+              "captured_at_ms": 1793824175825,
+              "snapshot_revision": 2
+            },
+            {
+              "code": "SNAPSHOT_STABLE",
+              "source": "ui_tree",
+              "captured_at_ms": 1793824178604,
+              "snapshot_revision": 2
+            }
+          ],
+          "limitations": [
+            "NORMALIZED_UI_ONLY",
+            "FOREGROUND_APP_UNVERIFIED",
+            "UNRESPONSIVE_SIGNAL_UNSUPPORTED",
+            "MANAGED_DEBUGGER_ONLY"
+          ],
+          "capabilities": {
+            "loading": true,
+            "transitioning": true,
+            "settled": true,
+            "unresponsive": false,
+            "debugger_paused": true
+          }
+        },
+        "device_readiness": {
+          "wakefulness": "awake",
+          "lock_state": "unlocked",
+          "input_ready": null,
+          "blockers": [],
+          "evidence": [
+            {
+              "code": "DEVICE_AWAKE",
+              "source": "android_power",
+              "captured_at_ms": 1793824176383
+            },
+            {
+              "code": "DEVICE_UNLOCKED",
+              "source": "android_window",
+              "captured_at_ms": 1793824176424
+            }
+          ],
+          "limitations": []
+        },
+        "elapsed_ms": 6075.207875
+      }
+    },
+    {
+      "tool": "wait_for_app_ready",
+      "args": {
+        "timeoutMs": 15000,
+        "stabilityMs": 100,
+        "pollIntervalMs": 100
+      },
+      "result": {
+        "success": true,
+        "device": {
+          "platform": "android",
+          "id": "emulator-5554",
+          "osVersion": "16",
+          "model": "sdk_gphone64_arm64",
+          "simulator": true,
+          "appInstalled": false
+        },
+        "readiness": {
+          "state": "settled",
+          "scope": "device_ui",
+          "basis": "observed",
+          "captured_at_ms": 1793824183495,
+          "snapshot_session_id": "760cfc72-9c17-4855-8a9e-4491f35284c1",
+          "snapshot_revision": 2,
+          "sample_count": 2,
+          "stable_for_ms": 2404.0407909999994,
+          "evidence": [
+            {
+              "code": "INSUFFICIENT_SAMPLES",
+              "source": "ui_tree",
+              "captured_at_ms": 1793824181091,
+              "snapshot_revision": 2
+            },
+            {
+              "code": "SNAPSHOT_STABLE",
+              "source": "ui_tree",
+              "captured_at_ms": 1793824183495,
+              "snapshot_revision": 2
+            }
+          ],
+          "limitations": [
+            "NORMALIZED_UI_ONLY",
+            "FOREGROUND_APP_UNVERIFIED",
+            "UNRESPONSIVE_SIGNAL_UNSUPPORTED",
+            "MANAGED_DEBUGGER_ONLY"
+          ],
+          "capabilities": {
+            "loading": true,
+            "transitioning": true,
+            "settled": true,
+            "unresponsive": false,
+            "debugger_paused": true
+          }
+        },
+        "device_readiness": {
+          "wakefulness": "awake",
+          "lock_state": "unlocked",
+          "input_ready": null,
+          "blockers": [],
+          "evidence": [
+            {
+              "code": "DEVICE_AWAKE",
+              "source": "android_power",
+              "captured_at_ms": 1793824181241
+            },
+            {
+              "code": "DEVICE_UNLOCKED",
+              "source": "android_window",
+              "captured_at_ms": 1793824181281
+            }
+          ],
+          "limitations": []
+        },
+        "elapsed_ms": 4855.992333
+      }
+    }
+  ],
+  "cleanup": "wake, dismiss disposable keyguard, Home; no security settings changed"
+}

package/docs/specs/033-device-readiness-blockers/android-physical-evidence.json

@@ -0,0 +1,28 @@
+{
+  "device": {
+    "platform": "android",
+    "id": "adb-51181FDAP0031Y-gxy7FO._adb-tls-connect._tcp"
+  },
+  "model": "Pixel 9 Pro",
+  "osVersion": "Android 17",
+  "runtime": "v23.11.0",
+  "scope": "read-only current state; no sleep/lock/unlock/input dispatched",
+  "result": {
+    "wakefulness": "unknown",
+    "lock_state": "locked",
+    "input_ready": false,
+    "blockers": [
+      "DEVICE_LOCKED"
+    ],
+    "evidence": [
+      {
+        "code": "DEVICE_LOCKED",
+        "source": "android_window",
+        "captured_at_ms": 1793824059095
+      }
+    ],
+    "limitations": [
+      "DEVICE_WAKEFULNESS_UNVERIFIED"
+    ]
+  }
+}

package/docs/specs/033-device-readiness-blockers/android-physical-power-evidence.json

@@ -0,0 +1,29 @@
+{
+  "device": {
+    "platform": "android",
+    "id": "adb-51181FDAP0031Y-gxy7FO._adb-tls-connect._tcp"
+  },
+  "model": "Pixel 9 Pro",
+  "osVersion": "Android 17",
+  "runtime": "v23.11.0",
+  "scope": "read-only current state; main Power Manager State section; no input dispatched",
+  "result": {
+    "wakefulness": "awake",
+    "lock_state": "unlocked",
+    "input_ready": null,
+    "blockers": [],
+    "evidence": [
+      {
+        "code": "DEVICE_AWAKE",
+        "source": "android_power",
+        "captured_at_ms": 1793824124380
+      },
+      {
+        "code": "DEVICE_UNLOCKED",
+        "source": "android_window",
+        "captured_at_ms": 1793824124492
+      }
+    ],
+    "limitations": []
+  }
+}

package/docs/specs/033-device-readiness-blockers/intent.md

@@ -0,0 +1,41 @@
+# Intent: device readiness blockers
+
+Status: intent and revised specification approved; implementation authorised.
+Originator: clivejefferies, GitHub issue #101, created 2026-11-04.
+Captured: 2026-11-04.
+Source: https://github.com/clivejefferies/mobile-debug-tools/issues/101
+
+## Problem
+
+Recent agent feedback reports that a successful app launch left the agent
+inspecting a sleeping or locked phone. Existing app readiness signals (#65)
+need to distinguish launch dispatch from an app observed to be visible and
+ready for input.
+
+## Desired outcome and scope
+
+Extend existing launch, readiness, and relevant interaction results so MCP
+clients can identify device-level readiness blockers on Android and iOS.
+Report sleeping or locked states only when supported evidence establishes
+them; otherwise expose explicit unknown or unsupported outcomes. Include
+evidence timestamps and coordinate with existing debugger-paused reporting.
+
+Success means launch dispatch alone cannot imply visibility or input readiness,
+and supported awake/unlocked, sleeping, locked, transitioning, and debugger-paused
+flows have recorded verification. Distinguish Android and iOS evidence and record
+any inaccessible scenarios. Reproduce the reported flow where practical.
+
+## Constraints and questions
+
+Preserve bounded waits, device targeting, and existing action contracts unless a
+compatibility change is explicitly approved. Do not automatically unlock devices
+or change security settings. New diagnostic capabilities are outside scope.
+
+Investigation must establish which device states each platform can reliably
+observe, which existing results need the evidence, and how stale or conflicting
+observations should be represented. These decisions belong in the specification.
+
+## Approval
+
+User approved this problem and scope with “ok” in the current chat on 2026-11-04,
+in response to the captured intent and explicit intent-approval question.