mobile-debug-mcp 0.32.4 → 0.34.0

package/docs/specs/020-conditional-actions/spec.md

@@ -0,0 +1,301 @@
+# Spec 020: conditional actions
+
+Date: 2026-10-29.
+Status: approved — implementation authorised.
+Intent: [intent.md](intent.md), approved in the current conversation by the
+originator's “yes” in response to the captured intent.
+
+## Outcome
+
+A client can request a supported UI action only if the observed UI snapshot still
+matches its expectation. The server obtains a new hierarchy immediately before
+native input dispatch. A mismatch prevents input and returns the fresh hierarchy
+so the client can decide what to do next.
+
+This is a precondition check, not a guarantee that the UI remains unchanged until
+the OS delivers the input or that the action achieves its intended outcome.
+
+## Current code and observations
+
+- `src/server/tool-handlers.ts` wraps action controls, delivery status, response
+  modes, and journeys. Existing assertions are separate from native input.
+- `ToolsInteract.tapElementHandler` revalidates a handle but does not compare a
+  client-provided expected snapshot. Selector resolution can also precede input.
+- `src/observe/snapshot-metadata.ts` computes a signature from the full element
+  list, screen, and resolution, and assigns revisions per resolved device.
+  Revisions remain stable for consecutive identical signatures. State, bounds,
+  identities, and actionability contribute; screen fingerprints omit some of
+  these and are unsuitable as the only condition.
+- Revisions are process-local integers. Revision numbers alone cannot safely
+  distinguish server restarts. Error trees may carry a previous revision, so a
+  revision on an error response is not proof of a successful observation.
+- Android and iOS input adapters mark dispatch immediately before spawning input.
+  The new guard must run there, after metadata/capability checks and resolution,
+  rather than only at entry to the MCP handler.
+
+### Device reconnaissance (existing behaviour, not feature verification)
+
+Read-only `list_devices` and `get_ui_tree` calls through the connected mobile-debug
+MCP succeeded on 2026-10-29:
+
+| Platform | Device | Observed state | Evidence |
+| --- | --- | --- | --- |
+| Android 16 | `emulator-5554`, sdk_gphone64_arm64 | Modul8 Subscription screen | 18 elements, revision 1, 1280 × 2856, tree call about 4.1 seconds |
+| iOS 26.4 | `F72108FF-C8D6-4C1E-980E-1AE5E5CCD27B`, iPhone Air simulator | Home screen | 14 elements, revision 2, 420 × 912, tree call about 8.4 seconds |
+
+These are observations from the connected server; its exact build was not exposed
+by these calls. The local checkout declares version 0.32.4. No inputs, installs,
+or settings changes were made. Verification must use a build from the changed
+checkout; these reads do not establish conditional-action behaviour.
+
+## Initial scope
+
+| Tool | Platforms | Condition support |
+| --- | --- | --- |
+| `tap` | Android, iOS | Optional expected snapshot |
+| `tap_element` (selector or handle) | Android, iOS | Optional expected snapshot |
+| `swipe` | Android, iOS | Optional expected snapshot |
+| `type_text` | Android | Optional expected snapshot |
+| `press_back` | Android | Optional expected snapshot |
+| `run_journey` | Android, iOS | Optional condition on each `tap` step |
+
+No platform gains an input capability it does not already support.
+
+Out of scope: lifecycle/build/install/reset tools, `scroll_to_element`,
+`adjust_control`, other multi-input operations, arbitrary predicate expressions,
+per-element-only conditions, automatic retries/replanning, rollback, screenshot
+comparison, and changing post-action verification semantics.
+
+A supplied `expectedState` on any unsupported tool or journey step is rejected
+as `INVALID_ARGUMENT` before any operation. It must never be silently ignored.
+Conditions cannot be journey defaults or a condition on the journey as a whole.
+
+## Input contract
+
+Add this optional field to each supported tool and journey `tap` step:
+
+```ts
+expectedState?: {
+  snapshotSessionId: string;
+  snapshotRevision: number;
+  timeoutMs?: number; // default 15000; integer, 100–60000 ms
+}
+```
+
+The object is strict. The session ID is nonempty; revision is a positive safe
+integer. Invalid types, null, missing required members, extra members, and
+out-of-range values return `INVALID_ARGUMENT` before observation or input.
+Validate both the advertised JSON schema and actual runtime arguments.
+
+Guarded standalone calls require explicit `platform` and concrete `deviceId`.
+The ID must identify the same resolved device as the baseline; aliases such as
+`booted` and `default` are not valid guarded targets. Journey taps inherit the
+journey's once-resolved concrete platform/device. Unguarded calls retain their
+existing device selection and argument behaviour.
+
+### Obtaining an expectation
+
+Successful UI-tree observations add `snapshot_session_id`, a random ID generated
+once per server process. Keep existing revision and timestamp fields intact.
+Carry the session ID through debug and compact `get_ui_tree` responses and nested
+UI-tree evidence. This field does not imply that an error response is usable.
+
+The client takes `snapshot_session_id` and `snapshot_revision` from a successful
+`get_ui_tree` on the same device and supplies them as the expectation:
+
+```json
+{
+  "platform": "android",
+  "deviceId": "emulator-5554",
+  "x": 100,
+  "y": 200,
+  "expectedState": {
+    "snapshotSessionId": "<session from get_ui_tree>",
+    "snapshotRevision": 12
+  },
+  "responseMode": "compact",
+  "verificationMode": "none"
+}
+```
+
+Require a retained successful baseline for this session, device, and revision.
+Reuse the existing bounded snapshot history (up to eight revisions, ten-minute
+retention); no new unbounded history. Expired, evicted, other-device, or
+previous-session baselines cannot authorise input. Clients must observe again.
+Check baseline availability before the fresh read and retain its identity for
+that check, so the fresh read itself cannot evict the baseline being checked.
+
+## Meaning of expected state
+
+Match means the fresh successful observation's revision equals the retained
+expected revision within the same server session and device. Use the existing
+snapshot signature and revision rules; do not substitute screen fingerprints,
+partial delta history, or target identity alone.
+
+This checks the normalized accessibility snapshot, not every app or OS state.
+The signature includes all elements even though retained delta records are
+bounded. Existing normalization trims/lowercases string fields, includes state
+and bounds, and does not prove the foreground package/activity (current tree
+`screen` is empty on both adapters). Pixel-only changes, inaccessible controls,
+backend state, and changes hidden by normalization are outside the guarantee.
+An intervening observed change followed by a return to the old screen produces
+a different revision and is conservatively rejected. An unobserved transient
+change cannot be detected. Document these limits in tool usage guidance.
+
+## Dispatch rules
+
+1. Validate the entire condition, supported tool/step, and guarded targeting
+   before starting the operation. Resolve and pin the concrete device once.
+2. Resolve the requested target and perform existing actionability/capability
+   checks. Existing target failures still prevent input normally; an unperformed
+   input does not imply its condition was checked.
+3. Immediately before the input subprocess would spawn, validate the retained
+   baseline and obtain a new, uncached UI hierarchy on the pinned device. Do not
+   use a selector-resolution tree, previous assertion, compact delta, or an
+   earlier pre-action fingerprint as the final check.
+4. Reject error/malformed trees, missing revision/session metadata, or a response
+   identifying another device. An old revision on an error tree never passes.
+5. Compare the expectation once. No polling until it becomes true, automatic
+   rebasing, or retry of input. Existing internal acquisition retries remain
+   bounded by the condition timeout; they do not authorise a stale read.
+6. On match, record the successful condition result, check the remaining action
+   budget, mark dispatch, and spawn native input. No further observation,
+   target resolution, metadata lookup, intentional delay, or asynchronous
+   capability probe may occur between the final check and input spawn.
+7. On failure, preserve the structured condition result across adapter catches.
+   Do not mark dispatch or reset the network action window. Skip post-input
+   verification and recovery, and return immediately.
+
+The condition observation has its own `timeoutMs` budget. Its elapsed time does
+not consume the existing action-dispatch budget; target resolution and input
+retain existing action controls. Check a nested budget's outer deadline too
+where applicable. An expired condition read cannot permit later background input.
+Condition checking is mandatory even with `verificationMode: "none"` or `"light"`.
+
+The guard must be scoped to the request using existing async-context conventions;
+it must not leak into another call or recursively guard its own observation.
+There is no cross-client transaction or device lock in this initial version.
+Concurrent actions, external input, and app updates may still change the UI
+after observation; clients should sequence actions on a device. Do not claim
+atomicity, exclusivity, or rollback.
+
+## Response contract
+
+Preserve existing action fields. Guarded calls add:
+
+```ts
+condition: {
+  status: 'matched' | 'mismatch' | 'unavailable' | 'not_checked';
+  expected: { snapshot_session_id: string; snapshot_revision: number };
+  observed: GetUITreeResponse | null;
+  elapsed_ms: number;
+  reason?: string;
+}
+```
+
+Stable `reason` values for unavailable checks: `BASELINE_UNAVAILABLE`,
+`SESSION_MISMATCH`, `DEVICE_MISMATCH`, `OBSERVATION_FAILED`,
+`OBSERVATION_INVALID`, and `CONDITION_TIMEOUT`. `not_checked` uses
+`ACTION_NOT_REACHED` when target/capability failure precedes the guard.
+`elapsed_ms` measures the condition check, or zero if it was not reached.
+
+| Outcome | Action result | Delivery fields | Condition evidence |
+| --- | --- | --- | --- |
+| Match, then input | Existing action outcome | Existing delivery semantics | `matched`, fresh observed tree |
+| State differs | `success: false`, `failure_code: PRECONDITION_FAILED`, `retryable: false` | `dispatch_started: false`, `delivery_status: not_delivered`, `lifecycle_state: failed` | `mismatch`, exact fresh observed tree |
+| Check cannot be completed | `success: false`, `failure_code: PRECONDITION_UNAVAILABLE`, `retryable: false` | Same non-delivery fields | `unavailable`, reason; valid fresh tree if available, otherwise null |
+| Target/capability failure before check | Existing failure code | No input dispatch | `not_checked`, observed null |
+
+For blocked input, `verification.status` is `not_requested`; this is a failed
+precondition, not a failed post-action assertion. If input fails after a match,
+retain `matched` alongside the actual input failure; a matching condition is not
+proof of delivery or outcome correctness. Add failure codes to shared types and
+recovery handling without enabling automatic retry.
+
+Debug mode includes full condition evidence. Compact mode always keeps condition
+status, expected values, elapsed time, and reason. On mismatch/unavailable it also
+keeps `observed`, including the full tree when available: this is a documented
+exception to compact mode's usual omission of device IDs and tree contents.
+On match, compact mode keeps only observed snapshot session/revision and capture
+time instead of the full tree. `not_checked` keeps observed null.
+
+The returned mismatch tree is the actual observation that blocked input; do not
+replace it with a later snapshot. No automatic screenshot or log capture is
+required. Apply existing response-data handling; UI trees can contain private
+text. Do not log expectation payloads, input text, or full trees by default.
+
+## Journey behaviour
+
+A conditional tap uses the same guard as a standalone `tap_element`. Conditions
+are evaluated at that step's dispatch boundary, after any earlier waits/asserts.
+A mismatch or unavailable condition fails that step and sets
+`stopped_at_step_id`; subsequent steps are `not_run`. Earlier completed steps
+remain completed. Preserve condition evidence in both journey response modes,
+regardless of `captureOnFailure`. Existing optional debug failure snapshots must
+not overwrite the guard evidence. There is no rollback or implicit baseline
+refresh from an earlier step.
+
+## Acceptance criteria
+
+1. Matching expectations dispatch exactly once on every supported tool/platform;
+   existing post-action controls still apply.
+2. A changed text, bounds, enabled flag, or exposed element state blocks input
+   even when the target still exists; return the blocking observation.
+3. Detect a change after selector resolution and during adapter preparation by
+   checking at the final dispatch boundary, not only at handler entry.
+4. Old sessions, expired/evicted baselines, another-device baselines, failed
+   observations, malformed metadata, and condition timeout never dispatch input.
+5. Conditions are enforced in none/light/full verification and compact/debug
+   response modes; mismatch evidence survives compact serialization.
+6. A failed journey condition stops subsequent steps and preserves earlier results.
+7. Unsupported/malformed conditions fail validation before side effects.
+8. Unguarded calls preserve existing contracts and behaviour.
+9. Concurrent requests do not share guard state; blocked input neither resets
+   the network window nor triggers retry/recovery. No late dispatch after timeout.
+10. Documentation explains snapshot normalization, history/session limits,
+    additional observation latency, data exposure in mismatch responses, and the
+    observation-to-input race.
+
+## Affected surfaces and verification expectations
+
+Implementation is expected in tool definitions and runtime validation, action
+wrapping/serialization and journey schema, snapshot metadata/history and types,
+and the Android/iOS native input boundaries. Reuse existing async contexts,
+budgets, and device resolution. Keep platform subprocess logic in its adapters.
+Update interaction/observation docs, README usage, changelog, and packaged agent
+skill guidance if it describes the new workflow; use the existing plugin sync
+command when changing its source.
+
+Use the repository's self-running `tsx` unit tests to prove dispatch prevention,
+freshness ordering, error propagation, exact evidence, isolation, timeout, and
+schema parity. Exercise real adapter paths with controlled subprocess fixtures;
+a test that mocks away the guard boundary is insufficient.
+
+Run `npm run verify` and `npm run test:device` after implementation, plus focused
+Android and iOS simulator journeys using the newly built server. Use an isolated
+test app or safe system controls, avoiding changes to the currently open Modul8
+subscription flow. Verify an unchanged-state action, deliberate intervening
+state change with non-delivery, and journey stop. Use controlled failures for
+unavailable/timeout and race ordering; report simulated and device evidence
+separately. Record exact test routes and cleanup in the implementation plan.
+
+## Risks and decisions
+
+- Whole-tree changes may conservatively block an action due to unrelated dynamic
+  UI; this initial version favours explicit rejection. Per-element predicates
+  can be specified later if needed.
+- Hierarchy acquisition adds seconds to guarded input; the separate condition
+  budget is intentional and must not silently weaken freshness.
+- Returning a fresh hierarchy in compact failures increases payload size and
+  exposes the same UI text as `get_ui_tree`; callers must handle it accordingly.
+- Session metadata is an additive contract change. Older servers cannot accept
+  guarded calls; clients must obtain expectations from this supporting server.
+  Local tests are not proof of an installed or published version's behaviour.
+- No data migration, new dependency, helper APK, external service, or automatic
+  release is required. Package publication remains a separate authorised action.
+
+## Approval
+
+Approved by the originator on 2026-10-29 in the current conversation: “yes”,
+in direct response to the linked complete spec and the listed first-version
+scope. Implementation is authorised within that scope.

