mobile-debug-mcp 0.32.2 → 0.33.0

package/docs/specs/process.md

@@ -0,0 +1,213 @@
+# Development process
+
+This is the required development workflow for all agents contributing to
+`mobile-debug-mcp`. Read it before planning, editing, or reviewing changes,
+including work delegated to another agent. [AGENTS.md](../../AGENTS.md) is the
+shared entrypoint; tool-specific instructions must point here rather than
+maintain a competing workflow. Explicit user instructions take precedence.
+
+The agent owns investigation, implementation, and verification. The user or
+explicitly designated maintainer owns product decisions and approval. Existing
+explicit approval in the current conversation counts for unchanged scope; do
+not ask for it again. Never invent approval or treat silence as approval.
+
+## Choose the path
+
+Use the full process for new MCP capabilities, material tool behaviour or
+contract changes, and significant architecture changes. Use the lightweight
+path for fixes restoring agreed behaviour, refactors that preserve contracts,
+small maintenance changes, and documentation-only work. Move to the full path
+if investigation exposes new behaviour or unresolved product decisions.
+
+For the lightweight path:
+
+1. State the intended outcome and scope in the conversation.
+2. Inspect the relevant code, contracts, tests, and instructions.
+3. Make focused changes and run applicable verification below.
+4. Report the changes, evidence, and remaining limitations.
+
+Separate intent, spec, and plan files and approval stages are not required for
+the lightweight path. Documentation-only changes require a diff, link/path,
+and consistency check; application builds and device tests are unnecessary.
+
+For the full path, keep `intent.md`, `spec.md`, and `plan.md` together under
+`docs/specs/<next-number>-<feature>/`, following existing directory naming.
+Reuse the relevant feature directory where appropriate. Do not rewrite old
+specs retrospectively; add only what is needed for the current scope.
+
+## Keep artifacts concise
+
+Use these writing defaults for the full path:
+
+- `intent.md`: about 200 words covering the problem, outcome, scope, and open
+  questions, with the required source and status information.
+- `spec.md`: about 800 words focused on behaviour, contracts, failure handling,
+  acceptance criteria, and decisions needing approval.
+- `plan.md`: a short implementation checklist and verification table. Append
+  actual results as work finishes.
+
+These are defaults, not limits. Add detail when complexity or risk requires it;
+retain all applicable stage requirements and approval gates below. Record each
+decision once and reference it from later documents instead of repeating it.
+Use examples only where a contract would otherwise be ambiguous. Link detailed
+logs and evidence rather than copying them, while keeping enough result detail
+in the plan to assess coverage and any remaining failures or blockers.
+
+## 1. Capture intent
+
+Write `intent.md` with:
+
+- The original problem and its source, preserving the originator's meaning.
+- Desired outcome, affected MCP clients, platforms, and observable success criteria.
+- Constraints, exclusions, assumptions, and open questions.
+- Originator, date, and status; do not invent identities.
+
+Show the captured intent and obtain explicit agreement before drafting the
+spec. A clarification about one detail does not approve the complete intent.
+Record the approving response and its scope. While approval is pending,
+continue only investigation or independent work that does not assume it.
+
+**Exit:** the user has accepted the problem and scope, and questions blocking
+specification are answered.
+
+## 2. Investigate and specify
+
+Inspect the current checkout and preserve unrelated changes. Ground the design
+in existing code, tests, and [tool contracts](../tools/TOOLS.md). Reuse helpers
+and conventions rather than introducing new frameworks without a concrete need.
+
+Load applicable repository skills from [.agents/skills/](../../.agents/skills/README.md):
+
+- [Test authoring](../../.agents/skills/test-authoring/SKILL.md) before creating or updating tests.
+- [MCP builder](../../.agents/skills/mcp-builder/SKILL.md) for build, installation, or native toolchain work.
+- [Spec review](../../.agents/skills/spec-review/SKILL.md) when reviewing an RFC or spec draft.
+
+For device-dependent behaviour, inspect the current tool flow on an available
+device or emulator when practical. Record the platform, device, server build,
+observed behaviour, and inaccessible states. If unavailable, record the concrete
+blocker and available code/test evidence; plan a runnable device check.
+
+Write `spec.md` defining:
+
+- Required behaviour and plain-language acceptance criteria linked to the intent.
+- Scope, exclusions, failure, recovery, cancellation, and timeout behaviour.
+- MCP tool names, input schemas, response/error shapes, and compatibility impact.
+- Android/iOS differences and unsupported environments where applicable.
+- Device/process targeting, resource ownership and cleanup, concurrency, and
+  subprocess handling where relevant.
+- Security and privacy implications, including arguments, logs, screenshots,
+  UI trees, credentials, and potentially destructive device actions.
+- Affected modules, risks, assumptions, and unresolved decisions.
+- Approval status and a reference to the actual approving decision.
+
+Show the complete spec and obtain explicit acceptance before planning
+implementation. An instruction to implement an already accepted spec authorises
+that scope.
+
+**Exit:** the spec is accepted and decisions blocking correctness or scope are resolved.
+
+## 3. Plan implementation and verification
+
+Save `plan.md` with:
+
+- References to intent, spec, and approval decisions.
+- Affected files/modules and an ordered implementation checklist.
+- Dependencies, risks, compatibility, rollout, and cleanup steps as applicable.
+- Each acceptance criterion mapped to a meaningful automated or device check.
+- Exact verification commands and required runtime/toolchain versions.
+- For device checks: platform/device, starting state, actions, expected result,
+  evidence to capture, fixture requirements, and cleanup.
+- Unavailable prerequisites, their owner where known, and how to obtain them or
+  perform an equivalent check.
+
+Use the existing lightweight self-running `tsx` test pattern. No separate
+scenario language, scenario-approval stage, or new test framework is required.
+Routine technical planning choices do not need separate approval.
+
+Check scarce prerequisites early. Treat missing access as a planning blocker
+only when an essential acceptance criterion has no credible verification route.
+Do not describe readiness checks as verification of unimplemented behaviour.
+
+**Exit:** implementation is authorised within the accepted spec, the plan has
+no unresolved blocking dependency, and essential criteria have credible checks.
+
+## 4. Implement and handle discoveries
+
+Implement the agreed scope, add meaningful regression coverage where needed,
+and update the plan as work completes. Place tests according to the test-authoring
+skill: automated unit tests in `test/unit/`, automated device checks in
+`test/device/automated/`, and manual/debug helpers in `test/device/manual/`.
+
+Review changed code, tests, and relevant callers for contract consistency,
+platform differences, error handling, subprocess safety, resource cleanup,
+state ownership, and reliable assertions. Review depth should match the risk.
+
+When new evidence changes the work:
+
+- Update the plan for routine implementation choices.
+- Update the spec for design or contract changes. Obtain agreement before
+  implementing material changes to behaviour, scope, permissions, data handling,
+  compatibility, or acceptance criteria.
+- Update intent only if the problem or intended outcome changes; preserve the
+  original statement and record the accepted revision.
+- Record blockers and continue independent work. Do not silently weaken requirements.
+
+Keep [tool documentation](../tools/TOOLS.md), [README](../../README.md), and
+[changelog](../CHANGELOG.md) aligned when usage or behaviour changes.
+
+**Exit:** agreed implementation and relevant documentation are ready for verification.
+
+## 5. Verify and report
+
+For code or test changes, run focused checks during iteration and complete the
+maintainer verification command from the repository root:
+
+```sh
+npm run verify
+```
+
+This currently runs lint, TypeScript build, all automated unit tests, and the
+agent-plugin consistency check. Confirm scripts in [package.json](../../package.json)
+and applicable [CI workflows](../../.github/workflows) in the current checkout;
+report any difference between local validation and CI coverage.
+
+For changes affecting native device interaction, platform tooling, or runtime
+behaviour, also run applicable automated device checks:
+
+```sh
+npm run test:device
+```
+
+Confirm which platforms and behaviours the suite actually covers. Supplement
+it with focused end-to-end tool calls on the updated server where required by
+the acceptance criteria. A passing Android check does not establish iOS support;
+a dispatched action or mocked subprocess does not prove a real device outcome.
+
+For each relevant device journey, record the platform/device and server build,
+starting state, actions/tool calls, expected and observed result, evidence, and
+**pass**, **fail**, **blocked**, or **unrun** status. Include failure, recovery,
+interruption, and cleanup paths where relevant. Restore device settings and
+remove temporary test data after verification. If a platform or prerequisite is
+unavailable, state the concrete blocker and next step rather than claiming full
+verification.
+
+For schema changes, check registration, dispatch, runtime validation, response
+serialization, documentation, and callers/fixtures together. Distinguish local
+compatibility checks from testing an installed or published package.
+
+Investigate failures against the agreed contract. Do not weaken assertions,
+skip tests, add suppressions, or lower validation rules merely to get a pass.
+Distinguish pre-existing failures from regressions with evidence; neither is a
+pass. Fix issues introduced by the change and report unrelated findings separately.
+
+For documentation-only work, inspect the diff, validate changed relative links
+and referenced paths/commands, and check consistency across agent entrypoints.
+Required pull-request CI checks still apply.
+
+**Exit:** all agreed work and applicable checks have passed. Otherwise, report
+partial completion and identify failed, blocked, or unrun checks explicitly.
+
+The final report states what changed, verification commands and outcomes,
+relevant device evidence, focused review findings, and remaining limitations.
+Summarise successful output rather than pasting full logs. Commit, push, publish,
+and release only within the user's authorised workflow.

