mobile-debug-mcp 0.35.0 → 0.37.0

package/docs/specs/033-device-readiness-blockers/ios-investigation.md

@@ -0,0 +1,55 @@
+# iOS readiness investigation — 2026-11-04
+
+## Findings
+
+Blanket iOS unsupported was not justified by the initial sandbox failure.
+Running the probes outside the sandbox established an actual capability
+boundary, separately from tool-access failures.
+
+Apple's installed `devicectl` documents `device info lockState` as a read-only
+lock-state query, and `device info displays` supplies structured backlight
+information. Its help documents JSON output as the automation interface.
+[Apple's device command-line documentation](https://developer.apple.com/documentation/xcode/interacting-with-devices-using-the-command-line)
+is the upstream reference. This investigation relies on actual local command
+help and output for the conclusions below.
+
+## Environment and results
+
+Target: iPhone 17 Pro simulator, UDID
+`F9243BAF-62A8-4990-8A99-17F527F56FDA`, listed as iOS 26.4.
+CoreDevice CLI version: `651.32`; JSON version: 5.
+No physical iOS device was listed by `devicectl list devices`.
+No server implementation was changed or tested.
+
+| Probe | Observed result | Meaning |
+| --- | --- | --- |
+| `xcrun simctl list devices booted` outside sandbox | No booted simulators initially | Initial runtime state only |
+| `xcrun simctl boot <UDID>` / `bootstatus <UDID> -b` | Boot succeeded; later bootstatus confirmed booted | Runtime available |
+| `xcrun devicectl device info lockState --device <UDID> --timeout 10 --json-output <path>` | CoreDevice error 1001, feature `com.apple.coredevice.feature.getlockstate`, capability not supported | Explicit lock-probe unsupported on this target/toolchain |
+| `xcrun devicectl device info displays --device <UDID> --timeout 10 --json-output <path>` | Per-display backlight unknown; top-level backlight `activeOn` after boot | Does not establish lock state |
+| `xcrun simctl io <UDID> enumerate` | Display ports report power On | Port-level evidence only |
+| `xcrun simctl io <UDID> screenConfig --display 1 power off` followed by display probes | Command accepted; display ports still On; devicectl top-level `activeOn` | These probes did not distinguish the commanded display-off state |
+| Repeat display-off experiment after bootstatus completed | Baseline and off JSON both `activeOn` | No reliable sleep inference from this experiment |
+| `screenConfig --display 1 power on`, then `simctl shutdown <UDID>` | Both completed successfully | Restored original shutdown state |
+
+The display-off command is not independently verified OS sleep or lock. The
+experiment disproves treating command acknowledgement or port power as sufficient
+readiness evidence; it does not establish that every iOS display API is unusable.
+Transient timing and simulator-specific semantics remain limitations.
+
+## Proposed specification correction
+
+- Explicit unsupported is per axis and target, established by capability evidence.
+- Probe failures or uninterpretable observations yield unknown.
+- On this simulator: lock state unsupported through CoreDevice; wakefulness
+  unknown with an unverified-signal limitation.
+- Physical iOS lock detection has an Apple CLI route, but no physical iOS device
+  was available to validate output or locked/unlocked transitions. The repository's
+  current iOS discovery/lifecycle path is simulator-based; extending that is a
+  separate scope decision.
+- No private API fallback, app instrumentation, automatic unlock, or security
+  changes are proposed.
+
+This is investigation evidence, not implementation verification or proof of
+all iOS runtimes. Real lock/unlock transitions and true sleep recovery remain
+unrun on iOS.

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

@@ -0,0 +1,24 @@
+{
+  "device": {
+    "platform": "ios",
+    "id": "F9243BAF-62A8-4990-8A99-17F527F56FDA"
+  },
+  "runtime": "v23.11.0",
+  "server": "dist/observe/device-readiness.js",
+  "result": {
+    "wakefulness": "unknown",
+    "lock_state": "unsupported",
+    "input_ready": null,
+    "blockers": [],
+    "evidence": [
+      {
+        "code": "DEVICE_LOCK_SIGNAL_UNSUPPORTED",
+        "source": "coredevice",
+        "captured_at_ms": 1793823876688
+      }
+    ],
+    "limitations": [
+      "DEVICE_WAKEFULNESS_UNVERIFIED"
+    ]
+  }
+}

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

@@ -0,0 +1,73 @@
+{
+  "tool": "get_app_readiness",
+  "server": {
+    "name": "mobile-debug-mcp",
+    "version": "0.36.0"
+  },
+  "runtime": "v23.11.0",
+  "result": {
+    "success": true,
+    "device": {
+      "platform": "ios",
+      "id": "F9243BAF-62A8-4990-8A99-17F527F56FDA",
+      "osVersion": "iOS 26.4",
+      "model": "iPhone 17 Pro",
+      "simulator": true,
+      "booted": true
+    },
+    "readiness": {
+      "state": "settled",
+      "scope": "device_ui",
+      "basis": "observed",
+      "captured_at_ms": 1793823964160,
+      "snapshot_session_id": "cd4bc1e2-b26c-40f6-a50e-27472dc00a29",
+      "snapshot_revision": 1,
+      "sample_count": 2,
+      "stable_for_ms": 2846.7576670000003,
+      "evidence": [
+        {
+          "code": "INSUFFICIENT_SAMPLES",
+          "source": "ui_tree",
+          "captured_at_ms": 1793823961313,
+          "snapshot_revision": 1
+        },
+        {
+          "code": "SNAPSHOT_STABLE",
+          "source": "ui_tree",
+          "captured_at_ms": 1793823964160,
+          "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": "unknown",
+      "lock_state": "unsupported",
+      "input_ready": null,
+      "blockers": [],
+      "evidence": [
+        {
+          "code": "DEVICE_LOCK_SIGNAL_UNSUPPORTED",
+          "source": "coredevice",
+          "captured_at_ms": 1793823962013
+        }
+      ],
+      "limitations": [
+        "DEVICE_WAKEFULNESS_UNVERIFIED"
+      ]
+    },
+    "elapsed_ms": 5987.550583
+  }
+}

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

@@ -0,0 +1,249 @@
+# Implementation and verification plan
+
+Scope: [intent](intent.md), [approved specification](spec.md). User approved the
+revised contract with “ok, lets proceed” on 2026-11-04.
+
+Status: implementation and supported virtual-device checks complete on
+2026-11-05, including the trace shutdown repair below. Default idb compatibility
+and hardware-specific coverage remain separate limitations.
+
+## Implementation
+
+- [x] Add typed, bounded device-state probes with conservative Android parsing and
+  capability-based iOS lock evidence; reuse subprocess and operation budgets.
+- [x] Integrate evidence into readiness services, predicate waits, and shared action
+  responses, retaining dispatch outcomes and compact/journey evidence.
+- [x] Cover parsing, partial failure, recovery, deadlines, debugger precedence,
+  targeting and serialization with self-running unit tests.
+- [x] Update tool docs, descriptions, README and changelog. Review all changed callers.
+
+## Verification
+
+Node >=22 (CI Node 22); native Android ADB and local Xcode for iOS probes.
+
+| Criteria | Check |
+| --- | --- |
+| 1, 2: launch, awake/asleep/locked/recovery | Updated server against explicit Android emulator; sleep disposable emulator, launch Settings, inspect readiness, restore awake state |
+| 2: transition/conflict/missing fields | Deterministic parser fixtures and failed native probes |
+| 3: blocker gating and unknown compatibility | Readiness/predicate wait unit integration |
+| 4: debugger, targeting, timestamps, compact/journey | Shared action and probe unit integration; existing debugger guard tests |
+| 5: required checks | `npm run verify`, `npm run test:device` |
+| iOS boundary | Updated probe against explicitly booted iPhone 17 Pro simulator; verify capability rejection and unknown wakefulness, then shutdown |
+
+Device suite is Android-focused and may contain opt-in checks; record skips.
+Physical iOS unavailable; do not claim physical support. CI additionally compiles
+the Java worker with JDK 17 and checks package contents; the latest results below
+supersede the initial unrun status.
+Use existing Settings app for launch reproduction, no user app data changes.
+Restore emulator wake state and shutdown any simulator booted for this task.
+
+## Results
+
+Implementation and required baseline verification completed; detailed evidence
+and later PR repairs follow. Remaining platform risks: vendor-specific Android output,
+extra probe latency, iOS capability differences, and budget expiry during probes.
+No publication, release, or protected-branch change is planned.
+
+## Implementation results
+
+Implemented the separate device-readiness contract, Android power/keyguard
+parsers, capability-based iOS lock query, pre-observation wait gating, and shared
+launch/input response evidence. Known blockers break UI-stability continuity;
+recovery requires fresh UI samples. Compact actions and journey action steps
+retain the evidence; the separate adjust_control result also carries it. Dispatch success and verification controls retain their
+existing meanings. Updated tool descriptions and their full compatibility
+fixture, README, tool docs, and changelog.
+
+Focused review covered resolved-device ownership, no cross-call cache, partial
+probe failure, conservative parsing, response preservation on observation
+failure, debugger priority, and operation-budget clipping. CoreDevice requires
+its own timeout argument to be >=5 seconds; the parent process enforces the
+1,000 ms probe deadline. Android 17 repeats a numeric wakefulness enum in a later
+vendor section: parsing now isolates the named current-state section. Both
+runtime discoveries have deterministic regression coverage. No raw native dumps
+are included in the response or retained evidence.
+
+## Initial device evidence — 2026-11-04
+
+Local server version 0.36.0, modified checkout based on
+`46f86bae52f09be4499867ac581f9308d3892e41`, Node v23.11.0 (supported >=22).
+This is local source/built-server evidence, not a published package or hosted CI.
+
+- **PASS — Android emulator 16, emulator-5554:** started awake/unlocked;
+  observed a real transitioning-to-asleep state, launched Settings with
+  verification disabled, and established successful dispatch alongside
+  DEVICE_ASLEEP. Readiness wait returned READINESS_TIMEOUT while asleep, then
+  passed after wake-up with fresh settled UI evidence. Restored awake/unlocked
+  and Home. [Evidence](android-evidence.json).
+- **PASS — Pixel 9 Pro, Android 17:** passive state read established
+  DEVICE_LOCKED and input_ready=false. No input or state changes were sent.
+  The first power sample was conservatively unknown because of duplicate
+  vendor-debug fields; the scoped parser subsequently observed awake/unlocked
+  with both timestamped signals. These are separate observations of natural
+  device changes, not an automated lock/unlock journey.
+  [Lock evidence](android-physical-evidence.json),
+  [power evidence](android-physical-power-evidence.json).
+- **PASS — iPhone 17 Pro simulator, iOS 26.4:** updated native probe and actual
+  get_app_readiness MCP call returned lock_state=unsupported from CoreDevice's
+  matching capability rejection, wakefulness=unknown, and input_ready=null.
+  UI readiness could still report settled without claiming input readiness.
+  Simulator restored to shutdown. [Probe](ios-probe-evidence.json),
+  [MCP result](ios-tool-evidence.json).
+- **UNRUN — real locked emulator journey:** this emulator wakes unlocked;
+  security settings were not changed. Locked classifier evidence exists on the
+  physical Pixel, and locked wait gating has deterministic integration coverage.
+- **UNRUN — physical iOS, live debugger-paused reproduction, true iOS sleep and
+  lock/unlock recovery:** no physical iOS device; opt-in debugger fixtures were
+  not run. Managed debugger precedence is covered by deterministic tests, not
+  claimed as a new live debugger journey.
+
+## Initial verification results — 2026-11-04
+
+- `npm run verify`: passed, including the rerun after the Android 17 parser
+  refinement. Final lint/build and focused action tests also passed after review. Includes lint, size/dependency checks, TypeScript build,
+  complete unit suite, and agent-plugin consistency.
+- Focused device-readiness parser/probe/action tests, readiness tool/wait tests,
+  and compact journey tests: passed. Covers partial probe failure, explicit
+  unknown/unsupported outcomes, targeting, timestamps, expired budgets, no raw
+  error leakage, blocker gating, fresh recovery, and dispatch preservation.
+- `npm run test:device`: passed with a booted iOS simulator. Android/iOS
+  screenshots, logs, trees and correlated-evidence checks passed; Android system
+  tracing passed with cleanup. Optional coroutine/Kotlin/debugger/interaction
+  fixtures and iOS tracing were unrun. The new explicit emulator readiness
+  journey was run separately with MCP_READINESS_DEVICE=emulator-5554.
+  Initial suite invocation without a booted simulator failed at the iOS
+  screenshot prerequisite; booting the simulator resolved that prerequisite.
+- `git diff --check` and changed documentation relative-path checks: passed.
+- CI uses Node 22, plus JDK 17 worker compilation/package checks. These extra
+  hosted checks were not run here. No commit, push, release or publication.
+
+The GitHub project status move remains unconfirmed; CLI project access lacks
+read:project, and browser actions were interrupted by concurrent user navigation.
+No ticket completion or remote publication is claimed.
+
+## PR #104 review repairs — 2026-11-04
+
+Lightweight fixes restoring the approved contract, based on the four attached
+unresolved review threads at head `b78268b`:
+
+- Reset UI-change candidate, change kind and stability timestamp when a device
+  blocker skips sampling. A deterministic clock test proves the full change
+  stability window must elapse again after recovery.
+- Retain last-known blocked power/keyguard axes within the same wait when a
+  later probe is inconclusive, including original evidence timestamps and new
+  failure limitations. Fresh conclusive evidence clears each axis independently.
+  Regression tests cover partial recovery, expired probes and READINESS_TIMEOUT.
+- Preserve the native tap/swipe response's resolved device in the action result.
+  No new target resolution or guarded-selection change. Tested implicit,
+  explicit and already-resolved targeting in debug/compact responses.
+- Attempt every emulator restoration command independently and always close the
+  client in a nested finally. Aggregate failures after all attempts; report PASS
+  only after successful cleanup. Injected failures cover each ADB step and close.
+
+All three production regressions were demonstrated to fail against the original
+PR head and pass with these fixes. `npm run verify`, focused regressions and
+final lint passed. Device verification results are recorded below.
+
+PR repair verification used local Node v23.11.0 and server 0.36.0. On Android 16
+`emulator-5554`, the updated stdio MCP server reported DEVICE_ASLEEP alongside
+successful start_app, ordinary tap and swipe dispatches. The readiness wait
+returned READINESS_TIMEOUT with DEVICE_ASLEEP still present, then recovered
+awake/unlocked; all restoration commands and client close completed. The first
+device-suite attempt timed out at the initial readiness RPC before state
+changes. A focused retry passed, as did the same journey in the serial suite
+retry. No timeout or assertion was weakened. Failed-cleanup paths were verified
+with injected failures rather than disconnecting a real emulator.
+
+The serial `MCP_READINESS_DEVICE=emulator-5554 npm run test:device` run passed,
+including Android/iOS screenshots, logs, UI trees, correlated evidence and
+Android trace cleanup. The iPhone 17 Pro iOS 26.4 simulator was temporarily
+booted and restored to shutdown. Optional coroutine/Kotlin/debugger/interaction
+fixtures and iOS tracing remained unrun. Hosted CI/JDK 17 package checks remain
+separate from these local results. `git diff --check` passed.
+
+## Additional checks without physical devices — 2026-11-05
+
+Requested follow-up: run remaining checks on emulators/simulators and record
+limits explicitly. No physical device was selected. Existing fixture tests now
+also assert the new device_readiness DEBUGGER_PAUSED blocker and input_ready=false,
+and immediate DEBUGGER_PAUSED from wait_for_app_ready on both platforms.
+
+- **PASS — Android emulator debugger**, including the real 60-second pause limit,
+  paused readiness and wait blockers, source/locals/stepping, recovery and owned
+  resource cleanup. JDK 17.0.11, emulator-5554, Android API 36, extended mode.
+  Log: `/tmp/readiness-extra-android-debugger-retry.log`.
+- **PASS — iOS simulator debugger**, including paused readiness and wait blockers,
+  async/cancellation, real pause expiry, disconnect and shutdown recovery, and
+  fixture cleanup. iPhone 17 Pro simulator, iOS 26.4, Xcode 27.2 (27B52),
+  Swift-enabled LLDB, extended mode. Fixture-only command-file triggers are used;
+  this proves debugger/readiness behaviour, not successful iOS HID tap delivery.
+  Log: `/tmp/readiness-extra-ios-debugger-retry.log`.
+
+The first Android extended run failed its expiry assertion with paused state and
+pending cleanup after pause_limit was selected; its unchanged-deadline retry
+passed. The first iOS attempt timed out during fixture installation; the retry
+passed without increasing the install timeout. These initial failures remain
+recorded in `/tmp/readiness-extra-android-debugger.log` and
+`/tmp/readiness-extra-ios-debugger.log`; they are not counted as passes.
+
+- **PASS — Android interaction fixture:** clickable/visible waits, stored handles,
+  selector journey, enabled-state assertion and labelled SeekBar convergence.
+  Log: `/tmp/readiness-extra-interaction.log`.
+- **PASS — Kotlin locals fixture:** known values before/after assignments,
+  stale-frame rejection, UI recovery and owned-forward cleanup. Kotlin/stdlib
+  2.0.21 and JDK 17.0.11. Log: `/tmp/readiness-extra-kotlin.log`.
+- **PASS — coroutine fixture:** source stops around suspension, dispatch-thread
+  locals, completion, cancellation/finally, pause guards and cleanup. Uses the
+  same compiler plus coroutines 1.9.0. No logical coroutine-stack claim.
+  Log: `/tmp/readiness-extra-coroutine.log`.
+- **PASS — local CI-equivalent extras:** JDK 17 worker compilation and all 23
+  package inventory entries from the current CI workflow. Hosted unit checks
+  for PR #104 head `28d73ff` were also confirmed successful.
+
+All Android fixtures ran sequentially on emulator-5554, and removed their own
+packages, temporary builds and debugger forwards. No production source changes
+were required. The default iOS trace runner verified capture/cancel/expiry/shutdown cleanup but
+failed its input journey: the installed idb_companion 1.1.8 expects SimulatorKit
+under Developer/Library/PrivateFrameworks, absent in Xcode 27.2. A direct input
+probe confirmed that error. No production or installed Xcode files were changed.
+
+Using the documented test-owned Xcode path alias and isolated companion, the
+traced tap-to-Done journey passed with 53 exported sample rows; cancellation,
+expiry, stale-ID rejection and failed-journey handling also passed. The same
+run failed the final server-shutdown partial-directory assertion, so the overall
+compatibility trace run remains **FAIL / partial**, not a pass. A subsequent
+resource check found no recorder processes or owned trace directories left.
+Logs/evidence: `/tmp/readiness-extra-ios-trace.log`,
+`/tmp/readiness-extra-ios-trace.json`,
+`/tmp/readiness-extra-ios-trace-compatible.log` and
+`/tmp/readiness-extra-ios-trace-compatible.json`.
+
+Remaining software follow-up: investigate the intermittent iOS trace shutdown
+cleanup assertion and provide a compatible default idb HID backend. True iOS
+sleep/lock recovery cannot be established by this simulator's unsupported lock
+probe and unverified wakefulness signal; physical iOS remains outside this
+verification run. The default emulator's secure-lock journey was not enabled by
+changing security settings; locked wait gating has deterministic coverage and
+prior passive Pixel evidence. No new hardware validation is claimed.
+
+Final `npm run verify` passed with the new Android/iOS paused-readiness
+assertions. Changed documentation paths and `git diff --check` passed. The
+compatibility companion, alias and local JDK compilation output were removed,
+and the test-owned simulator was restored to shutdown. The verification-only
+test changes and this plan update remain local and uncommitted.
+
+
+### iOS trace shutdown issue repaired — 2026-11-05
+
+The shutdown finalizer now removes discarded files after a stop error if the
+owned recorder has exited; it retains the failure reason and never removes a
+possibly live recorder's directory. Regression tests failed on the old code and
+passed with the fix. The full simulator trace journey then passed its original
+shutdown assertion, with 59 exported sample rows and complete cleanup.
+`npm run verify` passed. See [trace repair record](../031-ios-system-traces/plan.md#shutdown-cleanup-repair--2026-11-05).
+This supersedes the earlier failed shutdown check; the default idb compatibility
+limitation and hardware-only coverage remain explicitly separate.
+
+The shutdown repair also passed the baseline device suite. Temporary verification
+resources were removed and the simulator restored to shutdown. The repair and
+verification updates are local and uncommitted.

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

@@ -0,0 +1,134 @@
+# Specification: device readiness blockers
+
+Status: approved. User accepted the revised specification with “ok, lets proceed”
+in the current chat on 2026-11-04; implementation is authorised for this scope.
+Intent: [approved intent](intent.md), user response “ok”, 2026-11-04.
+Source: [issue #101](https://github.com/clivejefferies/mobile-debug-tools/issues/101).
+
+## Behaviour
+
+Keep launch dispatch, normalized UI stability, and device accessibility distinct.
+Successful `start_app` / `restart_app` dispatch does not establish app visibility,
+unlocked state, or input readiness. Existing success, verification, and
+`observed_app.matchedTarget` fields retain their meanings. Device observations
+must never upgrade dispatch success into proof that the app is usable.
+
+Add `device_readiness` to launch/restart results, interaction action results,
+`get_app_readiness`, `wait_for_app_ready`, and readiness-enabled
+`wait_for_ui` / `wait_for_ui_change` results. Preserve it in compact and debug
+responses, including failures after target resolution. Journey action steps use
+the same representation. Ordinary waits without `requireReady` keep their
+predicate semantics. No new tools or input parameters are introduced.
+
+The additive object has:
+
+- `wakefulness`: `awake | asleep | transitioning | unknown | unsupported`.
+- `lock_state`: `locked | unlocked | unknown | unsupported`.
+- `input_ready`: `false | null`. False means an observed device blocker; null
+  means readiness is not established. Awake/unlocked alone never yields true.
+- `blockers`: zero or more of `DEVICE_ASLEEP`, `DEVICE_LOCKED`,
+  `DEVICE_TRANSITIONING`, `DEBUGGER_PAUSED`.
+- `evidence`: at most eight entries containing `code`, `source`, and host
+  epoch `captured_at_ms`. No raw command output or UI text.
+- `limitations`: bounded codes for unavailable, unsupported, conflicting, or
+  failed observations. Each axis has an explicit value even when unavailable.
+
+Each successful native sample carries its own timestamp. An unknown axis has
+no invented timestamp. Evidence is scoped to the explicitly resolved device
+and current operation, with no cross-call cache. Observations describe their
+capture time; they cannot guarantee the device remains unchanged afterward.
+
+## Platform evidence
+
+Android uses bounded, explicitly targeted ADB reads of `dumpsys power` and
+`dumpsys window policy`. Parse recognized current-state fields only. Awake and
+asleep require explicit wakefulness evidence; a wakefulness-change flag yields
+transitioning. Dozing is treated as asleep for input readiness. Keyguard showing
+means locked even if occluded; explicit non-showing means unlocked. Missing,
+unrecognized, contradictory, or truncated fields produce unknown for the
+affected axis. Device keyguard capability alone is not lock-state evidence.
+Retain independent evidence when one probe fails. Unknown Android variants must
+not be classified by text labels, screenshots, or command success alone.
+
+iOS support is determined per signal and target, not by a blanket platform
+assumption. Apple's `devicectl device info lockState` provides a lock-state
+probe, but the tested iOS 26.4 simulator explicitly rejects it with CoreDevice
+error 1001 and feature `com.apple.coredevice.feature.getlockstate`. That explicit
+capability rejection yields unsupported for the lock axis; ordinary probe errors
+yield unknown. A recognized successful structured response may establish lock
+state only once its semantics and compatibility have been verified. Physical
+iOS integration is outside this ticket's existing simulator-only lifecycle path;
+the command's existence does not establish physical-device support in this MCP.
+
+For the tested simulator, wakefulness remains unknown: display information is
+available, but neither `simctl io enumerate` port power nor devicectl backlight
+state reliably distinguished an accepted display-off command in this experiment.
+Return `DEVICE_WAKEFULNESS_UNVERIFIED`, not an inferred awake/asleep state.
+Simulator boot status, launch PID, SpringBoard labels, and a static tree do not
+prove awake/unlocked state. No private iOS APIs, helper app, or security-setting
+changes are introduced. See [iOS investigation](ios-investigation.md).
+
+## Integration, precedence, and failure
+
+Keep the existing `ReadinessSummary.state` enum and UI evidence unchanged for
+compatibility, but a known device blocker prevents readiness-wait success even
+if the UI appears settled. `get_app_readiness` may successfully report an
+observed blocker; a readiness wait continues within its existing budget to allow
+natural recovery. At expiry it returns `READINESS_TIMEOUT` with last evidence.
+Managed debugger pause retains existing immediate `DEBUGGER_PAUSED` behaviour
+and guard precedence. Combine available blockers without replacing debugger
+session evidence or triggering a UI read while that guard blocks one.
+
+Unsupported/unknown device observations do not prevent existing settled-UI wait
+success; documentation must make clear that this still does not prove input
+readiness. After observation failure, never reuse a previous known clear state
+to claim the device is clear. A later fresh sample can establish recovery.
+
+For actions, collect one post-action device sample within the existing action
+budget, including verification mode `none`; do not add a UI-tree read for this
+feature. Preserve dispatch outcomes on observation failure and expose unknown
+with a limitation. A sleeping/locked result does not introduce a new input guard
+or retry. Calls already blocked by the debugger retain their existing failure.
+If target resolution fails, return unknown with a target-unavailable limitation.
+
+Each native probe has a maximum 1,000 ms timeout, clipped to the remaining
+operation budget. No additional timeout window, retry, detached subprocess, or
+automatic device selection is allowed. Existing cancellation and child-process
+cleanup apply. Do not begin a probe after budget expiry.
+
+## Acceptance and verification
+
+1. Reproduce launch while asleep/locked on a disposable Android emulator where
+   practical; record dispatch outcome separately from device-state evidence.
+2. Verify awake/unlocked, asleep, locked, transition/conflict, missing fields,
+   probe failure, expiry, and recovery. Use real-device evidence for supported
+   stable states and deterministic fixtures for fleeting transitions.
+3. Verify a stable lock-screen tree cannot complete a readiness-enabled wait;
+   unknown/unsupported remains explicit without changing ordinary predicates.
+4. Verify managed debugger precedence, targeting, timestamp freshness, compact
+   serialization, journey propagation, and absence of raw dumps in responses.
+5. Run `npm run verify` and applicable `npm run test:device`; report exact device,
+   server build, outcomes, cleanup, and unrun platforms. No claim of iOS state
+   detection is made without matching runtime evidence.
+
+## Ownership, security, and investigation evidence
+
+Affects readiness services/contracts, action execution/serialization, lifecycle
+results, tool descriptions, tools documentation, README, and changelog. Reuse
+existing budgets, subprocess helpers, and resolved-device context. Raw system
+dumps can include private metadata: parse locally and retain only enumerated
+flags. Never unlock, wake, or alter security settings automatically. Verification
+may sleep/wake a disposable emulator and must restore its starting state; do not
+change the user's physical phone for reproduction.
+
+On 2026-11-04, connected MCP discovery reported an Android 16 emulator
+`emulator-5554`, a physical Android phone, and no booted iOS simulator. Read-only
+ADB probes on the emulator exposed `mWakefulness=Awake`,
+`mWakefulnessChanging=false`, and keyguard `showing=false` / `mIsShowing=false`.
+These establish available baseline fields only; sleeping/locked reproduction
+and updated-server verification remain unrun. Local sandboxed simctl access
+failed to connect to CoreSimulator, so it supplies no iOS runtime evidence.
+
+The user approved this complete revised contract, including additive fields,
+known-blocker wait gating, and per-signal iOS unknown/unsupported behaviour,
+with “ok, lets proceed” on 2026-11-04.

package/docs/specs/034-app-installation-status/intent.md

@@ -0,0 +1,41 @@
+# Intent: trustworthy app installation status
+
+Status: intent approved; specification pending.
+Originator: GitHub issue #98; author identity not independently checked.
+Captured: 2026-11-05.
+Source: https://github.com/clivejefferies/mobile-debug-tools/issues/98
+
+## Problem
+
+Agent feedback reported `appInstalled: false` while Modul8 was installed and
+running. The original device, app context and query are not yet established.
+Current code can represent missing app context or failed installation queries
+as absence; Android system status also queries without explicit device targeting.
+These findings explain possible failure paths, not a reproduction of the report.
+
+## Desired outcome and scope
+
+Make installation reporting trustworthy for MCP clients using device inventory
+and system status on Android and iOS. Distinguish confirmed installed, confirmed
+absent and unknown/check-failed results, with explicit app and device context
+and the scope of the check. Review device selection consumers so unknown status
+cannot be mistaken for confirmed absence or used as unsupported targeting evidence.
+
+Success includes meaningful coverage for installed/running and absent apps,
+missing app context, multiple devices and failed queries. Reproduce the original
+inconsistency where practical, otherwise document the evidence and limits.
+Align tool descriptions and diagnostics with the accepted contract.
+
+## Constraints and open questions
+
+Preserve existing compatibility where possible; any response-contract change
+requires specification approval. Use bounded, device-specific queries and avoid
+installing, removing or launching user apps merely to check installation.
+Automatic installation, broader readiness changes and expanded platform support
+are excluded. Investigation will establish reliable absence evidence on each
+supported platform and how legacy `appInstalled` maps to unknown results.
+
+## Approval
+
+The user approved the captured intent with “yes” in this chat on 2026-11-05.
+This approves the problem and scope; response contracts await specification approval.