mobile-debug-mcp 0.35.0 → 0.37.0

package/docs/specs/036-end-to-end-interaction-latency/intent.md

@@ -0,0 +1,37 @@
+# End-to-end interaction latency — intent
+
+Status: accepted on 2026-11-06. The user replied “ok” to the proposed intent
+and its scope in this chat. This approves investigation and specification;
+specification acceptance is still required before implementation.
+Originator: Clive Jefferies, GitHub issue #100; picked up at the user's request on 2026-11-06.
+Source: https://github.com/clivejefferies/mobile-debug-tools/issues/100
+
+## Problem and outcome
+
+Agent feedback reports observations taking several seconds during small UI
+refinements. Establish reproducible measurements of complete MCP action and
+observation round trips, separating MCP overhead from Gradle builds, application
+work, and external test-suite time. Optimize only bottlenecks supported by those
+measurements; a documented negative finding is a valid outcome.
+
+## Scope and success
+
+Reuse the existing interaction-latency benchmark and coordinate iOS UI-tree
+measurements with issue #89 and its existing fixture. Measure Android and iOS
+separately and compare relevant response and verification modes. Report repeated
+runs, p50/p95, failed attempts, device/platform, server build, tool versions, and
+component costs: targeting/readiness, subprocess acquisition, screenshots, UI
+trees, waits, verification, and serialization. Identify attribution limits.
+
+Any proposed optimization must improve the same baseline while preserving fresh,
+device-scoped evidence, assertions, required verification, deadlines,
+cancellation, and child-process cleanup. Report unavailable platform coverage
+explicitly. Existing MCP clients must retain their agreed contracts.
+
+## Constraints and open questions
+
+No speculative caching, hidden failures, reduced verification, or duplicated iOS
+tree fixture. Runtime or contract changes require an accepted specification.
+Investigation will establish available devices, reproducible workloads, useful
+sample counts, and existing timing coverage before specification. No performance
+target or optimization is assumed in advance.

package/docs/specs/036-end-to-end-interaction-latency/plan.md

@@ -0,0 +1,59 @@
+# Implementation and verification plan
+
+[Intent](intent.md) and [specification](spec.md) accepted by the user in this
+chat, each with “ok” on 2026-11-06. No runtime optimization is authorized.
+
+## Work
+
+- Add opt-in request timing events using existing AsyncLocalStorage timing and
+  tree metrics. Include subprocess intervals, preserve normal responses/output.
+- Add a dedicated end-to-end benchmark alongside the historical Spec 018
+  benchmark. Reuse its fixture and journey, alternate modes, retain failed
+  attempts, record build identity and separate setup phases, write new reports.
+- Add deterministic tests for accounting, privacy, disabled instrumentation,
+  nested/concurrent timing and owned process cleanup. Bound fixture builds.
+- Run validation, then device measurement. Review reports and document
+  bottlenecks, negative findings and coverage limitations. No speculative fixes.
+
+## Verification mapping
+
+| Acceptance | Check |
+| --- | --- |
+| Reproducible attempts and percentiles | Unit report checks; repeated Android run (3 warm-ups + 10 attempts/case) with environment/build hashes |
+| Separate phases/components/overhead | Setup ledger; request/tree spans; instrumented/uninstrumented observation comparison |
+| Assertions and platform coverage | Six-transition fixture journey in all modes; report explicit iOS blocker and #89 ownership |
+| Contracts and cleanup | Opt-in instrumentation unit tests; timeout/interrupt owned-process checks; `npm run verify`; `npm run test:device` |
+| Optimization discipline | Report measured findings; no optimization in this stage |
+
+Commands: `npm run verify`, `npm run test:device`, and
+`LATENCY_DEVICE_ID=emulator-5554 MCP_ADB_TIMEOUT=30000 npx tsx test/device/automated/latency/end-to-end.ts`.
+Requires Node >=22, installed npm dependencies, Java capable of `--release 8`,
+Android platform/build-tools 36/36.0.0, adb and a running emulator. Fixture build
+uses existing offline SDK tools; no Gradle or network dependency.
+
+Device starting state: explicitly named Android emulator, dedicated fixture
+installed/reset by harness; no display/settings changes. Each attempt starts
+with reset fixture and stopped process. Journey asserts every destination;
+observations use its known final screen. Evidence: timing-only JSON/Markdown,
+fixture/build hashes, attempt outcomes, cleanup status. Remove run-owned remote
+temporary files, force-stop fixture and close server on completion/interruption;
+preserve pre-existing apps/settings.
+
+iOS: no simulator was booted during specification. No shared #89 static/network
+fixture exists in this checkout; fixture journey remains blocked pending that
+work. Record simulator availability again during execution. Physical iOS is
+excluded. Existing suite may skip optional fixture checks; report actual scope.
+
+Risks: instrumentation perturbation, nested intervals, emulator contention,
+long full-verification runs. Keep transport residual unlabelled, document gaps,
+stop measurement after unsafe timeout/cleanup failure, preserve partial reports.
+No commit/push/release is included.
+
+## Results
+
+Benchmark code, request instrumentation and timing reports are implemented.
+Android produced nine successful measured samples per case, two additional
+measured failures, three warm-up failures and nine unrun attempts before an
+emulator crash. The iOS smoke reached its readiness check and produced zero
+timing samples. See [findings](../../benchmarks/end-to-end-latency/investigation.md)
+and [verification](verification.md) for evidence, cleanup and remaining gates.