package/docs/tools/TOOLS.md

@@ -7,6 +7,9 @@ This repository groups the MCP tools into four areas aligned with the codebase:
 - [interact](interact.md) — UI resolution, actions, waits, and deterministic verification
 - [system](system.md) — environment and health checks
 
+Correlation metadata and explicit action references are documented in
+[correlated evidence](evidence.md).
+
 ## Agent guidance
 
 For interactive flows, the intended deterministic pattern is:

package/docs/tools/evidence.md

@@ -0,0 +1,79 @@
+# Correlated evidence
+
+Covered actions (`start_app`, `restart_app`, `tap`, `tap_element`, `swipe`,
+`scroll_to_element`, `type_text`, `press_back`, `adjust_control`) return an
+additive `evidence` object in their first JSON content block. Journey steps have
+individual action IDs and share the journey correlation ID.
+
+To associate a later observation, copy the action's `evidence.session_id` and
+`evidence.action_id` into `actionRef`:
+
+```json
+{
+  "platform": "android",
+  "deviceId": "emulator-5554",
+  "actionRef": { "sessionId": "<evidence.session_id>", "actionId": "<evidence.action_id>" }
+}
+```
+
+Supported observation tools: `capture_screenshot`, `get_ui_tree`,
+`get_screen_fingerprint`, `capture_debug_snapshot`, `get_logs`, `read_log_stream`.
+The reference object accepts only those two keys, each a string of 1–128
+characters. Malformed references fail before collection. References never select
+or redirect devices. A missing reference creates independent evidence; there is
+no automatic association with the latest action.
+
+Completed actions remain referenceable for 10 minutes, with at most 1,000 records
+per server process. Restart changes the session. Unknown, expired, foreign-session,
+or different-device references still collect independently: `association` is
+`unavailable`, `association_reason` explains why, and `action_id` is null.
+
+## Reading metadata
+
+`session_id`, `correlation_id`, `action_id`, `device`, and `association` identify
+the operation. Association is `self`, `explicit`, `internal`, `none`, or
+`unavailable`. Target scope is the resolved device; UI evidence is device-wide.
+`requested_action_ref` preserves an explicit reference, including unavailable ones.
+
+Phase fields are server UTC epoch milliseconds:
+
+- `operation_started_at_ms` / `operation_completed_at_ms`: this call.
+- `dispatch_started_at_ms` / `dispatch_completed_at_ms`: actual action dispatch,
+  first start through last completion for multi-input actions.
+- `verification_completed_at_ms`: verification attempt completion, including
+  failure or timeout; null when skipped. Read the existing verification status
+  to determine its outcome.
+
+Unreached/uninstrumented phases are null. Host monotonic time governs ordering
+and retention. A detected clock reversal yields unknown freshness and null age.
+
+`observations` contains separate screenshot, UI-tree, fingerprint, activity, and
+log records. Each has `evidence_id`, device, component status (`captured`, `failed`,
+`omitted`), acquisition start/completion, source capture time, age, freshness and
+reasons. Tree records retain snapshot session/revision references. Failed records
+preserve available errors; disabled captures are omitted. Snapshot components
+are collected independently, including fallback log reads; they are not atomic.
+
+Visual freshness is evaluated when the response is assembled:
+
+| Status | Meaning |
+| --- | --- |
+| `fresh` | Newly acquired with no known intervening covered dispatch; app state may still change. |
+| `stale` | Before the associated action or superseded by a later covered dispatch. |
+| `unknown` | Overlap, reuse, failure, unknown scope/timing, or clock discontinuity. |
+| `not_applicable` | Omitted logs. |
+
+Cached source times are preserved. `age_ms` is nullable; clients choose their own
+age limits. Freshness does not replace conditional-action safeguards.
+
+Log timestamps remain on their original device/unknown clock. Log records expose
+`clock: "device_or_unknown"`, `event_time_comparable: false`, and nullable earliest/
+latest parseable entry times. Collection after an action does not prove emission
+after it, or causality. No implicit action-window filtering is applied.
+
+Existing payloads, image blocks, and log blocks remain available. Snapshot evidence
+sits alongside `raw` and `semantic`. Android ADB and supported iOS simulators share
+this contract; existing provider limitations still apply. `trace_context` reports
+`{ "supported": false, "trace_id": null, "markers": [] }` for future trace linkage.
+Correlation history stores identifiers, scope, timing, and ordering only, without
+captured content, arguments, persistence, or telemetry.

