mobile-debug-mcp 0.36.0 → 0.37.0

package/README.md

@@ -10,6 +10,11 @@ Android, iOS, and Kotlin Multiplatform projects are supported. Flutter and React
 Native have not been tested. Platform and device limitations are described in the
 [tool reference](docs/tools/TOOLS.md).
 
+Use `responseMode: "compact"` for bounded interaction and journey summaries.
+Retrieve retained details without replaying input with
+[`get_interaction_diagnostics`](docs/tools/compact-interactions.md); debug output
+remains available.
+
 ## What you can use it for
 
 Mobile Debug Tools gives a coding agent access to a running app, so development
@@ -297,3 +302,8 @@ Android debugger errors include bounded, sanitized failure classifications and r
 ## License
 
 [Apache-2.0](LICENSE)
+
+Launch and interaction results distinguish dispatch from timestamped
+[device readiness evidence](docs/tools/observe.md#device-readiness-evidence).
+Readiness waits account for observed sleeping/locked device blockers. Unknown or
+unsupported signals are explicit, and no automatic unlock is performed.

package/agent-plugin/.antigravity-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://antigravity.google/schemas/v1/plugin.json",
   "name": "mobile-debug-tools",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Mobile app debugging tools and usage guidance for Android and iOS agents.",
   "author": {
     "name": "mobile-debug-tools contributors"

package/agent-plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-tools",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Mobile app debugging tools and usage guidance for Android and iOS agents.",
   "author": {
     "name": "mobile-debug-tools contributors"
@@ -12,7 +12,7 @@
       "command": "npx",
       "args": [
         "--yes",
-        "mobile-debug-mcp@0.36.0",
+        "mobile-debug-mcp@0.37.0",
         "server"
       ]
     }

package/agent-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-tools",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Mobile app debugging tools and usage guidance for Android and iOS agents.",
   "repository": "https://github.com/clivejefferies/mobile-debug-tools",
   "license": "Apache-2.0",

package/agent-plugin/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-tools",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Mobile app debugging tools and usage guidance for Android and iOS agents.",
   "author": {
     "name": "mobile-debug-tools contributors"
@@ -14,7 +14,7 @@
       "command": "npx",
       "args": [
         "--yes",
-        "mobile-debug-mcp@0.36.0",
+        "mobile-debug-mcp@0.37.0",
         "server"
       ],
       "cwd": "${CURSOR_PLUGIN_ROOT}"

package/agent-plugin/.mcp.json

@@ -5,7 +5,7 @@
       "command": "npx",
       "args": [
         "--yes",
-        "mobile-debug-mcp@0.36.0",
+        "mobile-debug-mcp@0.37.0",
         "server"
       ],
       "cwd": "${PLUGIN_DATA}"

package/agent-plugin/cursor/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-tools",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Mobile app debugging tools and usage guidance for Android and iOS agents.",
   "author": {
     "name": "mobile-debug-tools contributors"
@@ -14,7 +14,7 @@
       "command": "npx",
       "args": [
         "--yes",
-        "mobile-debug-mcp@0.36.0",
+        "mobile-debug-mcp@0.37.0",
         "server"
       ],
       "cwd": "${CURSOR_PLUGIN_ROOT}"

package/agent-plugin/cursor/skills/mobile-debug-mcp/SKILL.md

@@ -57,7 +57,14 @@ required. A 2-second timeout cannot reliably accommodate a 3-second tree read.
 Adjust to measured device latency and supported tool limits. Report an
 observation timeout separately from evidence that a control is absent.
 
-Use compact responses for routine actions. If action dispatch is reliable but
+Use compact responses for routine actions. Compact interaction/journey results retain
+outcomes, verification, readiness blockers and observed_state (or explicit unknown).
+For original errors, condition trees, state-delta elements and evidence timestamps,
+call get_interaction_diagnostics with diagnostics.session_id/result_id as
+sessionId/resultId. This reads retained data without replaying input. Results expire
+after ten minutes or earlier eviction (100 results, 16 MiB total, 1 MiB per result).
+Check diagnostics.available; unavailable details never justify automatic replay.
+Debug mode can request additional captures at execution time. If action dispatch is reliable but
 verification is slow or unavailable, dispatch with verification disabled and
 verify at meaningful checkpoints with one focused accessibility assertion or
 screenshot. Do not assume `light` verification is faster: use it only when it
@@ -103,7 +110,8 @@ actions are tap, element tap, swipe, Android typing/back, and journey tap steps.
 The server takes a fresh normalized hierarchy immediately before input.
 `PRECONDITION_FAILED` or `PRECONDITION_UNAVAILABLE` means input was blocked:
 inspect `condition` evidence and decide again; do not blindly retry or replace
-the expectation. Compact failures may contain the full UI tree and private text.
+the expectation. Compact failures summarize condition evidence; their diagnostics lookup may contain
+the full UI tree and private text. Compact output is not privacy redaction.
 Expectations expire with retained history or server restart. The extra hierarchy
 read can take seconds; it is not atomic with input delivery and does not prove
 the action's outcome.

package/agent-plugin/mcp.json

@@ -4,7 +4,7 @@
     "mobile-debug-mcp": {
       "type": "stdio",
       "command": "npx",
-      "args": ["--yes", "mobile-debug-mcp@0.36.0", "server"],
+      "args": ["--yes", "mobile-debug-mcp@0.37.0", "server"],
       "cwd": "${PLUGIN_DATA}"
     }
   }

package/agent-plugin/mcp_config.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "--yes",
-        "mobile-debug-mcp@0.36.0",
+        "mobile-debug-mcp@0.37.0",
         "server"
       ],
       "cwd": "${PLUGIN_DATA}"

package/agent-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "mobile-debug-tools",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Mobile app debugging tools and usage guidance for Android and iOS agents.",
   "repository": "https://github.com/clivejefferies/mobile-debug-tools",
   "license": "Apache-2.0",

package/agent-plugin/skills/mobile-debug-mcp/SKILL.md

@@ -57,7 +57,14 @@ required. A 2-second timeout cannot reliably accommodate a 3-second tree read.
 Adjust to measured device latency and supported tool limits. Report an
 observation timeout separately from evidence that a control is absent.
 
-Use compact responses for routine actions. If action dispatch is reliable but
+Use compact responses for routine actions. Compact interaction/journey results retain
+outcomes, verification, readiness blockers and observed_state (or explicit unknown).
+For original errors, condition trees, state-delta elements and evidence timestamps,
+call get_interaction_diagnostics with diagnostics.session_id/result_id as
+sessionId/resultId. This reads retained data without replaying input. Results expire
+after ten minutes or earlier eviction (100 results, 16 MiB total, 1 MiB per result).
+Check diagnostics.available; unavailable details never justify automatic replay.
+Debug mode can request additional captures at execution time. If action dispatch is reliable but
 verification is slow or unavailable, dispatch with verification disabled and
 verify at meaningful checkpoints with one focused accessibility assertion or
 screenshot. Do not assume `light` verification is faster: use it only when it
@@ -103,7 +110,8 @@ actions are tap, element tap, swipe, Android typing/back, and journey tap steps.
 The server takes a fresh normalized hierarchy immediately before input.
 `PRECONDITION_FAILED` or `PRECONDITION_UNAVAILABLE` means input was blocked:
 inspect `condition` evidence and decide again; do not blindly retry or replace
-the expectation. Compact failures may contain the full UI tree and private text.
+the expectation. Compact failures summarize condition evidence; their diagnostics lookup may contain
+the full UI tree and private text. Compact output is not privacy redaction.
 Expectations expire with retained history or server restart. The extra hierarchy
 read can take seconds; it is not atomic with input delivery and does not prove
 the action's outcome.

package/dist/contracts/device-readiness.js

@@ -0,0 +1 @@
+export {};

package/dist/interact/waits/ui-change-wait.js

@@ -1,7 +1,7 @@
 import { systemClock } from '../../runtime/clock.js';
 import { remainingBudget } from '../../utils/operation-budget.js';
 import { checkDebuggerGuard } from '../../debugger/guard.js';
-import { observeReadinessWait, isDeviceUnavailable } from '../../observe/readiness.js';
+import { observeReadinessWait, observeReadinessDeviceWait, isDeviceUnavailable } from '../../observe/readiness.js';
 import { readinessDelay } from '../../observe/readiness-service.js';
 import { _buildUiChangeSignatures, _summarizeUiChangeDelta, _matchesUiChange, _uiChangeSignaturesEqual } from './ui-change-helpers.js';
 import { createChangeWait, changeResult } from './ui-change-state.js';
@@ -26,12 +26,19 @@ function changed(s, signatures) {
         s.since = s.clock.now();
     }
     const stable = s.since === null ? 0 : s.clock.now() - s.since;
-    return (s.stability === 0 || stable >= s.stability) && (!s.tracker || s.tracker.summary.state === 'settled');
+    return (s.stability === 0 || stable >= s.stability) && (!s.tracker || s.tracker.ready);
 }
 async function sample(s, deps) {
     if (s.tracker)
         remainingBudget();
     const started = s.clock.now(), a = s.input;
+    await observeReadinessDeviceWait();
+    if (s.tracker?.deviceReadiness.input_ready === false) {
+        s.candidate = null;
+        s.change = null;
+        s.since = null;
+        return null;
+    }
     const tree = await deps.observe({ platform: a.platform, deviceId: a.deviceId });
     observeReadinessWait(tree, started);
     const scoped = deps.scope(tree, a.scope, a.target);

package/dist/interact/waits/ui-wait.js

@@ -1,12 +1,13 @@
 import { systemClock } from '../../runtime/clock.js';
+import { benchmarkStage } from '../../utils/benchmark-metrics.js';
 import { remainingBudget } from '../../utils/operation-budget.js';
 import { checkDebuggerGuard } from '../../debugger/guard.js';
-import { observeReadinessWait, isDeviceUnavailable } from '../../observe/readiness.js';
+import { observeReadinessWait, observeReadinessDeviceWait, isDeviceUnavailable } from '../../observe/readiness.js';
 import { readinessDelay } from '../../observe/readiness-service.js';
 import { matchingElements, evaluateCondition } from './ui-wait-condition.js';
 import { createUIWait, validateUIWait, waitObserved, waitFailure } from './ui-wait-state.js';
 async function delay(s, ms) {
-    await (s.tracker && s.clock === systemClock ? readinessDelay(ms) : s.clock.sleep(ms));
+    await benchmarkStage('poll_sleep_ms', () => s.tracker && s.clock === systemClock ? readinessDelay(ms) : s.clock.sleep(ms));
 }
 function acceptObservation(s, tree, now) {
     const age = typeof tree?.captured_at_ms === 'number' ? now - tree.captured_at_ms : null;
@@ -15,7 +16,7 @@ function acceptObservation(s, tree, now) {
         return null;
     }
     s.stable++;
-    if (s.stable < (s.args.singleObservation ? 1 : 2) || (s.tracker && s.tracker.summary.state !== 'settled'))
+    if (s.stable < (s.args.singleObservation ? 1 : 2) || (s.tracker && !s.tracker.ready))
         return null;
     return { status: 'success', ...(s.args.singleObservation ? { _tree: tree } : {}), matched: s.count,
         element: s.element, metrics: { latency_ms: now - s.start, poll_count: s.polls, attempts: s.attempts }, requested: s.requested, observed: waitObserved(s, true) };
@@ -50,6 +51,9 @@ async function poll(s, deps) {
     s.polls++;
     try {
         const started = s.clock.now(), a = s.args;
+        await observeReadinessDeviceWait();
+        if (s.tracker?.deviceReadiness.input_ready === false)
+            return null;
         const tree = await deps.observe({ platform: a.platform, deviceId: a.deviceId });
         observeReadinessWait(tree, started);
         if (a.resolveTapTarget && tree?.error && /ACTION_TIMEOUT|timed out/i.test(String(tree.error)))

package/dist/manage/index.js

@@ -1,3 +1,4 @@
+import { validAppId } from '../utils/app-installation.js';
 import { promises as fs } from 'fs';
 import path from 'path';
 import { resolveTargetDevice, listDevices } from '../utils/resolve-device.js';
@@ -313,6 +314,8 @@ export class ToolsManage {
         }
     }
     static async listDevicesHandler({ platform, appId }) {
+        if (appId !== undefined && !validAppId(appId))
+            throw new Error('Invalid appId');
         const devices = await listDevices(platform, appId);
         return { devices };
     }

package/dist/observe/device-readiness.js

@@ -0,0 +1,116 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { pausedReadiness } from '../debugger/guard.js';
+import { execCmd } from '../utils/exec.js';
+import { getAdbCmd } from '../utils/android/commands.js';
+import { getXcrunCmd } from '../utils/ios/utils.js';
+import { remainingBudget } from '../utils/operation-budget.js';
+import { benchmarkStage } from '../utils/benchmark-metrics.js';
+export function unknownDeviceReadiness(code) {
+    return { wakefulness: 'unknown', lock_state: 'unknown', input_ready: null, blockers: [], evidence: [], limitations: code ? [code] : [] };
+}
+function values(text, pattern) { return [...text.matchAll(pattern)].map(match => match[1]); }
+function unique(items) { return items.length > 0 && new Set(items).size === 1 ? items[0] : null; }
+export function parseAndroidPower(text) {
+    // Later vendor/debug sections can repeat mWakefulness as a numeric enum.
+    // Classify only the named current-state section when its boundary is present.
+    const main = text.split('Power Manager State:')[1];
+    if (main?.includes('Settings and Configuration:'))
+        text = main.split('Settings and Configuration:')[0];
+    const wake = unique(values(text, /^\s*mWakefulness=(\w+)\s*$/gm));
+    const changing = unique(values(text, /^\s*mWakefulnessChanging=(true|false)\s*$/gm));
+    if (!wake || !changing)
+        return 'unknown';
+    if (changing === 'true')
+        return 'transitioning';
+    return wake === 'Awake' ? 'awake' : ['Asleep', 'Dozing'].includes(wake) ? 'asleep' : 'unknown';
+}
+export function parseAndroidLock(text) {
+    const section = text.split(/\bKeyguardServiceDelegate\s*\n/)[1];
+    if (!section)
+        return 'unknown';
+    const showing = unique(values(section, /^\s*(?:showing|mIsShowing)=(true|false)\s*$/gm));
+    return showing === 'true' ? 'locked' : showing === 'false' ? 'unlocked' : 'unknown';
+}
+export function finishDeviceReadiness(state) {
+    if (state.wakefulness === 'asleep')
+        state.blockers.push('DEVICE_ASLEEP');
+    if (state.wakefulness === 'transitioning')
+        state.blockers.push('DEVICE_TRANSITIONING');
+    if (state.lock_state === 'locked')
+        state.blockers.push('DEVICE_LOCKED');
+    state.blockers = [...new Set(state.blockers)];
+    state.input_ready = state.blockers.length ? false : null;
+    return state;
+}
+export function parseIosLock(text) {
+    try {
+        const data = JSON.parse(text);
+        if (data.error?.domain === 'com.apple.dt.CoreDeviceError' && data.error.code === 1001 &&
+            data.error.userInfo?.CapabilityFeatureIdentifier?.string === 'com.apple.coredevice.feature.getlockstate')
+            return 'unsupported';
+        // Successful response semantics require runtime validation before classification.
+    }
+    catch { /* Non-JSON output supplies no state evidence. */ }
+    return 'unknown';
+}
+const probes = new AsyncLocalStorage();
+export function withDeviceReadinessProbe(probe, operation) { return probes.run(probe, operation); }
+const nativeProbe = (command, args, timeout) => execCmd(command, args, { timeout });
+export async function observeDeviceReadiness(device, probe = probes.getStore() ?? nativeProbe) {
+    return benchmarkStage('device_readiness_ms', () => observe(device, probe));
+}
+async function observe(device, probe) {
+    const state = unknownDeviceReadiness();
+    if (!device?.id || !['android', 'ios'].includes(device.platform) || ['booted', 'default'].includes(device.id))
+        return unknownDeviceReadiness('DEVICE_TARGET_UNAVAILABLE');
+    const paused = pausedReadiness(device.id, device.platform);
+    if (paused) {
+        state.blockers.push('DEBUGGER_PAUSED');
+        state.evidence.push({ code: 'DEBUGGER_PAUSED', source: 'debugger', captured_at_ms: paused.captured_at_ms });
+        return finishDeviceReadiness(state);
+    }
+    if (device.platform === 'android') {
+        await androidProbe(state, device.id, 'power', probe);
+        await androidProbe(state, device.id, 'window', probe);
+    }
+    else {
+        state.limitations.push('DEVICE_WAKEFULNESS_UNVERIFIED');
+        try {
+            const timeout = remainingBudget(1000);
+            // CoreDevice requires a CLI timeout of at least five seconds; the parent
+            // subprocess deadline still caps this read at one second.
+            const result = await probe(getXcrunCmd(), ['devicectl', 'device', 'info', 'lockState', '--device', device.id, '--timeout', '5', '--json-output', '-'], timeout);
+            remainingBudget();
+            state.lock_state = parseIosLock(result.stdout);
+            if (state.lock_state === 'unsupported')
+                state.evidence.push({ code: 'DEVICE_LOCK_SIGNAL_UNSUPPORTED', source: 'coredevice', captured_at_ms: Date.now() });
+            else
+                state.limitations.push('DEVICE_LOCK_OBSERVATION_UNAVAILABLE');
+        }
+        catch {
+            state.limitations.push('DEVICE_LOCK_OBSERVATION_FAILED');
+        }
+    }
+    return finishDeviceReadiness(state);
+}
+async function androidProbe(state, id, kind, probe) {
+    try {
+        const timeout = remainingBudget(1000);
+        const result = await probe(getAdbCmd(), ['-s', id, 'shell', 'dumpsys', kind, ...(kind === 'window' ? ['policy'] : [])], timeout);
+        remainingBudget();
+        if (result.exitCode !== 0)
+            throw new Error('PROBE_FAILED');
+        const value = kind === 'power' ? parseAndroidPower(result.stdout) : parseAndroidLock(result.stdout);
+        if (kind === 'power')
+            state.wakefulness = value;
+        else
+            state.lock_state = value;
+        if (value === 'unknown')
+            state.limitations.push(kind === 'power' ? 'DEVICE_WAKEFULNESS_UNVERIFIED' : 'DEVICE_LOCK_STATE_UNVERIFIED');
+        else
+            state.evidence.push({ code: `DEVICE_${value.toUpperCase()}`, source: `android_${kind}`, captured_at_ms: Date.now() });
+    }
+    catch {
+        state.limitations.push(kind === 'power' ? 'DEVICE_POWER_OBSERVATION_FAILED' : 'DEVICE_LOCK_OBSERVATION_FAILED');
+    }
+}

package/dist/observe/evidence.js

@@ -217,11 +217,21 @@ export function refreshJourneyEvidence(steps) {
         const child = current.children.find(c => c.action?.id === previous?.action_id);
         if (child && step.result)
             step.result.evidence = assemble(child);
+        else if (previous?.observations && step.result) {
+            const ids = new Set(previous.observations.map(o => o.evidence_id));
+            step.result.evidence = assemble({ ...current, observations: current.observations.filter(o => ids.has(o.value.evidence_id)) });
+        }
     }
 }
 export function completeJourneyVerification(actionId) {
     const child = context.getStore()?.children.find(c => c.action?.id === actionId);
     if (child?.action) {
+        const parent = context.getStore();
+        const completed = child.action.dispatchEnd?.mono;
+        if (completed !== undefined) {
+            const after = parent.observations.filter(o => o.start.mono >= completed && sameDevice(o.value.device, child.action.device));
+            child.observations.push(...after);
+        }
         child.verification = stamp();
         child.action.verification = child.verification;
     }
@@ -317,3 +327,24 @@ function recordCaptureTime(acquisition, result, start) {
         acquisition.reused = source < start.wall;
     }
 }
+export class JourneyStepError extends Error {
+    evidence;
+    constructor(evidence, cause) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+        this.evidence = evidence;
+    }
+}
+/** Retain per-step evidence without changing the parent journey's acquisition flow. */
+export async function withJourneyStepEvidence(operation) {
+    const current = context.getStore();
+    const start = current?.observations.length ?? 0;
+    try {
+        const result = await operation();
+        return { ...result, ...(current ? { evidence: assemble({ ...current, observations: current.observations.slice(start) }) } : {}) };
+    }
+    catch (error) {
+        if (current)
+            throw new JourneyStepError(assemble({ ...current, observations: current.observations.slice(start) }), error);
+        throw error;
+    }
+}

package/dist/observe/ios-trace/sessions.js

@@ -163,11 +163,13 @@ export class IosTraceSessions {
         catch (error) {
             this.fail(s, reasonFor(error, s.recording?.recorder.alive() ? 'TRACE_STOP_FAILED' : 'TRACE_ARTIFACT_FAILED'));
             s.result.cleanup.status = 'failed';
-            if (s.result.reason === 'STORAGE_LIMIT' && !s.recording?.recorder.alive())
-                await this.discardOversized(s);
+            // Stop timeouts can throw after SIGKILL has already closed the recorder.
+            // Discarding is safe only after exit; keep the failure but release owned files.
+            if ((s.discard || s.result.reason === 'STORAGE_LIMIT') && !s.recording?.recorder.alive())
+                await this.discardStoppedFiles(s);
         }
     }
-    async discardOversized(s) {
+    async discardStoppedFiles(s) {
         try {
             if (s.directory)
                 await fs.rm(s.directory, { recursive: true, force: true });

package/dist/observe/readiness-service.js

@@ -1,3 +1,4 @@
+import { unknownDeviceReadiness, observeDeviceReadiness } from './device-readiness.js';
 import { pausedReadiness } from '../debugger/guard.js';
 import { resolveTargetDevice, withResolvedDevice } from '../utils/resolve-device.js';
 import { remainingBudget, runWithBudget } from '../utils/operation-budget.js';
@@ -28,10 +29,14 @@ export async function readinessDelay(ms) {
     await new Promise(resolve => setTimeout(resolve, Math.min(ms, remainingBudget(ms))));
     remainingBudget();
 }
+function observationComplete(tracker, wait, count) {
+    return tracker.ready || (!wait && (tracker.summary.state === 'loading' || count === 2));
+}
 export async function getAppReadiness(args, wait = false) {
     const started = performance.now();
     let device = null;
     let tracker = new ReadinessTracker(args.platform ?? 'android', args.deviceId ?? '');
+    tracker.deviceReadiness = unknownDeviceReadiness('DEVICE_TARGET_UNAVAILABLE');
     let failureCode;
     let debugPause = null;
     await runWithBudget(args.timeoutMs ?? (wait ? 30000 : 15000), async () => {
@@ -45,9 +50,17 @@ export async function getAppReadiness(args, wait = false) {
                     remainingBudget();
                     debugPause = pausedReadiness(device.id, device.platform);
                     if (debugPause) {
+                        tracker.deviceReadiness = await observeDeviceReadiness(device);
                         failureCode = wait ? 'DEBUGGER_PAUSED' : undefined;
                         return;
                     }
+                    await tracker.observeDevice();
+                    if (tracker.deviceReadiness.input_ready === false) {
+                        if (!wait)
+                            return;
+                        await readinessDelay(args.pollIntervalMs ?? 500);
+                        continue;
+                    }
                     const captureStarted = Date.now();
                     try {
                         const tree = await ToolsObserve.getUITreeHandler({ platform: device.platform, deviceId: device.id });
@@ -68,9 +81,7 @@ export async function getAppReadiness(args, wait = false) {
                         }
                     }
                     count++;
-                    if (tracker.summary.state === 'settled' || (!wait && tracker.summary.state === 'loading'))
-                        return;
-                    if (!wait && count === 2)
+                    if (observationComplete(tracker, wait, count))
                         return;
                     await readinessDelay(wait ? args.pollIntervalMs ?? 500 : args.stabilityMs ?? 500);
                 }
@@ -86,17 +97,18 @@ export async function getAppReadiness(args, wait = false) {
         }
     });
     if (debugPause)
-        return { success: !wait, device, readiness: debugPause, elapsed_ms: performance.now() - started, ...(wait ? { failure_code: 'DEBUGGER_PAUSED' } : {}) };
+        return { success: !wait, device, readiness: debugPause, device_readiness: tracker.deviceReadiness, elapsed_ms: performance.now() - started, ...(wait ? { failure_code: 'DEBUGGER_PAUSED' } : {}) };
     const state = tracker.summary.state;
-    const success = !failureCode && (wait ? state === 'settled' : state !== 'unknown');
+    const success = !failureCode && (wait ? tracker.ready : state !== 'unknown' || tracker.deviceReadiness.input_ready === false);
     return {
-        success, device, readiness: tracker.summary, elapsed_ms: performance.now() - started,
+        success, device, readiness: tracker.summary, device_readiness: tracker.deviceReadiness, elapsed_ms: performance.now() - started,
         ...(!success ? { failure_code: failureCode ?? (wait ? 'READINESS_TIMEOUT' : 'READINESS_UNAVAILABLE') } : {})
     };
 }
 export async function withReadyWait(target, timeoutMs, operation, failure) {
     const started = performance.now();
     let tracker = new ReadinessTracker(target.platform ?? 'android', target.deviceId ?? '');
+    tracker.deviceReadiness = unknownDeviceReadiness('DEVICE_TARGET_UNAVAILABLE');
     let resolved = false;
     return runWithBudget(timeoutMs, async () => {
         try {
@@ -110,9 +122,9 @@ export async function withReadyWait(target, timeoutMs, operation, failure) {
             }
             catch {
                 const alreadyFailed = result && (('status' in result && result.status !== 'success') || ('success' in result && result.success === false));
-                return { ...(alreadyFailed ? result : failure('TIMEOUT', performance.now() - started, tracker.summary.sample_count)), readiness: tracker.deadline() };
+                return { ...(alreadyFailed ? result : failure('TIMEOUT', performance.now() - started, tracker.summary.sample_count)), readiness: tracker.deadline(), device_readiness: tracker.deviceReadiness };
             }
-            return { ...result, readiness: tracker.summary };
+            return { ...result, readiness: tracker.summary, device_readiness: tracker.deviceReadiness };
         }
         catch (error) {
             const expired = budgetExpired(error);
@@ -120,7 +132,7 @@ export async function withReadyWait(target, timeoutMs, operation, failure) {
                 tracker.deadline();
             else
                 tracker.unavailable();
-            return { ...failure(!expired && (!resolved || isDeviceUnavailable(error)) ? 'DEVICE_UNAVAILABLE' : 'TIMEOUT', performance.now() - started, tracker.summary.sample_count), readiness: tracker.summary };
+            return { ...failure(!expired && (!resolved || isDeviceUnavailable(error)) ? 'DEVICE_UNAVAILABLE' : 'TIMEOUT', performance.now() - started, tracker.summary.sample_count), readiness: tracker.summary, device_readiness: tracker.deviceReadiness };
         }
     });
 }

package/dist/observe/readiness.js

@@ -1,3 +1,4 @@
+import { unknownDeviceReadiness, observeDeviceReadiness, finishDeviceReadiness } from './device-readiness.js';
 import { pausedReadiness } from '../debugger/guard.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { remainingBudget } from '../utils/operation-budget.js';
@@ -7,10 +8,38 @@ const capabilities = { loading: true, transitioning: true, settled: true, unresp
 export function isDeviceUnavailable(error) {
     return /device.*(?:not found|offline|disconnected)|no devices found|READINESS_DEVICE_UNAVAILABLE/i.test(String(error));
 }
+function retainBlockedEvidence(previous, next) {
+    const retained = [];
+    if (['unknown', 'unsupported'].includes(next.wakefulness) && ['asleep', 'transitioning'].includes(previous.wakefulness)) {
+        next.wakefulness = previous.wakefulness;
+        retained.push('DEVICE_ASLEEP', 'DEVICE_TRANSITIONING');
+    }
+    if (['unknown', 'unsupported'].includes(next.lock_state) && previous.lock_state === 'locked') {
+        next.lock_state = previous.lock_state;
+        retained.push('DEVICE_LOCKED');
+    }
+    if (retained.length) {
+        next.evidence = [...previous.evidence.filter(item => retained.includes(item.code)), ...next.evidence].slice(-8);
+        next.limitations = [...new Set([...next.limitations, 'DEVICE_BLOCKER_EVIDENCE_RETAINED'])];
+    }
+    return finishDeviceReadiness(next);
+}
 export class ReadinessTracker {
     platform;
     deviceId;
     stabilityMs;
+    deviceReadiness = unknownDeviceReadiness();
+    get ready() { return this.summary.state === 'settled' && this.deviceReadiness.input_ready !== false; }
+    async observeDevice() {
+        const next = await observeDeviceReadiness({ platform: this.platform, id: this.deviceId });
+        this.deviceReadiness = retainBlockedEvidence(this.deviceReadiness, next);
+        if (this.deviceReadiness.input_ready === false) {
+            this.signature = null;
+            this.stableSince = 0;
+            this.summary = { ...this.summary, state: 'unknown', basis: 'insufficient', stable_for_ms: 0,
+                limitations: [...new Set([...this.summary.limitations, 'DEVICE_BLOCKED'])] };
+        }
+    }
     signature = null;
     stableSince = 0;
     summary;
@@ -105,3 +134,4 @@ function readinessState(loading, previous, unchanged, stableFor, stabilityMs) {
 function readinessCode(nativeLoading, textLoading, state) {
     return nativeLoading ? 'NATIVE_LOADING_INDICATOR' : textLoading ? 'LOADING_LABEL' : state === 'transitioning' ? 'SNAPSHOT_CHANGED' : state === 'settled' ? 'SNAPSHOT_STABLE' : 'INSUFFICIENT_SAMPLES';
 }
+export async function observeReadinessDeviceWait() { await waits.getStore()?.observeDevice(); }

package/dist/observe/screenshot-encoding.js

@@ -1,3 +1,4 @@
+import { benchmarkStage } from '../utils/benchmark-metrics.js';
 async function convert(buffer, platform) {
     const { default: sharp } = await import('sharp');
     const image = sharp(buffer);
@@ -22,6 +23,9 @@ async function convert(buffer, platform) {
     return { hasAlpha, webp, jpeg };
 }
 export async function encodeScreenshot(buffer, platform) {
+    return benchmarkStage('screenshot_encoding_ms', () => encode(buffer, platform));
+}
+async function encode(buffer, platform) {
     const png = buffer.toString('base64');
     try {
         const { hasAlpha, webp, jpeg } = await convert(buffer, platform);

package/dist/observe/snapshot-collection.js

@@ -3,6 +3,7 @@ import { measure } from '../utils/timing.js';
 import { deriveSnapshotMetadata } from './snapshot-metadata.js';
 import { deriveSnapshotSemantic } from './snapshot-semantic.js';
 import { snapshotLog, streamLog } from './snapshot-logs.js';
+import { collectGetScreenFingerprint } from './android/fingerprint.js';
 async function settle(tasks) {
     const results = await Promise.allSettled(Object.values(tasks));
     return Object.fromEntries(Object.keys(tasks).map((key, index) => [key, results[index]]));
@@ -15,11 +16,15 @@ function apply(result, success, failure) {
 }
 async function collect(raw, input, deps) {
     const { platform, deviceId, includeScreenshot = true, includeLogs = true, sessionId, logLines = 200 } = input;
+    const androidTree = platform === 'android' ? deps.getUITreeHandler({ platform, deviceId }) : undefined;
     const results = await settle({
         screenshot: includeScreenshot ? measure('screenshot_ms', () => deps.captureScreenshotHandler({ platform, deviceId })) : Promise.resolve(null),
         currentScreen: !platform || platform === 'android' ? deps.getCurrentScreenHandler({ deviceId }) : Promise.resolve(null),
-        fingerprint: deps.getScreenFingerprintHandler({ platform, deviceId }),
-        uiTree: deps.getUITreeHandler({ platform, deviceId }),
+        fingerprint: androidTree ? collectGetScreenFingerprint({
+            getUITree: () => androidTree,
+            getCurrentScreen: id => deps.getCurrentScreenHandler({ deviceId: id })
+        }, deviceId) : deps.getScreenFingerprintHandler({ platform, deviceId }),
+        uiTree: androidTree ?? deps.getUITreeHandler({ platform, deviceId }),
         readLogStream: includeLogs ? deps.readLogStreamHandler({ platform, deviceId, sessionId: sessionId || 'default', limit: logLines }) : Promise.resolve({ entries: [] })
     });
     let entries = [];