package/docs/specs/021-app-readiness-signals/intent.md

@@ -0,0 +1,40 @@
+# Intent: app readiness signals
+
+Originator: repository maintainer (current conversation).
+Date: 2026-10-29. Status: approved.
+Source: [GitHub issue #65: App readiness signals](https://github.com/clivejefferies/mobile-debug-tools/issues/65), roadmap priority 2 of 9.
+
+## Problem
+
+Clients can mistake an observation captured during loading or a transition for
+settled app content. They also need to distinguish an unresponsive app from an
+app paused by a debugger, where evidence permits.
+
+## Desired outcome
+
+Android/iOS observations and bounded waits expose evidence-backed readiness:
+loading, transitioning, settled, unresponsive, and debugger-paused. Results carry
+the supporting observations and uncertainty so clients can decide whether to act,
+wait, or investigate. A screenshot alone does not establish readiness.
+
+## Scope and success criteria
+
+- Build on existing observation, loading-state, snapshot, and wait contracts.
+- Distinguish readiness states only when available evidence supports them;
+  otherwise report uncertainty rather than guess.
+- Bound waits and distinguish timeout/observation failure from proven app
+  unresponsiveness.
+- Coordinate with debugger sessions when available; do not invent a current
+  debugger integration.
+- Preserve existing tool behaviour unless the approved spec explicitly changes it.
+
+## Exclusions and questions
+
+No runtime debugger implementation, automatic recovery/restart, or performance
+profiling. The spec must define state evidence, sampling/stability rules,
+unsupported signals, API placement, and how long observations remain current.
+
+## Approval
+
+Approved on 2026-10-29 by the originator’s “yes” in direct response to the
+complete intent summary and linked artifact in this conversation.

package/docs/specs/021-app-readiness-signals/plan.md

@@ -0,0 +1,102 @@
+# Plan: app readiness signals
+
+Date: 2026-10-29. Status: complete — implementation and required verification passed.
+[Intent](intent.md) and [spec](spec.md) separately approved in this conversation;
+“yep” authorises implementation of spec 021. Preserve existing uncommitted work.
+
+## Implementation
+
+- [x] Add a request-local classifier and typed, bounded evidence summaries in
+  `src/observe/readiness.ts` and shared types.
+- [x] Add summaries to tree observations without extra reads; expose strict new
+  tool schemas/handlers using pinned devices and existing operation budgets.
+- [x] Add opt-in readiness to existing UI/changed-UI waits, sharing their samples
+  and one deadline; retain default semantics.
+- [x] Add deterministic classifier, schema, wait, native acquisition/error/timeout
+  tests in `test/unit/`; reuse existing self-running `tsx` conventions.
+- [x] Update tool docs, README/changelog, and packaged agent usage guidance.
+- [x] Verify, review the changed contracts, and record results below.
+
+## Verification
+
+| Criteria | Checks |
+| --- | --- |
+| State precedence and uncertainty | Explicit expected classifier outputs with controlled monotonic times; native/label loaders, changes, stable UI, empty/error/old-session/wrong-device samples |
+| Bounded sampling and isolation | Production observation adapters with fake binaries, timeout/child-close evidence, outer budget, concurrent requests, no late success |
+| Schemas and compatibility | SDK JSON-schema validation against runtime validation; compact/debug tree responses; default and opt-in waits; no extra reads |
+| Real device behaviour | Updated server over MCP stdio on Android emulator and iOS simulator: stable UI, controlled loader → settled, bounded loading timeout, predicate present during loader, and changed-UI wait |
+
+Commands: focused tests with the existing `tsx` runtime, `npm run verify`,
+`npm run test:device`, and a reproducible focused device helper under
+`test/device/manual/`. Native fixture apps provide a timed loader without
+accounts, network services, settings changes, or inspection helper services.
+Use the existing Android fixture build conventions and installed iOS SDK tools.
+Known targets: Android `emulator-5554`; iOS
+`F9243BAF-62A8-4990-8A99-17F527F56FDA` (reconfirm availability).
+Fixture builds/access are local prerequisites owned by this task. Record exact
+routes, artifacts, build identity and cleanup; restore original foreground apps.
+Unsupported unresponsive/debugger pause signals must remain explicit, not tested
+as implemented capabilities. No deployment or package publication is required.
+
+## Results and review
+
+Local build/version: working-tree `dist/server.js`, MCP handshake 0.32.4,
+Node v23.11.0. This is local evidence, not a published package or Node 18 CI run.
+
+| Check | Result / evidence |
+| --- | --- |
+| Classifier, schemas, opt-in waits | PASS: state precedence, monotonic stability, invalid/error continuity, no extra predicate reads, explicit unsupported states, timeout uncertainty |
+| Production Android/iOS observation adapters with fake binaries | PASS: two-sample stability, native loaders, timeout child closure, and killing a hung iOS metadata probe; simulated error evidence |
+| Maintainer checks | PASS: final `npm run verify` (lint, build, 62 unit-test files, plugin consistency); `/tmp/mobile-readiness-verify-complete.log` |
+| Existing `npm run test:device` | PASS: all six Android/iOS screenshot, log, and tree smoke wrappers; `/tmp/mobile-readiness-device-suite.log` |
+| Native fixture journeys through built MCP stdio | PASS: six on each simulator; evidence linked below |
+
+Focused device commands (each builds, installs, and uninstalls its own offline
+native fixture; temporary artifacts are removed):
+
+```sh
+node --import tsx test/device/manual/interact/readiness.manual.ts \
+  --platform android --id emulator-5554 --output /tmp/mobile-readiness-android.json
+node --import tsx test/device/manual/interact/readiness.manual.ts \
+  --platform ios --id F9243BAF-62A8-4990-8A99-17F527F56FDA \
+  --output /tmp/mobile-readiness-ios.json
+```
+
+Android 16 sdk_gphone64_arm64 and iOS 26.4 iPhone 17 Pro were explicitly pinned.
+Starting state: newly launched fixture, Ready visible, loader hidden. Show loader
+starts a 12-second loader while Ready stays visible; completion displays Done.
+
+| Scenario | Android | iOS | Observed proof |
+| --- | --- | --- | --- |
+| Stable content | PASS | PASS | Two fresh samples report settled |
+| Controlled loader | PASS | PASS | Loading; Android native indicator, iOS accessible label marked heuristic |
+| Bounded wait | PASS | PASS | 100 ms deadline rejects readiness; unknown plus deadline limitation, no invented unresponsive state |
+| Predicate + readiness | PASS | PASS | Ready remains visible during loading; success only after settled, Done independently observed |
+| Changed-UI wait | PASS | PASS | Loader completion changes hierarchy; opt-in wait returns success with settled evidence |
+| Readiness wait success | PASS | PASS | Bounded wait establishes settled content |
+
+All twelve device scenarios passed. Both fixture apps were uninstalled, build
+folders removed, Android’s original foreground app restored, and iOS returned
+to Home. No settings, permissions, accounts, or production app data were changed.
+Structured evidence: `/tmp/mobile-readiness-android.json` and
+`/tmp/mobile-readiness-ios.json`.
+
+Review covered classification/normalization, schema parity, serialization,
+request-local state, ancestor budgets, native acquisition and cleanup, existing
+wait callers, conditional-action compatibility, and evidence privacy. Findings
+fixed: discovery budget expiry must not look like a proven missing device;
+iOS probes/metadata must respect the active budget; timeout envelopes must retain
+an already-observed predicate instead of pretending its target was absent.
+The Android helper uses the stable accessibility ID, avoiding button-case
+variation. Initial fixture attempts exposed these issues and were not counted
+as passes; the later runs above passed without weakening assertions.
+
+Limits: unresponsive/debugger-paused detection remains unsupported. Stability
+covers normalized sampled UI, not app identity, responsiveness, backend outcome,
+or atomic input readiness. Transport cancellation still relies on deadlines.
+No mutation testing or physical-device input checks were performed. The prior
+conditional work was committed externally during this task and was preserved;
+this task did not commit, push, or publish readiness changes.
+
+Final source/diagnostic correction was covered by the completion verification run.
+Documentation relative links and `git diff --check` also passed.

package/docs/specs/021-app-readiness-signals/spec.md

@@ -0,0 +1,144 @@
+# Spec 021: app readiness signals
+
+Date: 2026-10-29. Status: approved — implementation authorised.
+Source: [issue #65](https://github.com/clivejefferies/mobile-debug-tools/issues/65).
+[Intent](intent.md) approved by the originator’s “yes” in this conversation.
+
+## Behaviour and scope
+
+Report readiness of the observed foreground device UI on Android/iOS. This is
+not proof of a particular app’s identity, backend completion, or safe input.
+Reuse snapshot signatures, loading observations, device resolution, and budgets.
+Do not infer readiness from screenshots or input-dispatch success.
+
+Initial supported states are `loading`, `transitioning`, `settled`, and `unknown`.
+Reserve `unresponsive` and `debugger_paused`, but report their capabilities as
+unsupported on both platforms: there is currently no authoritative process-health
+or debugger-session provider. A timeout must never manufacture either state.
+Adding those providers requires a subsequent spec decision; this feature does
+not implement a debugger, recovery, restart, or performance profiling.
+
+## Public contracts
+
+Add tools `get_app_readiness` and `wait_for_app_ready`, requiring `platform`
+(`android`/`ios`) and optionally accepting `deviceId`. Resolve and pin one concrete
+device per call. Both accept strict integer controls:
+
+| Control | Default | Range |
+| --- | --- | --- |
+| `timeoutMs` | get: 15000; wait: 30000 | 100–60000 |
+| `stabilityMs` | 500 | 100–10000 |
+| `pollIntervalMs` (wait only) | 500 | 100–1000 |
+
+Reject invalid/unknown arguments as `INVALID_ARGUMENT` before device work.
+`get_app_readiness` takes at most two fresh samples, separating their acquisitions
+by at least `stabilityMs`. A loading first sample can return immediately. The
+wait tool samples until settled or its deadline. Reads are sequential; never
+start a background poller or overlap hierarchy dumps within a call.
+
+Both return `{ success, device, readiness, elapsed_ms, failure_code? }`.
+For get, success means a supported state was established; `unknown` is unsuccessful.
+For wait, only `settled` is successful. Unsuccessful codes are
+`READINESS_UNAVAILABLE` (get), `READINESS_TIMEOUT` (wait deadline), and
+`DEVICE_UNAVAILABLE` (resolution/disconnection prevents continuation).
+
+`readiness` contains:
+
+- `state`, `scope: device_ui`, and `basis` (`observed`, `heuristic`, or `insufficient`).
+- `captured_at_ms` (latest successful sample, or null), `sample_count`,
+  `stable_for_ms`, and nullable `snapshot_session_id`/`snapshot_revision`.
+- `evidence`: bounded records of signal code, source, capture time, and snapshot
+  revision; maximum eight, newest retained. No full text, logs, screenshots, or trees.
+- `limitations`: applicable codes from `INSUFFICIENT_SAMPLES`, `OBSERVATION_FAILED`,
+  `OBSERVATION_INVALID`, `DEADLINE_EXCEEDED`, `NORMALIZED_UI_ONLY`,
+  `FOREGROUND_APP_UNVERIFIED`, `UNRESPONSIVE_SIGNAL_UNSUPPORTED`, and
+  `DEBUGGER_SIGNAL_UNSUPPORTED`.
+- `capabilities`: true for loading/transition/stability observation; false for
+  unresponsive/debugger-paused detection in this version.
+
+Add the same `readiness` summary to debug/compact `get_ui_tree` and nested tree
+observations without additional reads. Single-sample summaries can only report
+loading or unknown; separate calls never silently share a stability window.
+Preserve existing fields, compact error evidence, and delta behaviour.
+
+Add opt-in `requireReady: boolean` (default false) to `wait_for_ui` and
+`wait_for_ui_change`. When enabled, success requires the existing predicate and
+settled readiness on the same current samples. Reuse those waits’ samples and
+single existing deadline; do not add another wait budget or unrelated tree reads.
+Return `readiness` alongside the existing envelope. On expiry retain the existing
+timeout/failure shape and include readiness limitations. Default calls retain
+existing predicate semantics; no new journey assertion type is introduced.
+
+## Classification rules
+
+| Evidence | State / basis |
+| --- | --- |
+| Visible native `android.widget.ProgressBar`, `ActivityIndicator`, or `ProgressIndicator` | loading / observed |
+| Visible label exactly “Loading” or “Please wait”, ignoring case, whitespace, and trailing full stops/ellipsis | loading / heuristic |
+| Two valid consecutive signatures differ | transitioning / observed |
+| At least two valid identical signatures spanning `stabilityMs`, without loading evidence | settled / observed |
+| Missing, failed, invalid, or insufficient evidence | unknown / insufficient |
+
+Loading takes precedence over stability. Do not reuse the broad existing
+`loading_state` keyword heuristic as proof: a button named “Progress” is not an
+active loader. Keep that legacy field unchanged for compatibility.
+
+Use full normalized snapshot signatures, including state and bounds, not the
+coarser screen fingerprint or truncated delta. A change resets stability;
+failed reads break consecutive-sample continuity. Validate device/session,
+revision, a finite capture timestamp from this acquisition, nonempty elements,
+and positive finite resolution. Never accept retained metadata as a fresh read.
+Track elapsed/stability intervals with a monotonic clock; expose wall-clock
+capture timestamps only as evidence. Results describe their capture window,
+not a guarantee that the UI stays settled afterward.
+
+## Failure, lifecycle, and privacy
+
+Bound acquisition, retries, and delays by the remaining operation budget and any
+outer deadline. No late sample may produce success. Terminate/await owned timed-out
+subprocesses; perform no follow-up snapshot after expiry. Waits can retry transient
+observation failures within budget, with continuity reset; disconnect is terminal.
+Retain the last supported state on wait timeout only as timestamped evidence,
+with `DEADLINE_EXCEEDED`; if the latest read failed, current state is unknown.
+There is no cancellation argument. Existing transport cancellation does not
+currently abort platform reads; those reads remain bounded by their deadlines.
+Do not claim immediate cancellation support or create persistent sessions.
+Do not reset network windows, dispatch input, or retain cross-request histories.
+Do not log UI payloads or input text. No permissions, dependencies, migrations,
+or automatic package release are required.
+
+## Acceptance and verification
+
+- Loading outranks identical trees; changing trees transition; consecutive stable
+  valid trees settle. Text-only loading is explicitly heuristic.
+- A frozen-looking screenshot, stable tree, slow dump, timeout, or missing loader
+  cannot establish responsiveness, debugger pause, or app/backend completion.
+- Error/empty/stale-session/wrong-device samples never settle; failures reset
+  continuity. Deadlines prevent late success and background work.
+- New summaries preserve compact/debug evidence and existing defaults; opt-in
+  waits require both their predicate and readiness.
+- Every state has evidence and limitations; unsupported capabilities are explicit.
+
+Use deterministic native-adapter/clock fixtures for transitions, failures,
+timeouts, isolation, and schema parity. Run `npm run verify`, `npm run test:device`,
+and updated-server Android/iOS journeys for stable content, a controlled loader
+transition, bounded waiting, and opt-in predicate waits. Record simulator/build,
+results, and unsupported coverage in the plan after approval.
+
+## Investigation and approval
+
+Existing owners: `src/observe/snapshot-metadata.ts`, `src/observe/index.ts`,
+`src/interact/index.ts`, server schemas/handlers, shared types and operation budgets.
+The legacy idle wait can compare null fingerprints; the new classifier must not
+copy that inference. No debugger/readiness module currently exists.
+
+Read-only reconnaissance used the connected server (exact build not reported;
+local checkout 0.32.4). Android 16 `emulator-5554`: two fresh 15-element trees,
+same revision 9, no loading hint, reads about 4.4/3.0 seconds. iOS 26.4 iPhone 17
+Pro `F9243BAF-62A8-4990-8A99-17F527F56FDA`: two fresh 14-element trees, revision
+10, no loading hint, reads about 3.4/2.0 seconds. These establish available
+observation routes, not feature passes; no inputs or settings were changed.
+
+Approved by the originator’s “yep” on 2026-10-29 in direct response to this
+spec and first-version scope, including unsupported unresponsive/debugger-paused
+detection and opt-in existing-wait integration.

package/docs/specs/022-correlated-evidence/device-evidence.json

@@ -0,0 +1,60 @@
+{
+  "verified_on": "2026-10-30",
+  "source_base": "3701f3987940a8abc76ed893b575ed370e3fb673",
+  "source_state": "working tree with correlated evidence changes",
+  "node_version": "23.11.0",
+  "build_sha256": {
+    "dist/server/tool-handlers.js": "4ae4aef2467518216e3b987112aadb91e5ff560679782fe08aefdb389209cc50",
+    "dist/observe/evidence.js": "bd7c6ac046ad4adde08117dcb66f68682e0036a83308c0c84f6d5ce141f8a386"
+  },
+  "journeys": [
+    {
+      "status": "PASS",
+      "server": {
+        "name": "mobile-debug-mcp",
+        "version": "0.32.4"
+      },
+      "platform": "android",
+      "device": "emulator-5554",
+      "osVersion": "16",
+      "startingApp": "com.android.settings",
+      "actionId": "5fdfe5a0-cfd3-4182-a12b-c440d855cec5",
+      "phases": {
+        "dispatchStarted": 1793350325789,
+        "dispatchCompleted": 1793350326584,
+        "screenshotStarted": 1793350327002,
+        "screenshotCompleted": 1793350327334
+      },
+      "screenshot": "captured",
+      "logs": "captured",
+      "uiTree": "captured",
+      "disabledComponents": "omitted",
+      "foreignReference": "unavailable",
+      "cleanup": "No settings, app data or streams changed; Settings remains foreground. No content artifacts saved."
+    },
+    {
+      "status": "PASS",
+      "server": {
+        "name": "mobile-debug-mcp",
+        "version": "0.32.4"
+      },
+      "platform": "ios",
+      "device": "F9243BAF-62A8-4990-8A99-17F527F56FDA",
+      "osVersion": "iOS 26.4",
+      "startingApp": "com.apple.Preferences",
+      "actionId": "99a4cdc4-8be1-4194-acab-3d08e7bd4a41",
+      "phases": {
+        "dispatchStarted": 1793350335131,
+        "dispatchCompleted": 1793350335486,
+        "screenshotStarted": 1793350335806,
+        "screenshotCompleted": 1793350336212
+      },
+      "screenshot": "captured",
+      "logs": "captured",
+      "uiTree": "captured",
+      "disabledComponents": "omitted",
+      "foreignReference": "unavailable",
+      "cleanup": "No settings, app data or streams changed; Settings remains foreground. No content artifacts saved."
+    }
+  ]
+}