package/docs/tools/interact.md

@@ -19,6 +19,90 @@ Important:
 - action tools report execution success, not outcome correctness.
 - `classify_action_outcome` should receive the runtime `action_type` when you want routing to distinguish local-state and side-effect actions.
 
+## Conditional actions
+
+`tap`, `tap_element`, and `swipe` (Android/iOS), plus Android `type_text` and
+`press_back`, accept an optional expected UI snapshot. Journey `tap` steps accept
+it per step. Other tools and step types reject `expectedState` rather than ignore
+it; it is not supported in journey defaults or on the journey itself.
+
+First call `get_ui_tree` on the chosen device. From a successful response, use
+`snapshot_session_id` and `snapshot_revision`:
+
+```json
+{
+  "platform": "android",
+  "deviceId": "emulator-5554",
+  "selector": { "accessibility_id": "save" },
+  "expectedState": {
+    "snapshotSessionId": "<snapshot_session_id from get_ui_tree>",
+    "snapshotRevision": 12,
+    "timeoutMs": 15000
+  },
+  "verificationMode": "none",
+  "responseMode": "compact"
+}
+```
+
+This is a `tap_element` example. Guarded standalone calls require explicit
+`platform` and concrete `deviceId` from the observed tree; `booted` and `default`
+are not valid guarded targets. Journey taps inherit the journey's resolved device.
+The expected-state object is strict: nonempty session ID, positive safe-integer
+revision, and optional integer timeout of 100–60000 ms (default 15000). Invalid or
+unsupported conditions return an `INVALID_ARGUMENT` error before device work.
+Calls without a condition preserve existing behaviour.
+
+After target and adapter preparation, the server reads a new hierarchy just
+before native input. It checks the same device, server session, and retained
+revision, even with post-action verification disabled. It never waits for a
+mismatch to become a match or retries/rebases the input automatically.
+
+| Result | Meaning |
+| --- | --- |
+| `condition.status: matched` | Condition passed; inspect the ordinary action outcome for delivery and verify its effect separately. |
+| `PRECONDITION_FAILED`, `condition.status: mismatch` | State changed; input was not dispatched. The condition includes the exact fresh tree that blocked it. |
+| `PRECONDITION_UNAVAILABLE`, `condition.status: unavailable` | Condition could not be established; input was not dispatched. Inspect `condition.reason` and observe again. |
+| `condition.status: not_checked` | Target/capability preparation failed before reaching the guard; inspect the original action failure. |
+
+Blocked input reports `success: false`, `dispatch_started: false`,
+`delivery_status: not_delivered`, `retryable: false`, `lifecycle_state: failed`,
+and `verification.status: not_requested`. No network action window is reset and
+no post-input verification runs. A failed conditional journey tap stops the
+journey; subsequent steps are `not_run` and earlier steps are not rolled back.
+
+Condition evidence has `status`, `expected: { snapshot_session_id,
+snapshot_revision }`, `observed`, `elapsed_ms`, and an optional `reason`.
+Reasons are `BASELINE_UNAVAILABLE`, `SESSION_MISMATCH`, `DEVICE_MISMATCH`,
+`OBSERVATION_FAILED`, `OBSERVATION_INVALID`, `CONDITION_TIMEOUT`, or
+`ACTION_NOT_REACHED` for a check that was not reached. `observed` is null when
+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.
+
+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
+revision. Server restart or eviction requires a new observation. A fresh read
+cannot evict the baseline out from under its own check.
+
+The match covers the existing normalized accessibility snapshot: element text,
+identity, state, bounds, actionability, screen, and resolution. String identity
+fields are trimmed/lowercased; native state values retain their representation.
+All elements contribute, even when delta history is truncated. Pixel-only,
+backend, inaccessible, and normalization-hidden changes are not detected; the
+current tree does not establish foreground package/activity. Any observed
+intervening change invalidates the old revision, even if the UI later returns.
+
+A condition read can add seconds. Its timeout budget is separate from the action
+budget; enclosing operation deadlines still apply. This check is not atomic with
+OS input delivery. Concurrent clients, external input, or app updates can change
+the UI after the observation. Sequence device actions and verify outcomes with
+`expect_*` as usual.
+
 ## tap / swipe / type_text / press_back
 
 These tools return a shared action execution envelope.
