mobile-debug-mcp 0.32.2 → 0.33.0

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

@@ -0,0 +1,214 @@
+# Plan: conditional actions
+
+Date: 2026-10-29. Status: complete — implementation and required verification passed.
+Intent: [intent.md](intent.md). Specification: [spec.md](spec.md).
+Both approved by the originator's separate “yes” replies in this conversation;
+the latest approval authorises implementation of spec 020.
+
+## Implementation sequence
+
+- [x] Inspect action wrapping, native input, observation/history, budgets, tests.
+- [x] Add session metadata and retained successful-baseline lookup without changing
+  existing revision semantics or growing history.
+- [x] Add strict condition schema, supported-tool validation, and journey tap wiring.
+- [x] Add a request-scoped asynchronous pre-dispatch guard, pin the device, and
+  isolate the observation budget from the action budget (respecting outer budgets).
+- [x] Integrate at Android/iOS input spawn boundaries; retain failure evidence
+  through adapter errors; defer guarded network-window reset until dispatch.
+- [x] Preserve condition evidence and non-delivery semantics in compact/debug
+  responses, including journey stop and not-checked cases.
+- [x] Add deterministic unit/adapter regression coverage and device journeys.
+- [x] Update public docs/changelog and packaged agent usage guidance; sync/check plugin.
+- [x] Run focused checks, maintainer verification, device suite, and focused device journeys.
+- [x] Review changed code/contracts/callers and record results and limits.
+
+## Expected affected files
+
+- `src/observe/snapshot-metadata.ts`, `src/observe/index.ts`, `src/types.ts`.
+- New shared condition schema/guard modules under `src/` as responsibility requires.
+- `src/utils/operation-budget.ts`, Android/iOS input adapters.
+- `src/server/tool-definitions.ts`, `tool-handlers.ts`, `journey-schema.ts`, `common.ts`.
+- Unit tests under `test/unit/server/`, `test/unit/observe/`, and adapter fixtures.
+- Focused reusable device helper under `test/device/manual/` if explicit simulator
+  selection/state setup makes it unsuitable for automatic generic suite execution.
+- `docs/tools/interact.md`, `observe.md`, `docs/CHANGELOG.md`, `README.md`, and
+  `agent-plugin/skills/mobile-debug-mcp/SKILL.md`.
+
+## Verification mapping
+
+| Spec criteria | Verification |
+| --- | --- |
+| 1, 5, 8 | Real Android/iOS adapter calls using fake binaries; all supported actions, verification modes and response modes; unguarded compatibility tests |
+| 2, 3 | Mutable hierarchy fixture changes text/bounds/enabled/state and changes during target resolution/adapter preparation; assert zero native input and exact final tree |
+| 4 | Session, history expiry/eviction, device mismatch, error/malformed observation, timeout including late completion and child cleanup |
+| 6 | Journey with earlier passed step, blocked conditional tap, later not-run step; both response modes |
+| 7 | Runtime invalid-input matrix and advertised schemas; unsupported tools/steps rejected before any side effects |
+| 9 | Overlapping guarded/unguarded calls and network-window reset spy; condition budget distinct from input budget; outer-budget expiry |
+| 10 | Documentation and focused review against actual implementation |
+
+Commands: focused test files via existing `tsx` runtime, then `npm run verify`,
+`npm run test:device`, and focused device helper against built `dist/` modules.
+Runtime: repository supports Node >=18; record actual Node/toolchain with results.
+No new dependency, migration, helper APK, publication, or service is needed.
+
+## Device routes and readiness
+
+Available during spec reconnaissance: Android 16 `emulator-5554` and booted iOS
+26.4 iPhone Air `F72108FF-C8D6-4C1E-980E-1AE5E5CCD27B`. The physical Pixel is
+excluded from mutation checks. Tool access and fresh trees work on both simulators.
+Before device runs, inspect current state and choose safe system controls; avoid
+interacting with the open Modul8 subscription flow. Use an already-installed
+system Settings app on Android/iOS where possible; no accounts or entitlements.
+
+For each platform on the newly built server:
+
+1. Open system Settings, observe its tree and session/revision, repeat to check a
+   stable baseline, then perform a guarded safe navigation tap and assert destination.
+2. Observe the baseline, navigate to another Settings screen, then send a guarded
+   action with the old expectation; assert non-delivery and returned current tree.
+   Confirm the blocked action has no effect using a fresh state assertion.
+3. Run a journey with an earlier successful wait/assert, an old-revision guarded
+   tap, and a later action. Confirm the tap fails, later step is not run, and state
+   stays unchanged. Repeat relevant compact/debug evidence checks.
+
+Exact selectors depend on the current simulator OS tree and will be recorded
+with results. Restore original foreground apps where practical; do not alter
+settings, app data, or subscriptions. Owner of local prerequisites: current task.
+Unavailable/timeout and last-moment preparation races use controlled fake binaries;
+no forced device disconnect or privileged settings change is needed. This is
+reported as simulated error-path evidence, separate from real-device passes.
+
+## Results
+
+Implementation is present. Node.js v23.11.0 was used locally (the supported
+minimum is >=18; CI's Node 18 run has not been executed locally).
+
+### Automated checks
+
+- Initial `npm run verify`: PASS, including lint, build, unit tests, plugin check.
+- Focused conditional action regression: PASS using production Android/iOS input
+  adapters and controlled fake native binaries. Coverage includes all supported
+  actions, each verification/response mode, late target-preparation changes,
+  mismatches, unavailable/malformed observations, session/history/device rejection,
+  request isolation, native input failure, and journey stop. Complete native
+  observation/input paths also pass with fake ADB/idb, including child-close
+  evidence for condition timeouts. This is simulated platform evidence.
+- Focused schema parity and retention tests: PASS. Advertised JSON schemas are
+  exercised using the existing MCP SDK's validator, alongside runtime schemas.
+  All elements contribute to revision checks beyond the bounded delta history.
+- `npm run sync:agent-plugin`: PASS; no generated manifest differences.
+- Final `npm run verify`: PASS (lint, build, 59 unit-test files, plugin consistency).
+  Log: `/tmp/mobile-debug-conditional-verify-final.log`.
+- Initial `npm run test:device`: FAIL at iOS UI-tree smoke (`Invalid UI tree resolution`) while the original simulator was booting.
+  Android screenshot/log/tree wrappers passed. iOS screenshot wrapper passed;
+  the iOS log wrapper also reported pass but its underlying log retrieval printed
+  `getpwuid_r` / unavailable log-store errors, so this is not evidence of usable
+  iOS logs. These wrappers use automatic device selection; focused tests below
+  pin their simulator explicitly. Full log: `/tmp/mobile-debug-conditional-device-suite.log`.
+
+- Final `npm run test:device`: PASS after the replacement iPhone 17 Pro finished
+  booting. All six Android/iOS screenshot, log, and tree smoke wrappers passed,
+  without the earlier iOS log-store diagnostics. Log:
+  `/tmp/mobile-debug-conditional-device-suite-final.log`.
+- Final documentation relative-link checks and `git diff --check`: PASS.
+- Final lint after the device helper's selector/start-state correction: PASS.
+
+### Focused Android emulator evidence
+
+Command (against the built server over MCP stdio, no mocked tool handlers):
+
+```sh
+node --import tsx test/device/manual/interact/conditional_actions.manual.ts \
+  --platform android --id emulator-5554 \
+  --target-text 'Network & internet' --destination-text Internet \
+  --output /tmp/mobile-debug-conditional-android.json
+```
+
+Device: Android 16 sdk_gphone64_arm64, `emulator-5554`.
+Build: local `dist/server.js`, handshake `mobile-debug-mcp` 0.32.4, with
+`expectedState` confirmed in its advertised tool schema. This is the working-tree
+build, not proof of a published release.
+Starting state: system Settings root, with Network & internet visible.
+
+| Journey | Actions / expected outcome | Observed outcome | Result |
+| --- | --- | --- | --- |
+| Matching snapshot | Observe Settings; conditional coordinate tap Network & internet | `matched`, delivered once; fresh tree contains Internet | PASS |
+| Stale snapshot, compact | On network page, attempt safe back-navigation tap with root expectation | `PRECONDITION_FAILED`, not delivered; compact tree contains Internet; fresh tree confirms network page remains | PASS |
+| Stale snapshot, debug | Repeat guarded back navigation with root expectation | Same non-delivery and unchanged destination, full debug evidence | PASS |
+| Journey stop, compact | Successful wait for Internet, conditional back tap with root expectation, later tap | Earlier wait passed, guarded step failed with fresh tree, later step `not_run`; destination remained | PASS |
+| Journey stop, debug | Same sequence in debug mode | Same stop and preserved evidence | PASS |
+
+Full structured evidence: `/tmp/mobile-debug-conditional-android.json`.
+The five scenarios were rerun successfully against the final built server after
+the compact-error and metadata-validity fixes and the helper selector correction.
+The helper is reproducible and requires a deliberately prepared safe system
+Settings screen. No setting or subscription was changed. The original Modul8
+dev app was brought back to the foreground after checks.
+
+### Focused iOS simulator evidence
+
+The original iPhone Air simulator stalled during boot and was closed/rebooted by
+the user. The replacement iPhone 17 Pro became responsive; read-only screenshot
+and UI-tree checks confirmed Home and then Settings before running input checks.
+No boot/restart/reset commands were issued by the agent.
+
+Command:
+
+```sh
+node --import tsx test/device/manual/interact/conditional_actions.manual.ts \
+  --platform ios --id F9243BAF-62A8-4990-8A99-17F527F56FDA \
+  --target-text General --destination-text About \
+  --output /tmp/mobile-debug-conditional-ios.json
+```
+
+Device: iOS 26.4 iPhone 17 Pro simulator,
+`F9243BAF-62A8-4990-8A99-17F527F56FDA`.
+Build: the same local `dist/server.js` 0.32.4 build and MCP stdio route as Android,
+with condition support confirmed in tool discovery.
+Starting state: Settings root with General visible, About absent.
+
+| Journey | Actions / expected outcome | Observed outcome | Result |
+| --- | --- | --- | --- |
+| Matching snapshot | Observe Settings; conditional coordinate tap General | `matched`, delivered; fresh tree contains About | PASS |
+| Stale snapshot, compact | Attempt safe back-navigation tap with Settings-root expectation | `PRECONDITION_FAILED`, not delivered; compact fresh tree contains About; new observation confirms General stays visible | PASS |
+| Stale snapshot, debug | Same guarded back navigation | Same non-delivery and preserved full condition tree | PASS |
+| Journey stop, compact | Successful wait for About, stale conditional tap on `resource_id: BackButton`, later back tap | Wait passed; condition failed; later step `not_run`; General remained visible | PASS |
+| Journey stop, debug | Same sequence in debug mode | Same stop and fresh condition evidence | PASS |
+
+Structured evidence: `/tmp/mobile-debug-conditional-ios.json`.
+An initial helper attempt selected the application container sharing the Settings
+label and correctly stopped with `ELEMENT_NOT_INTERACTABLE` / `not_checked`;
+this was not counted as a conditional-journey pass. The helper now prefers the
+unique native resource ID and requires the destination to be absent from its
+starting screen. A subsequent incorrect-start attempt was also discarded.
+The final five-pass run above starts at the confirmed root and uses BackButton.
+
+Cleanup: only navigation was exercised. No setting, permission, account, or app
+data was changed. Home is restored after the smoke-suite rerun.
+
+### Focused quality review
+
+Reviewed the shared condition schema and advertised definitions, action wrapper
+and journey dispatch, Android/iOS native input boundaries, observation metadata
+and history, budget ancestors, compact serialization, error/recovery mapping,
+and associated tests/callers. The guard runs after adapter preparation, and
+blocked conditions replace generic adapter failures without inventing an execute
+trace or allowing recovery. Condition observation budgets pause only the current
+action; enclosing deadlines still apply. Tests check no late input after timeout
+and native observation child closure. No new framework or dependency was added.
+
+Review findings fixed:
+
+- Journey light-verification response overlay must preserve `not_requested` when
+  its conditional tap did not dispatch.
+- Compact tree responses must retain observation errors instead of looking like
+  successful deltas carrying an old revision/session. Added a regression test.
+- Repeated successful observations refresh retained revision timestamps, so a
+  recently observed stable screen does not yield an immediately unusable baseline.
+
+Limits: live simulator checks cover conditional taps and journey stops; conditional
+swipes and Android typing/back use production-adapter tests with fake native
+tools. Physical devices were not used for mutation checks. UI normalization, the observation-to-OS-input race, and concurrent external
+input remain explicit spec limits. No mutation testing was performed. No tests
+or validation rules were weakened. Existing uncommitted process/skill relocation
+work was preserved. No package was published and nothing was committed/pushed.

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.