package/docs/specs/036-end-to-end-interaction-latency/spec.md

@@ -0,0 +1,126 @@
+# End-to-end interaction latency — specification
+
+Status: accepted on 2026-11-06 by the user's “ok” in response to the complete
+specification in this chat. The [intent](intent.md) was
+accepted by the user's “ok” on 2026-11-06. Source: [issue #100](https://github.com/clivejefferies/mobile-debug-tools/issues/100).
+
+## Outcome and boundaries
+
+Publish reproducible current-build round-trip measurements and identify where
+time is spent. Reuse Spec 018's Android fixture and stdio MCP harness, Spec 019's
+tree metrics, and existing timing helpers. This stage authorizes benchmark and
+opt-in instrumentation changes, not runtime optimizations. A measured candidate
+requires a specification amendment identifying its path, correctness risks,
+and comparison criteria before implementation. A negative finding is valid.
+
+No new MCP tools, arguments, response fields, errors, defaults, verification
+semantics, or caching are introduced. Instrumentation is disabled by default
+and emits only benchmark diagnostics to stderr, preserving stdio protocol output.
+
+## Measurement protocol
+
+Measure a locally built server over a real SDK stdio client. Record commit,
+working-tree state and source/build hashes, package and Node versions, host,
+platform/OS, device model, emulator configuration, fixture hash, and applicable
+adb/Xcode/idb versions. Dirty source is explicitly identified; generated reports
+are distinguished from changes to measured source. Capture exact commands,
+timeouts, instrumentation settings, starting state, and run order.
+
+Reuse the six-transition Android fixture journey with explicit destination
+assertions. Retain the standalone handle-based comparison. Compare journey
+full/debug, full/compact, light/debug and light/compact to separate response-mode
+cost from verification cost. All comparisons retain destination assertions.
+Do not use verification `none` as evidence of equivalent verification.
+
+Each case receives three warm-ups and ten measured attempts. Alternate mode
+order across rounds to reduce ordering bias. Preserve warm-up failures separately
+from measured failures. Report raw per-attempt durations, success/failure and
+stage, sample counts, nearest-rank p50/p95, minimum and maximum. Percentiles
+describe successful attempts only; failures remain visible and prevent a claim
+that the entire run passed. Missing samples produce unavailable statistics,
+never zero latency. Ten samples provide a preliminary p95, not a robust tail
+estimate; state that limitation.
+
+Measure `capture_screenshot`, `get_ui_tree`, and screenshot/log-free
+`capture_debug_snapshot` separately on the same known fixture screen. Record
+response byte counts without retaining response contents. Fixture build,
+installation/reset, server startup, and any Gradle or validation-suite execution
+are separate phases excluded from steady-state MCP round trips. Device-side
+application work within a round trip remains included unless independently
+measured; do not mislabel it as pure MCP overhead.
+
+## Attribution
+
+Use monotonic clocks for client request-to-response and server intervals.
+Attribute device resolution/readiness, subprocess/tool acquisition, screenshot
+capture/encoding, physical tree acquisition/retries/parsing, waits, dispatch,
+verification/assertions, and response construction/JSON serialization where
+observable. Reuse existing timing and observation events before adding probes.
+Correlate events using generated request/acquisition IDs and serialize requests
+within a run. Document inclusive/nested intervals; do not sum overlapping spans.
+
+Report unattributed residual time explicitly. Client round-trip minus server
+timing includes transport, scheduling and uninstrumented work; it is not an
+exact transport or serialization measurement. SDK wire serialization and device
+application execution may remain unattributed. Instrumentation failures or
+missing events are diagnostic gaps, never invented component timings. Compare
+instrumented and uninstrumented observation runs to disclose probe overhead.
+
+## Platform ownership and safety
+
+Pin every request to an explicit device; never fall back to a physical phone.
+Run one fixture workload at a time. Reset/install only the dedicated Android
+fixture, restore changed settings, and remove run-owned temporary files and
+processes. Do not change display configuration silently. No real user app data
+is reset. Reports omit device serials, screenshots, UI trees, logs, credentials,
+raw command arguments and unrestricted subprocess output; use fixture aliases
+and sanitized failure classifications.
+
+[Issue #89](https://github.com/clivejefferies/mobile-debug-tools/issues/89) owns
+the iOS static/network fixture and paired tree protocol. Reuse it when available;
+do not create a competing fixture here. Standalone iOS observation measurements
+may use an explicitly identified stable simulator screen, separately labelled
+from fixture journeys. If no simulator or shared fixture is available, report
+those cases blocked with prerequisites and runnable next steps. Physical iOS
+coverage is excluded from this simulator investigation.
+
+## Failures and verification
+
+Preserve existing action, wait and verification deadlines. Bound harness calls
+and setup operations; on timeout, cancellation or interrupt, record the failed
+attempt and close the owned client/server. Verify owned subprocess exit and
+cleanup; do not kill unrelated processes or leave a timed-out request running
+while measuring another. If safe recovery cannot be established, stop that case
+and report remaining attempts unrun. Never retry invisibly.
+
+Use unit checks for percentile/failure accounting, redaction, correlation and
+instrumentation enabled/disabled behavior where changed. Run `npm run verify`
+and applicable `npm run test:device`, plus the repeated benchmark. Runtime
+changes later require focused deadline, cancellation, cleanup, freshness,
+device-isolation and stabilization regression checks and paired results on the
+same fixture, settings and instrumented baseline. Existing Spec 018/019 gates
+remain applicable to their original comparisons; new mode measurements must
+not be forced through unrelated speedup gates.
+
+## Acceptance and reporting
+
+1. Reports reproduce each measured case with environment/build identifiers,
+   commands, run order, p50/p95, raw attempts and visible failures.
+2. Phase and component attribution separate setup/build/test-suite time, expose
+   overlap and gaps, and quantify instrumentation overhead.
+3. Mode comparisons retain assertions; platform coverage and #89 dependencies
+   are explicit. Report observed bottlenecks or a justified negative finding.
+4. No public contract or normal diagnostic-output change occurs. Cleanup,
+   timeout and interrupt checks pass for changed harness paths.
+5. Any later optimization has separately accepted scope and improves its paired
+   baseline without correctness or verification regressions.
+
+Expected modules: existing latency benchmark/report helpers, shared benchmark
+support where useful, opt-in timing hooks near server/observation/subprocess
+boundaries, focused unit tests, and benchmark documentation. Main risks are
+probe overhead, nested-span double counting, emulator variance, and unavailable
+iOS prerequisites; reports must expose each rather than hide it.
+
+Investigation on 2026-11-06 found an attached Android emulator and no booted iOS
+simulator. The existing latency and tree harnesses are Android-only. These are
+prerequisite observations, not current-build performance or correctness results.

package/docs/specs/036-end-to-end-interaction-latency/verification.md

@@ -0,0 +1,87 @@
+# Verification evidence
+
+## Local checks
+
+- `npm run verify`: **pass** on the final checkout with device workloads stopped. Lint,
+  structural/architecture gates, TypeScript build, 112 automated unit files and
+  agent-plugin consistency checks completed. Local Node is 23.11.0; CI uses 22.
+- The run overlapping iOS startup and smoke execution failed the existing
+  `server/conditional_actions.test.ts` 150 ms action-budget assertion. The
+  assertion was preserved and passed on the final run.
+- New deterministic checks cover failed/empty sample accounting, overlapping
+  spans, observation validity/device identity, metric redaction, instrumented and
+  uninstrumented return behavior, concurrent request isolation, and exception
+  recording. The real process test verifies timeout/interrupt cleanup including
+  a child that ignores SIGTERM. Darwin's transient post-kill EPERM is treated as
+  unconfirmed existence until ESRCH; it never counts as successful cleanup.
+- `git diff --check`: **pass** during implementation; repeat at final review.
+
+The final CI workflow also compiles the optional Java debugger worker and checks
+package contents; those additional checks are not part of `npm run verify` and
+were not separately executed for this instrumentation-only change. Android
+integration CI is manually triggered. No hosted CI run or installed-package
+compatibility result is claimed.
+
+## Native evidence
+
+All executed Android actions target the named Android 16/API 36 emulator.
+The connected physical Android phone was not selected for actions. For the
+existing device suite, a temporary ADB_PATH forwarding script exposed only the
+emulator in discovery, rejected different explicit serials, and forwarded real
+commands to the installed adb; no tool output or assertions were mocked. The
+benchmark itself uses the real adb and explicit device IDs, and records discovery
+topology because existing device resolution can enumerate other attached devices.
+
+- `ADB_PATH=/private/tmp/ticket100-adb MCP_ADB_TIMEOUT=30000 npm run test:device`:
+  **blocked / exit 1**. Android compact-result smoke passed dispatch-only,
+  post-observation, absent-target, journey, and diagnostics checks. The next
+  iOS branch asserted that a booted simulator was required and stopped the suite.
+  Optional coroutine, Kotlin and runtime debugger fixture checks reported unrun.
+- Individually executed `capture_screenshot.android.smoke.ts`,
+  `get_ui_tree.android.smoke.ts`, and `get_logs.android.smoke.ts` using the same
+  forwarding configuration: **pass**. These are real emulator observation
+  checks, separate from benchmark timing and iOS coverage.
+- Development `end-to-end.ts --smoke`: **pass**, 11/11 cases, both owned servers
+  and fixture cleanup confirmed. This was a harness-development run; later
+  attribution/validation additions mean its source/build is not the final
+  repeated-run baseline. It is explicitly not performance evidence.
+
+The default device smoke leaves Android Settings foreground; it changes no
+settings or user app data. Benchmark attempts reset only the dedicated latency
+fixture, change no display settings and force-stop the fixture on exit. Existing
+fixture installations are retained; run-created installations are removed.
+
+## Platform prerequisites
+
+`xcrun simctl list devices booted` initially found no booted simulator. A PATH-only
+check missed idb, but subsequent inspection of the owning `getIdbCmd()` resolver
+found a working common-location fallback; its Python package is fb-idb 1.1.7.
+The original PATH-based unavailable assessment was incorrect. Android raw
+metadata retains that initial PATH probe; it does not establish iOS tool absence.
+
+The isolated iPhone 17 Pro booted iOS 27.2 runtime build 24B8117. The local
+stdio smoke failed the Settings readiness assertion after 32.6 seconds and
+recorded zero performance samples. A subsequent Mobile Debug MCP screenshot
+showed a blank app content area. Its UI tree reported the idb prerequisite
+unavailable. Direct `idb list-targets --json` failed with a companion listing
+error, though a later direct `idb_companion --list 1` succeeded. Root cause
+remains unresolved. Both owned servers exited. The temporary simulator was
+shut down and removed, and its remaining idb companion was stopped by matching
+the temporary simulator ID. The full native suite remains incomplete.
+
+The shared #89 static/network fixture remains absent. Equivalent fixture
+journeys remain blocked and physical iOS is excluded.
+
+## Original broad performance investigation
+
+Android measurement is partial. Nine successful samples per case precede the
+emulator's exit 139. Two measured and three warm-up failures are preserved, with
+nine planned attempts unrun. Both server groups exited. The crashed emulator
+prevented fixture force-stop confirmation. See the
+[investigation report](../../benchmarks/end-to-end-latency/investigation.md).
+Fixture compilation uses offline SDK tools, not Gradle. Validation-suite runtime
+is outside the benchmark; it is not included in request percentiles. Device-side
+application work remains included in request timings and is not separately
+profiled. The later Android tree-reuse candidate is covered by the
+[snapshot verification](android-snapshot-plan.md) and
+[paired comparison](../../benchmarks/end-to-end-latency/android-snapshot-pair.md).

package/docs/tools/TOOLS.md

@@ -10,9 +10,10 @@ Use the guides below when you need a tool contract or a specific workflow.
 - [Observation](observe.md) — screenshots, logs, UI trees, fingerprints, debug snapshots, and app readiness.
 - [Interaction](interact.md) — UI resolution, actions, waits, and deterministic verification.
 - [Environment diagnostics](system.md) — toolchain discovery and health checks.
+- [Compact interaction results](compact-interactions.md) — output budgets and read-only diagnostics lookup.
 - [Evidence correlation](correlated-evidence.md) — action references, capture timing, and freshness.
-- [Android system traces](system-traces.md) — performance capture and local Perfetto artifacts.
-- [Android runtime debugger](debugger.md) — process attachment, breakpoints, and bounded runtime inspection.
+- [System traces](system-traces.md) — Android Perfetto and iOS simulator Time Profiler capture with local artifacts.
+- [Android and iOS simulator runtime debugger](debugger.md) — process attachment, breakpoints, and bounded runtime inspection.
 
 ## Interaction principles
 

package/docs/tools/compact-interactions.md

@@ -0,0 +1,56 @@
+# Compact interaction results
+
+[Tool reference](TOOLS.md)
+
+Use `responseMode: "compact"` on tap, tap_element, swipe, scroll_to_element,
+type_text, press_back, start_app, restart_app and run_journey. Individual actions
+still default to debug; journeys still default to compact. Other tools retain
+their existing response contracts.
+
+Compact results preserve action outcomes, delivery/verification status, failure
+codes and retryability, device-readiness blockers/limitations and correlation IDs.
+They summarize condition observations and state-delta counts instead of returning
+full trees or changed elements. `observed_state.status` is `observed` only for
+fresh same-device evidence acquired after dispatch; otherwise it is `unknown`
+with a reason. A precondition tree never establishes the resulting UI. A fingerprint
+observation does not identify a screen or prove the intended outcome. Existing
+`verification` semantics are unchanged and separate from observation freshness.
+
+## Read the original result without replay
+
+Every executed compact action/journey step and journey supplies `diagnostics`:
+
+```json
+{"session_id":"UUID","result_id":"UUID","available":true}
+```
+
+Call `get_interaction_diagnostics({"sessionId":"UUID","resultId":"UUID"})`.
+It returns `{"success":true,"result":{...}}` with the retained original payload,
+including full evidence and internally available failure details. This tool performs
+no device action or observation. It does not acquire additional debug snapshots
+that were not requested originally; use debug mode at execution time for those.
+
+Retention is in process memory, at most ten minutes, 100 results, 16 MiB total,
+and 1 MiB per entry. Oldest completed entries are evicted first; reads do not extend
+expiry. Oversized originals report `available:false, reason:"RESULT_TOO_LARGE"`.
+Lookup failure returns `success:false, error:{code,message}`. Codes are
+`INVALID_ARGUMENT`, `SESSION_MISMATCH`, and `RESULT_UNAVAILABLE` (expired, evicted,
+unknown or restarted). Do not automatically replay input when diagnostics expire.
+Payloads may include private UI text and errors; compact mode is not redaction.
+Nothing is persisted to disk by this cache.
+
+## Output bounds and compatibility
+
+The final compact action text is at most 1,280 UTF-8 bytes plus device-ID bytes.
+Journeys have a base budget of 1,280 bytes plus 1,280 per supplied step and caller
+step-ID/device-ID occurrences (their UTF-8 JSON wire encoding, including necessary
+escapes). Optional summaries may be omitted with
+`truncated:true`; resulting state becomes unknown if its summary must be removed.
+Caller IDs, outcomes, blockers and diagnostics references are preserved. Token
+estimates in development reports use ceil(bytes/4), not tokenizer measurements.
+
+Compact clients that inspected full evidence timestamps/observations, condition
+UI trees or state-delta elements must use the diagnostics lookup instead. Evidence
+session/action IDs still work with observation tools' `actionRef`. Debug output
+remains available with its original detailed shape. Journey child diagnostics are
+retained after shared verification and final evidence refresh.

package/docs/tools/correlated-evidence.md

@@ -6,6 +6,12 @@ Use evidence correlation to connect an action with later screenshots, UI trees,
 and logs, and to understand when those observations were captured. Association
 does not prove that the action caused an observed change.
 
+Compact interaction/journey output keeps the correlation IDs and device while
+summarizing observation metadata. Use the returned `diagnostics` reference with
+[`get_interaction_diagnostics`](compact-interactions.md) for original timestamps,
+observation arrays and trace context without replaying input. Debug output retains
+the full evidence envelope described below. `adjust_control` output is unchanged.
+
 ## Associate an observation with an action
 
 Covered actions (`start_app`, `restart_app`, `tap`, `tap_element`, `swipe`,

package/docs/tools/debugger.md

@@ -1,4 +1,4 @@
-# Android runtime debugger
+# Runtime debugger
 
 [Documentation](../README.md) · [Tool reference](TOOLS.md)
 
@@ -98,7 +98,7 @@ state-changing command. Timeout or cancellation does not prove nondelivery.
 Retry incomplete cleanup with `detach_debugger`; never automatically retry
 attach, step or resume, or kill the app/ADB server. Diagnostics improve failure
 classification and do not establish the cause of a previously intermittent error.
-This contract applies to the Android backend; iOS debugging remains unsupported.
+These details describe Android; see the iOS simulator backend below for its prerequisites and recovery guidance.
 
 ## Suspension, limits and cleanup
 
@@ -108,8 +108,8 @@ racing input submission preserves delivery uncertainty and blocks verification.
 Journeys preserve completed steps. Other devices are unaffected.
 
 `get_app_readiness` returns evidence-backed `debugger_paused` without reading the
-UI; readiness waits fail with `DEBUGGER_PAUSED`. This signal covers managed Android
-sessions only and does not establish foreground app identity. Raw trees, screenshots
+UI; readiness waits fail with `DEBUGGER_PAUSED`. This signal covers managed Android and iOS simulator
+sessions and does not establish foreground app identity. Raw trees, screenshots
 and logs remain available within their own timeouts; snapshot/log acquisition may
 still fail while the app is suspended. Known pauses are annotated on observations.
 
@@ -134,7 +134,7 @@ step, resume or attach.
 ## Limits, privacy and evidence
 
 There is no expression evaluation, object traversal, method invocation, mutation,
-coroutine reconstruction, native debugger, iOS debugger or heap capture. Kotlin
+coroutine reconstruction, native-specific inspection or heap capture. The optional iOS simulator backend is described below. Kotlin
 results follow emitted bytecode/debug metadata; optimized/obfuscated apps may lack
 useful source lines or locals. Locals may contain private data: values are returned
 only on request, without protocol/value logging, persistent dumps or upload.
@@ -178,3 +178,43 @@ is selected. Fixture compilation requires SDK platform/build-tools 36 and `javac
 - [App management](manage.md): build, install, and launch the app before attaching.
 - [App readiness](observe.md#app-readiness): understand known debugger-pause evidence.
 - [Android system traces](system-traces.md): investigate performance without paused-state inspection.
+
+## iOS simulator backend
+
+The same eleven tools accept `platform: "ios"` for target capability probes and
+attach. Supply an explicit booted simulator UDID and bundle `appId`; an optional
+`processId` must belong to that simulator's installed app. Requires macOS and full
+Xcode with its Swift-enabled LLDB and Python bindings. Physical iOS devices remain
+unsupported. Attach never launches an app, chooses a host process by name alone,
+replaces another debugger, or changes security settings.
+
+For `set_debugger_breakpoint`, supply `sourceFile` (absolute local source path)
+and 1-based `line` for iOS; continue using binary `className` for Android. Exactly
+one selector is required. iOS reports `resolved`, `pending` or `rejected` with
+actual locations; LLDB line relocation is disabled. Pending breakpoints may bind
+when their image loads. Other tool arguments, stop-scoped references, stack/locals
+limits, event cursors, response modes and expiry durations follow the flow above.
+
+iOS returns backend-specific capabilities and limitations; `target.uid` may be
+null and `target.executable_path` identifies the verified simulator executable.
+`async_execution_inspection` and `async_stepping` are independent capability flags.
+False means the capability is not established for the backend's supported matrix;
+inspect the limitations. A source breakpoint after await and a shallow local do
+not enumerate suspended tasks or establish logical task identity. Step requests
+acknowledge delivery; inspect the subsequent actual stop. Object locals expose
+only bounded type/opaque identity; Swift standard numeric/bool wrappers are read
+from static storage; Swift strings and other aggregates retain type summaries. No expressions, descriptions, dynamic getters or arbitrary
+LLDB commands execute through this API.
+
+Known iOS pauses guard lifecycle actions, input, waits and assertions on that
+platform/device and supply `debugger_paused` readiness. Raw observations remain
+available within their own deadlines. Detach removes owned breakpoints and worker
+resources and releases owned suspension; it never kills the app or simulator.
+A worker exit without confirmed detach/process exit cannot prove cleanup; retry
+`detach_debugger` and inspect `cleanup.remaining_resources`. Failure diagnostics
+provide static Xcode/LLDB-specific recovery guidance without raw worker text.
+
+Use the [isolated simulator fixture](../../test/fixtures/ios-debugger-app/README.md)
+for real MCP runtime and async checks. The [implementation plan](../specs/032-ios-runtime-debugger/plan.md)
+records exact verification and unavailable coverage. An installed/published package,
+physical device, or other Xcode version requires separate evidence.

package/docs/tools/interact.md

@@ -78,11 +78,11 @@ Reasons are `BASELINE_UNAVAILABLE`, `SESSION_MISMATCH`, `DEVICE_MISMATCH`,
 there is no valid fresh observation. Error trees cannot authorise input merely
 because they contain an old revision.
 
-Debug responses retain the full condition tree. Compact responses retain full
-fresh evidence on mismatch/unavailable results; this is an exception to their
-usual omission of device identifiers and tree contents. Successful compact
-conditions contain only observed session/revision and capture time. UI trees may
-contain private text; avoid copying them into logs unnecessarily.
+Debug responses retain the full condition tree. Compact responses retain condition
+status/reason and observed session/revision/capture time when they fit the budget.
+Use the returned diagnostics reference with `get_interaction_diagnostics` to read
+the retained original condition tree without replaying input. UI trees may contain
+private text; compact mode is not redaction. See [compact results](compact-interactions.md).
 
 The baseline must still be in this process's same-device history: up to eight
 revisions, retained for ten minutes since a successful observation of that
@@ -714,7 +714,10 @@ and `responseMode` (`compact`, `debug`). Omitted controls retain `full`/`debug`.
 `none` reports dispatch without post-action accessibility reads. `light` requests
 one fresh tree; an unavailable observation does not turn successful delivery into
 a failed action. Use an explicit assertion to establish the intended outcome.
-Compact responses retain delivery, retry, lifecycle, and timing fields.
+Compact responses retain delivery, retry, lifecycle and verification fields, with
+bounded observation summaries and a read-only diagnostics reference. Optional
+timing/summaries may be omitted with `truncated:true` to fit the output budget.
+See [compact results](compact-interactions.md) for bounds and migration.
 
 `actionTimeoutMs` and `verificationTimeoutMs` are integer budgets, clamped to
 100–30,000 and 100–60,000 ms respectively. An action timeout after dispatch starts
@@ -789,5 +792,11 @@ for supported states and limits.
 
 ## Correlated evidence
 
-Actions and journeys expose identifiers and phase timestamps for linking later
-observations. See [evidence correlation](correlated-evidence.md) for scope and limitations.
+Actions and journeys expose identifiers for linking later observations. Debug
+results and retained diagnostics include phase timestamps. See [evidence correlation](correlated-evidence.md) for scope and limitations.
+
+Interaction action responses preserve `device_readiness` in compact/debug modes
+and journey action steps, including when verification is disabled. This evidence
+adds no input guard or automatic retry. Readiness-enabled waits reject known
+device blockers; ordinary predicate waits keep their existing semantics.
+See [device readiness evidence](observe.md#device-readiness-evidence).

package/docs/tools/manage.md

@@ -23,16 +23,18 @@ Enumerate connected Android devices and iOS simulators.
 Input (optional):
 
 ```json
-{ "platform": "android" }
+{ "platform": "android", "appId": "com.example.app" }
 ```
 
 Response:
 
 ```json
-{ "devices": [ { "id": "emulator-5554", "platform": "android", "osVersion": "11", "model": "sdk_gphone64_arm64", "simulator": true, "appInstalled": false } ] }
+{ "devices": [ { "id": "emulator-5554", "platform": "android", "osVersion": "11", "model": "sdk_gphone64_arm64", "simulator": true, "appInstalled": false, "appInstallation": { "status": "absent", "appId": "com.example.app", "deviceId": "emulator-5554", "scope": "android-current-user", "checkedAt": "2026-11-05T20:00:00.000Z" } } ] }
 ```
 
 Notes:
+- Supply `appId` for an installation check. `appInstallation.status` is `installed`, `absent`, or `unknown`; unknown includes a reason and omits legacy `appInstalled`. Missing app context never means absent.
+- Checks identify device/app, scope, and completion time (`checkedAt: null` when no check ran). Android checks cover the current user; iOS covers booted simulators. Unavailable devices and failed checks remain unknown. Installation does not establish running or ready state.
 - When multiple devices are attached, pass `deviceId` to other tools to target a specific device.
 
 ---
@@ -137,3 +139,9 @@ Notes:
 `appId`, with optional `deviceId`. Resetting app data removes application state;
 use it only when a clean app state is intended. Execution controls apply to
 `start_app` and `restart_app`; see [verification modes](interact.md#interaction-execution-controls-rfc-018).
+
+Launch/restart action responses include `device_readiness` in compact and debug
+modes, even when verification is disabled. `success` retains dispatch semantics;
+a sleeping/locked observation does not erase successful dispatch or prove that
+the target app is visible. Device-probe failure is reported as unknown without
+changing the dispatch result. See [device readiness evidence](observe.md#device-readiness-evidence).

package/docs/tools/observe.md

@@ -146,6 +146,8 @@ Input:
 
 Behavior:
 - Captures screenshot (base64), current activity (Android), screen fingerprint, full UI tree, and recent logs.
+- On Android, the fingerprint uses the fresh tree returned in the same snapshot.
+  A failed tree acquisition makes both components unavailable.
 - Prefers active log stream entries (read_log_stream) and falls back to get_logs when no active stream is available.
 - Returns partial data when components fail and includes per-part error fields (e.g. `screenshot_error`, `ui_tree_error`).
 - Caps logs to `logLines` entries and prefers recent entries.
@@ -290,8 +292,9 @@ latest successful capture time and snapshot session/revision, sample
 count, `stable_for_ms`, up to eight signal-code evidence records, limitations,
 and capability flags. Evidence excludes UI text and full trees. Managed Android
 [debugger pauses](debugger.md) are reported from session evidence without acquiring
-a UI tree; readiness waits fail with `DEBUGGER_PAUSED`. External-debugger and iOS
-pause detection remain unsupported. Unresponsive detection is unsupported; neither
+a UI tree; readiness waits fail with `DEBUGGER_PAUSED`. Supported managed iOS
+simulator debugger sessions also report pauses. External-debugger pause
+detection remains unsupported. Unresponsive detection is unsupported; neither
 slow hierarchy retrieval nor a deadline expiry proves a pause or unresponsiveness.
 
 Tree responses (including compact and nested trees) add a single-sample readiness
@@ -312,3 +315,40 @@ reads remain bounded by their operation deadlines.
 
 See [readiness-aware waits](interact.md#readiness-aware-waits) to combine this
 signal with a specific UI predicate.
+
+### Device readiness evidence
+
+`get_app_readiness`, `wait_for_app_ready`, readiness-enabled UI waits and shared
+interaction action results include a separate `device_readiness` object:
+
+- `wakefulness`: awake, asleep, transitioning, unknown or unsupported.
+- `lock_state`: locked, unlocked, unknown or unsupported.
+- `blockers`: DEVICE_ASLEEP, DEVICE_LOCKED, DEVICE_TRANSITIONING or DEBUGGER_PAUSED.
+- `input_ready`: false for an observed blocker; otherwise null (not established).
+- `evidence`: bounded signal codes, sources and host epoch `captured_at_ms` values.
+- `limitations`: explicit unavailable/unverified signal codes.
+
+Android reads explicitly targeted power/keyguard flags; missing or contradictory
+flags yield unknown. Known device blockers prevent readiness-wait success even
+when a lock-screen tree is stable. Waits allow natural recovery within the same
+budget; expiry retains READINESS_TIMEOUT and the last device observation.
+Within one wait, an inconclusive device probe retains any last-known blocker
+for that axis, including its original evidence timestamp and the new probe-failure
+limitation. `DEVICE_BLOCKER_EVIDENCE_RETAINED` distinguishes that historical
+evidence; only a fresh conclusive state clears the corresponding blocker.
+Unknown/unsupported signals without an earlier blocker retain existing
+UI-stability semantics and cannot prove input readiness. Managed debugger pause
+keeps its existing guard priority.
+
+On iOS, the CoreDevice lock query reports unsupported only for an explicit
+matching capability rejection; other failures yield unknown. Successful lock
+response semantics remain unverified. The tested iOS 26.4 simulator rejected
+lock-state queries, and wakefulness remains unknown: display/backlight output
+was not a reliable sleep signal. Physical iOS support was not established.
+
+No probe wakes, unlocks or changes security settings. Probe timeouts are at most
+1,000 ms each, clipped to the existing operation budget, with no retries or
+cross-call cache. Device evidence describes capture time, not an atomic promise
+about later input. Known blockers are checked before readiness UI acquisition.
+Tree-only observations retain their existing single-sample UI summary and do
+not perform these additional device probes.