@@ -633,7 +717,13 @@ has unknown delivery and must be observed before retrying.
 
 `tap_element` accepts exactly one `elementId` or `selector`. A selector supports
 `text`, `resource_id`, `accessibility_id`, and `contains`. Optional `waitFor` waits
-for the target before tapping; without it, resolution uses one observation.
+for the target before tapping; without it, resolution uses one observation with
+the action budget (default 5,000 ms), rather than a separate shorter cutoff.
+An explicit `waitFor.timeoutMs` remains bounded by the overall action budget.
+Selector taps resolve matching label text to its actionable ancestor using the
+existing clickable-wait policy, including `waitFor.condition: exists` or `visible`.
+Hidden/disabled labels and non-actionable containers cannot be bypassed.
+Observation timeouts report `ACTION_TIMEOUT`, rather than claiming a missing target.
 Ambiguous targets require an explicit `waitFor.match.index`.
 
 `run_journey` accepts 1–50 steps with unique IDs, on one platform/device. Supported
@@ -644,5 +734,38 @@ the journey; remaining steps report `not_run`. Journey responses default to comp
 `defaults` supplies execution controls; step verification overrides the default.
 `captureOnFailure: true` includes a screenshot-free failure snapshot in debug mode.
 
-See [RFC 018](../specs-deltas/018-interaction-latency-and-batched-journeys.md) for
+See [RFC 018](../specs/018-interaction-latency-and-batched-journeys/spec.md) for
 contracts and the device acceptance criteria.
+
+## Readiness-aware waits
+
+`wait_for_ui` and `wait_for_ui_change` accept optional `requireReady: true`.
+They require both their existing predicate and settled full-screen UI readiness
+on the same current samples. Readiness uses a 500 ms stability window, shares the
+wait's existing deadline (including retries), and adds no separate hierarchy reads.
+
+```json
+{
+  "platform": "android",
+  "deviceId": "emulator-5554",
+  "selector": { "text": "Ready" },
+  "condition": "visible",
+  "requireReady": true,
+  "timeout_ms": 30000
+}
+```
+
+Results retain the existing success/timeout envelope and include `readiness`
+evidence and limitations. Opt-in shared-deadline expiry uses a `TIMEOUT` error
+code and preserves whether the underlying predicate was observed; a readiness
+timeout does not mean that a visible target was absent. A visible target while a loader is active cannot pass
+this opt-in check. Observation failure resets readiness continuity; an exhausted
+budget is not proof of an unresponsive app. Default `requireReady: false` retains
+existing predicate semantics. There is no new journey assertion or change to
+conditional-action preconditions. See [app readiness](observe.md#app-readiness)
+for supported states and limits.
+
+## Correlated evidence
+
+Actions and journeys expose identifiers and phase timestamps for linking later
+observations. See [correlated evidence](evidence.md) for scope and limitations.

package/docs/tools/observe.md

@@ -10,6 +10,9 @@ These tools are primarily for:
 
 They are **not** the primary success signal when an applicable `expect_*` tool exists.
 
+Covered observations support optional `actionRef` and return acquisition/freshness
+metadata; see [correlated evidence](evidence.md).
+
 ## get_logs
 
 Fetch recent logs as structured entries optimized for AI agents.
@@ -91,9 +94,13 @@ Notes:
 - Elements may include a normalized `state` object when the platform exposes readable state such as checked, selected, focused, expanded, text input, or slider values.
 - Elements may also include platform-native identity hints such as `stable_id`, `role`, `test_tag`, `selector`, and `semantic`.
 - The tree response may include `snapshot_revision`, `captured_at_ms`, and `loading_state` when a reliable signal is available.
+- Successful tree observations include `snapshot_session_id`, a random identifier
+  for this server process. Use it with `snapshot_revision` for
+  [conditional actions](interact.md#conditional-actions) on the same device.
+  Compact tree responses preserve the session ID and revision. Never derive an
+  expectation from an error tree, even when it carries an older revision.
 - Prefer `wait_for_ui` for deterministic element resolution in interactive flows.
-- Android 14+ can use the experimental persistent hierarchy reader. Build its APK with `npx tsx test/fixtures/ui-tree-bridge/build.ts`, then set `MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK` to its absolute path before starting the server. The reader clears Android's accessibility cache before every tree read, including when a screen changes without an accessibility event. Older Android versions use `uiautomator dump`.
-- If the bridge fails, the server stops it before falling back to `uiautomator dump`. While running, the bridge holds Android's UiAutomation connection, so other `uiautomator dump` clients may fail. Leave the variable unset for the default reader. To reproduce the device probe, set `LATENCY_DEVICE_ID` and run `npx tsx test/device/automated/ui-tree-performance/bridge-probe.ts`.
+- Android reads the accessibility hierarchy with `uiautomator dump` through ADB. No helper APK is installed or required.
 
 ---
 
@@ -211,3 +218,58 @@ read_log_stream response example:
 ```json
 { "entries": [ { "timestamp": "2026-03-20T...Z", "level": "ERROR", "tag": "AppTag", "pid": 1234, "message": "FATAL EXCEPTION" } ], "crash_summary": { "crash_detected": true } }
 ```
+
+## App readiness
+
+`get_app_readiness` observes at most two fresh hierarchies; `wait_for_app_ready`
+waits for settled evidence within one budget. Require `platform`; optionally
+select `deviceId`. Each call pins its device and keeps its sampling history local.
+
+| Control | Default | Accepted integer range |
+| --- | --- | --- |
+| `timeoutMs` | get: 15000; wait: 30000 | 100–60000 |
+| `stabilityMs` | 500 | 100–10000 |
+| `pollIntervalMs` (wait only) | 500 | 100–1000 |
+
+```json
+{ "platform": "android", "deviceId": "emulator-5554", "timeoutMs": 30000 }
+```
+
+Both return `success`, resolved `device`, `readiness`, `elapsed_ms`, and a
+`failure_code` on failure. Get succeeds when it establishes loading, transitioning,
+or settled; wait succeeds only for settled. Codes are `READINESS_UNAVAILABLE`,
+`READINESS_TIMEOUT`, and `DEVICE_UNAVAILABLE`. Invalid/unknown inputs are rejected.
+
+`readiness.state` is loading, transitioning, settled, or unknown. Visible native
+progress indicators establish loading; exact Loading / Please wait labels
+(ignoring case, whitespace and trailing dots/ellipsis) are heuristic loading.
+Loading takes priority over unchanged trees. Two different valid signatures show
+transitioning; consecutive identical signatures spanning the stability window
+show settled. Failed, empty, stale-session, wrong-device, or invalid observations
+cannot establish stability and break sample continuity. Broad legacy loading
+keywords such as a button named Progress are not sufficient loading evidence.
+
+The summary includes `basis` (observed/heuristic/insufficient), `scope: device_ui`,
+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. Unresponsive and
+debugger-paused detection are explicitly unsupported on both platforms; neither
+slow hierarchy retrieval nor a deadline expiry proves either state.
+
+Tree responses (including compact and nested trees) add a single-sample readiness
+summary without extra reads. Such a summary reports loading or unknown; it does
+not inherit stability from an earlier request. Existing loading/delta fields and
+compact error evidence are preserved.
+
+Readiness describes normalized foreground UI during the capture window. It does
+not verify foreground app identity, process health, business outcome, or backend
+completion, and does not guarantee the UI will stay unchanged. A screenshot alone
+never establishes readiness. Network observation windows and device input are
+untouched. Timeouts include `DEADLINE_EXCEEDED` and retain the last valid
+readiness evidence; an aborted acquisition does not erase that observation.
+A non-timeout observation failure still makes current state unknown. Sampling and subprocess cleanup respect outer budgets.
+Transport cancellation does not currently abort platform reads immediately;
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.32.2",
+  "version": "0.33.0",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {
@@ -19,7 +19,9 @@
     "test": "npm run test:unit",
     "lint": "eslint src test --quiet",
     "lint:fix": "eslint src test --fix",
-    "verify": "npm run lint && npm run build && npm run test:unit"
+    "sync:agent-plugin": "node scripts/agent-plugin.mjs --sync",
+    "check:agent-plugin": "node scripts/agent-plugin.mjs --check",
+    "verify": "npm run lint && npm run build && npm run test:unit && npm run check:agent-plugin"
   },
 
   "engines": {

package/scripts/agent-plugin.mjs

@@ -0,0 +1,98 @@
+import assert from 'node:assert/strict'
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+
+const repositoryRoot = fileURLToPath(new URL('../', import.meta.url))
+const pluginRoot = path.join(repositoryRoot, 'agent-plugin')
+const packagedSkill = path.join(pluginRoot, 'skills/mobile-debug-mcp/SKILL.md')
+const packagedLicense = path.join(pluginRoot, 'LICENSE')
+const sourceLicense = path.join(repositoryRoot, 'LICENSE')
+const packageInfo = JSON.parse(readFileSync(path.join(repositoryRoot, 'package.json'), 'utf8'))
+const plugin = JSON.parse(readFileSync(path.join(pluginRoot, 'plugin.json'), 'utf8'))
+const mcp = JSON.parse(readFileSync(path.join(pluginRoot, 'mcp.json'), 'utf8'))
+const { $schema: _pluginSchema, extensions, ...pluginMetadata } = plugin
+const { $schema: _mcpSchema, ...codexMcp } = mcp
+const codexManifest = {
+  ...pluginMetadata,
+  skills: './skills/',
+  mcpServers: './.mcp.json',
+  interface: extensions['com.openai'].interface,
+}
+const sharedMetadata = Object.fromEntries(
+  ['name', 'version', 'description', 'author', 'repository', 'license'].map(key => [key, plugin[key]]),
+)
+const claudeManifest = {
+  ...sharedMetadata,
+  mcpServers: {
+    [packageInfo.name]: {
+      command: 'npx',
+      args: ['--yes', `${packageInfo.name}@${packageInfo.version}`, 'server'],
+    },
+  },
+}
+const cursorManifest = {
+  ...sharedMetadata,
+  skills: './skills/',
+  mcpServers: {
+    [packageInfo.name]: {
+      type: 'stdio',
+      command: 'npx',
+      args: ['--yes', `${packageInfo.name}@${packageInfo.version}`, 'server'],
+      cwd: '${CURSOR_PLUGIN_ROOT}',
+    },
+  },
+}
+const manifests = [
+  ['.codex-plugin/plugin.json', codexManifest],
+  ['.claude-plugin/plugin.json', claudeManifest],
+  ['.cursor-plugin/plugin.json', cursorManifest],
+]
+
+if (process.argv[2] === '--sync') {
+  copyFileSync(sourceLicense, packagedLicense)
+  writeFileSync(path.join(pluginRoot, '.mcp.json'), `${JSON.stringify(codexMcp, null, 2)}\n`)
+  for (const [relativePath, manifest] of manifests) {
+    const manifestPath = path.join(pluginRoot, relativePath)
+    mkdirSync(path.dirname(manifestPath), { recursive: true })
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+  }
+}
+else if (process.argv[2] !== '--check') throw new Error('Use --sync or --check')
+
+assert.equal(plugin.$schema, 'https://agent-plugins.org/schemas/1.0.0/plugin.schema.json')
+assert.equal(plugin.name, 'mobile-debug-tools')
+assert.match(plugin.version, /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/, 'plugin releases use an independent semantic version')
+assert.equal(mcp.$schema, 'https://agent-plugins.org/schemas/1.0.0/mcp.schema.json')
+const servers = Object.entries(mcp.mcpServers)
+assert.equal(servers.length, 1, 'the plugin should expose only this MCP server')
+const [serverName, server] = servers[0]
+assert.equal(serverName, packageInfo.name)
+assert.equal(server.type, 'stdio')
+assert.equal(server.command, 'npx')
+assert.deepEqual(server.args, ['--yes', `${packageInfo.name}@${packageInfo.version}`, 'server'])
+assert.equal(server.cwd, '${PLUGIN_DATA}', 'npx must run outside the same-named source checkout')
+assert.deepEqual(readFileSync(packagedLicense), readFileSync(sourceLicense), 'packaged license must match its source')
+assert.deepEqual(JSON.parse(readFileSync(path.join(pluginRoot, '.mcp.json'), 'utf8')), codexMcp, 'Codex MCP configuration must match the portable plugin')
+for (const [relativePath, expectedManifest] of manifests) {
+  assert.deepEqual(
+    JSON.parse(readFileSync(path.join(pluginRoot, relativePath), 'utf8')),
+    expectedManifest,
+    `${relativePath} must match the portable plugin`,
+  )
+}
+for (const marketplacePath of [
+  '.agents/plugins/marketplace.json',
+  '.claude-plugin/marketplace.json',
+  '.cursor-plugin/marketplace.json',
+]) {
+  const marketplace = JSON.parse(readFileSync(path.join(repositoryRoot, marketplacePath), 'utf8'))
+  assert.equal(marketplace.name, plugin.name, `${marketplacePath} name must match the plugin`)
+  assert.equal(marketplace.plugins.length, 1, `${marketplacePath} must expose one plugin`)
+  assert.equal(marketplace.plugins[0].name, plugin.name, `${marketplacePath} plugin name must match`)
+  assert.equal(marketplace.plugins[0].source?.path ?? marketplace.plugins[0].source, './agent-plugin', `${marketplacePath} source must point to the plugin`)
+}
+const skillName = readFileSync(packagedSkill, 'utf8').match(/^---\r?\nname: ([a-z0-9-]+)\r?\n/)?.[1]
+assert.equal(skillName, path.basename(path.dirname(packagedSkill)), 'packaged skill directory must match its frontmatter name')
+
+console.log('Agent plugin package is in sync')