mobile-debug-mcp 0.35.0 → 0.37.0

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

@@ -0,0 +1,93 @@
+import { promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { getXcrunCmd } from '../../utils/ios/utils.js';
+import { iosCapabilities, resolveIosApp } from './capabilities.js';
+import { prepareNotification, listenNotification } from './notification.js';
+import { spawnTrace, stopTraceChild, classifyTraceFailure } from './process.js';
+import { traceSize, validateArtifact, IOS_TRACE_MAX_BYTES } from './artifact.js';
+export class IosTraceNative {
+    spawn;
+    children = new Set();
+    recorders = new Set();
+    closing = false;
+    constructor(spawn = spawnTrace) {
+        this.spawn = (command, args, timeout) => {
+            if (this.closing)
+                throw new Error('TRACE_BUSY');
+            const child = spawn(command, args, timeout);
+            this.children.add(child);
+            if (args.includes('xctrace') && args.includes('record'))
+                this.recorders.add(child);
+            void child.done.then(() => { this.children.delete(child); this.recorders.delete(child); });
+            return child;
+        };
+    }
+    shutdown() {
+        this.closing = true;
+        for (const child of this.children)
+            child.signal('SIGINT');
+        const helpers = setTimeout(() => { for (const child of this.children)
+            if (!this.recorders.has(child))
+                child.signal('SIGKILL'); }, 1000);
+        const recorders = setTimeout(() => { for (const child of this.recorders)
+            child.signal('SIGKILL'); }, 8000);
+        helpers.unref();
+        recorders.unref();
+    }
+    capabilities(device, appId, template) { return iosCapabilities(device, appId, template, this.spawn); }
+    resolve(device, app) { return resolveIosApp(device, app, this.spawn); }
+    async storage(directory) {
+        const stat = await fs.statfs(directory);
+        if (stat.bavail * stat.bsize < 1024 * 1024 * 1024)
+            throw new Error('STORAGE_LIMIT');
+    }
+    async start(device, app, directory, duration, own) {
+        await this.storage(directory);
+        const binary = await prepareNotification(directory, this.spawn);
+        return this.startRecorder(device, app, directory, duration, binary, own);
+    }
+    async startRecorder(device, app, directory, duration, binary, own) {
+        const name = 'tools.mobiledebug.trace.' + randomUUID();
+        const listener = await listenNotification(binary, name, this.spawn);
+        let recording;
+        try {
+            const current = await this.resolve(device, app.app_id);
+            if (current.pid !== app.pid || current.executable !== app.executable || current.started_at !== app.started_at)
+                throw new Error('APP_IDENTITY_CHANGED');
+            const file = path.join(directory, 'capture.trace');
+            const recorder = this.spawn(getXcrunCmd(), ['xctrace', 'record', '--template', 'Time Profiler', '--device', device,
+                '--attach', String(app.pid), '--time-limit', `${duration}ms`, '--output', file, '--notify-tracing-started', name], duration + 65000);
+            recording = { recorder, file, ready_at_ms: 0 };
+            own(recording);
+            await Promise.race([listener.line('READY', 35000), recorder.done.then(result => { throw new Error(classifyTraceFailure(result)); })]);
+            if (!recorder.alive())
+                throw new Error('RECORDER_EXITED');
+            recording.ready_at_ms = Date.now();
+            return recording;
+        }
+        catch (error) {
+            if (recording)
+                await stopTraceChild(recording.recorder).catch(() => { });
+            throw error;
+        }
+        finally {
+            await stopTraceChild(listener, 1000).catch(() => { });
+        }
+    }
+    stop(recording, timeout) { return stopTraceChild(recording.recorder, timeout); }
+    async monitor(device, app, recording) {
+        const current = await this.resolve(device, app.app_id);
+        if (current.pid !== app.pid || current.executable !== app.executable || current.started_at !== app.started_at)
+            throw new Error('APP_IDENTITY_CHANGED');
+        try {
+            if (await traceSize(recording.file) > IOS_TRACE_MAX_BYTES)
+                throw new Error('STORAGE_LIMIT');
+        }
+        catch (error) {
+            if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+                throw error;
+        }
+    }
+    validate(recording, device, app) { return validateArtifact(recording.file, device, app, this.spawn); }
+}

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

@@ -0,0 +1,35 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { getXcrunCmd } from '../../utils/ios/utils.js';
+import { traceCommand, spawnTrace, stopTraceChild } from './process.js';
+// A private per-session listener avoids requiring a third-party notification utility.
+const source = `#include <notify.h>
+#include <dispatch/dispatch.h>
+#include <stdio.h>
+#include <stdlib.h>
+int main(int argc, char **argv) {
+  if (argc != 2) return 2;
+  int token;
+  if (notify_register_dispatch(argv[1], &token, dispatch_get_main_queue(), ^(int t) {
+    puts("READY"); fflush(stdout); notify_cancel(t); exit(0);
+  }) != NOTIFY_STATUS_OK) return 3;
+  puts("ARMED"); fflush(stdout); dispatch_main();
+}`;
+export async function prepareNotification(directory, spawn = spawnTrace) {
+    const file = path.join(directory, 'notification.c'), binary = path.join(directory, 'notification');
+    await fs.writeFile(file, source, { mode: 0o600 });
+    await traceCommand(getXcrunCmd(), ['clang', '-fblocks', file, '-o', binary], 30000, spawn);
+    await fs.chmod(binary, 0o700);
+    return binary;
+}
+export async function listenNotification(binary, name, spawn = spawnTrace) {
+    const listener = spawn(binary, [name], 40000);
+    try {
+        await listener.line('ARMED', 5000);
+        return listener;
+    }
+    catch (error) {
+        await stopTraceChild(listener, 1000).catch(() => { });
+        throw error;
+    }
+}

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

@@ -0,0 +1,98 @@
+import { spawn } from 'node:child_process';
+const MAX_OUTPUT = 64 * 1024;
+export const spawnTrace = (command, args, timeout) => {
+    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let output = '', settled = false, timedOut = false;
+    const waiters = new Set();
+    let force;
+    const terminate = () => {
+        if (settled)
+            return;
+        child.kill('SIGTERM');
+        force ??= setTimeout(() => { if (!settled)
+            child.kill('SIGKILL'); }, 1000);
+        force.unref();
+    };
+    const timer = setTimeout(() => { timedOut = true; terminate(); }, timeout);
+    timer.unref();
+    const done = new Promise(resolve => {
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (force)
+                clearTimeout(force);
+            for (const wake of waiters)
+                wake();
+            resolve({ code, output, timedOut });
+        };
+        child.on('error', () => finish(null));
+        child.on('close', finish);
+        const data = (chunk) => {
+            output = (output + chunk.toString()).slice(-MAX_OUTPUT);
+            for (const wake of waiters)
+                wake();
+        };
+        child.stdout?.on('data', data);
+        child.stderr?.on('data', data);
+    });
+    return {
+        done, alive: () => !settled && child.exitCode === null && child.signalCode === null,
+        signal: signal => { if (!settled)
+            child.kill(signal); },
+        line: (text, ms) => new Promise((resolve, reject) => {
+            const deadline = setTimeout(() => { waiters.delete(check); reject(new Error('READINESS_TIMEOUT')); }, ms);
+            const check = () => {
+                if (output.split(/\r?\n/).includes(text)) {
+                    clearTimeout(deadline);
+                    waiters.delete(check);
+                    resolve();
+                }
+                else if (settled) {
+                    clearTimeout(deadline);
+                    waiters.delete(check);
+                    reject(new Error('RECORDER_EXITED'));
+                }
+            };
+            waiters.add(check);
+            check();
+        })
+    };
+};
+export async function traceCommand(command, args, timeout = 10000, spawn = spawnTrace) {
+    const result = await spawn(command, args, timeout).done;
+    if (result.code !== 0 || result.timedOut)
+        throw new Error(result.timedOut ? 'ACTION_TIMEOUT' : 'COMMAND_FAILED');
+    return result.output.trim();
+}
+export async function stopTraceChild(child, timeout = 30000) {
+    if (child.alive())
+        child.signal('SIGINT');
+    let timer;
+    const result = await Promise.race([
+        child.done,
+        new Promise(resolve => { timer = setTimeout(() => resolve(null), timeout); })
+    ]);
+    if (timer)
+        clearTimeout(timer);
+    if (result)
+        return result;
+    child.signal('SIGKILL');
+    let forceTimer;
+    await Promise.race([child.done, new Promise(resolve => { forceTimer = setTimeout(resolve, 1000); })]);
+    if (forceTimer)
+        clearTimeout(forceTimer);
+    throw new Error('ACTION_TIMEOUT');
+}
+export function classifyTraceFailure(result) {
+    if (result.timedOut)
+        return 'ACTION_TIMEOUT';
+    if (/permission|not permitted|authoriz|privacy|access denied/i.test(result.output))
+        return 'PROFILING_PERMISSION_REQUIRED';
+    if (/cannot find process|process.*not.*found/i.test(result.output))
+        return 'APP_NOT_RUNNING';
+    if (/disconnect|device.*unavailable/i.test(result.output))
+        return 'TARGET_DISCONNECTED';
+    return 'RECORDER_EXITED';
+}

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

@@ -0,0 +1,246 @@
+import { classifyTraceFailure } from './process.js';
+import { TraceError } from '../system-trace-error.js';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { evidenceSessionId } from '../evidence.js';
+import { IosTraceNative } from './native.js';
+const reasonFor = (error, fallback) => {
+    const code = error instanceof Error ? error.message : '';
+    return ['STORAGE_LIMIT', 'APP_IDENTITY_CHANGED', 'ACTION_TIMEOUT', 'READINESS_TIMEOUT', 'RECORDER_EXITED', 'PROFILING_PERMISSION_REQUIRED', 'APP_NOT_RUNNING', 'TARGET_DISCONNECTED'].includes(code) ? code : fallback;
+};
+export class IosTraceSessions {
+    native;
+    time;
+    sessions = new Map();
+    closing = false;
+    constructor(native = new IosTraceNative(), time = {
+        wall: Date.now, mono: () => performance.now(), sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+        schedule: (fn, ms) => { const timer = setTimeout(fn, ms); timer.unref(); return timer; }, clear: clearTimeout
+    }) {
+        this.native = native;
+        this.time = time;
+    }
+    get(id) {
+        this.prune();
+        const s = this.sessions.get(id);
+        if (!s)
+            throw new TraceError('TRACE_NOT_FOUND');
+        return s;
+    }
+    prune() {
+        const terminal = [...this.sessions.values()].filter(s => s.terminal !== undefined && s.result.cleanup.status === 'complete');
+        for (const [index, s] of terminal.entries())
+            if (this.time.mono() - s.terminal >= 600000 || index < terminal.length - 100)
+                this.sessions.delete(s.result.trace_id);
+    }
+    serial(s, fn) {
+        const promise = s.queue.then(fn);
+        s.queue = promise.catch(() => { });
+        return promise;
+    }
+    snapshot(s) { return structuredClone(s.result); }
+    fail(s, reason) {
+        s.result.state = 'failed';
+        s.result.reason = reason;
+        s.result.completion_reason = 'error';
+        s.result.recovery = reason === 'PROFILING_PERMISSION_REQUIRED' ? 'Grant the required profiling permission through the macOS or Xcode UI, then explicitly start a new capture.' : reason === 'TRACE_ARTIFACT_FAILED' ? 'Retry stop to validate the finalised owned artifact, or cancel to discard.' : 'Check target, app and profiling permissions; cancel the owned session before retrying start.';
+        for (const id of s.linked)
+            s.partial.add(id);
+    }
+    async start(device, appId, duration = 30000) {
+        this.prune();
+        const active = [...this.sessions.values()].filter(s => s.result.cleanup.status !== 'complete');
+        if (this.closing || active.length >= 4 || active.some(s => s.result.device.id === device.id))
+            throw new TraceError('TRACE_BUSY');
+        if (!Number.isInteger(duration) || duration < 1000 || duration > 120000)
+            throw new TraceError('INVALID_ARGUMENT');
+        const result = {
+            trace_id: randomUUID(), session_id: evidenceSessionId(), device: structuredClone(device), backend: 'xctrace', state: 'starting',
+            reason: null, recovery: null, completion_reason: null, capture_started_at_ms: null, capture_completed_at_ms: null,
+            recording_ready_at_ms: null, app_id: appId, pid: null, executable: null, template: 'Time Profiler', artifact: null,
+            cleanup: { status: 'pending', remaining_resources: [] }, warnings: [], correlation_ids: [], clock_alignment: 'unknown'
+        };
+        const s = { result, deadline: Infinity, discard: false, queue: Promise.resolve(), linked: new Set(), partial: new Set() };
+        this.sessions.set(result.trace_id, s);
+        return this.serial(s, async () => {
+            try {
+                s.directory = await fs.mkdtemp(path.join(os.tmpdir(), 'mobile-debug-ios-trace-'));
+                await fs.chmod(s.directory, 0o700);
+                s.result.cleanup.remaining_resources = [s.directory];
+                s.app = await this.native.resolve(device.id, appId);
+                s.result.pid = s.app.pid;
+                s.result.executable = s.app.executable;
+                if (this.closing)
+                    throw new TraceError('TRACE_BUSY');
+                s.result.capture_started_at_ms = this.time.wall();
+                s.deadline = Infinity;
+                s.recording = await this.native.start(device.id, s.app, s.directory, duration, recording => { s.recording = recording; if (this.closing)
+                    recording.recorder.signal('SIGINT'); });
+                if (this.closing)
+                    throw new Error('READINESS_TIMEOUT');
+                s.deadline = this.time.mono() + duration;
+                s.result.recording_ready_at_ms = s.recording.ready_at_ms;
+                s.result.state = 'recording';
+                this.schedule(s);
+                void s.recording.recorder.done.then(() => this.control(result.trace_id, 'status')).catch(() => { });
+            }
+            catch (error) {
+                this.fail(s, reasonFor(error, 'TRACE_START_FAILED'));
+                s.discard = true;
+                await this.finalise(s, 'cancel', true);
+            }
+            return this.snapshot(s);
+        });
+    }
+    schedule(s) {
+        if (s.result.state !== 'recording')
+            return;
+        s.timer = this.time.schedule(() => {
+            void this.serial(s, () => this.poll(s)).finally(() => this.schedule(s)).catch(() => { });
+        }, 1000);
+    }
+    async poll(s) {
+        if (s.result.state !== 'recording' || !s.recording || !s.app)
+            return;
+        try {
+            await this.native.monitor(s.result.device.id, s.app, s.recording);
+            s.monitorFailures = 0;
+        }
+        catch (error) {
+            const reason = error instanceof Error && error.message === 'COMMAND_FAILED'
+                ? 'COMMAND_FAILED' : reasonFor(error, 'TRACE_MONITOR_FAILED');
+            const definitive = ['STORAGE_LIMIT', 'APP_IDENTITY_CHANGED', 'APP_NOT_RUNNING'].includes(reason);
+            s.monitorFailures = (s.monitorFailures ?? 0) + 1;
+            if (definitive || s.monitorFailures >= 3) {
+                this.fail(s, reason);
+                s.discard = true;
+                await this.finalise(s, 'cancel', true);
+                return;
+            }
+        }
+        if (this.time.mono() >= s.deadline || !s.recording.recorder.alive())
+            await this.finalise(s, 'duration');
+    }
+    async control(id, op, timeout) {
+        const s = this.get(id);
+        return this.serial(s, async () => {
+            if (s.result.cleanup.status === 'complete')
+                return this.snapshot(s);
+            if (op === 'status' && s.result.state === 'recording' && s.recording?.recorder.alive() && this.time.mono() < s.deadline) {
+                await this.poll(s);
+                return this.snapshot(s);
+            }
+            await this.finalise(s, op === 'status' ? 'duration' : op, false, timeout);
+            return this.snapshot(s);
+        });
+    }
+    async finalise(s, op, preserveFailure = false, timeout) {
+        if (s.timer) {
+            this.time.clear(s.timer);
+            s.timer = undefined;
+        }
+        if (op === 'cancel')
+            s.discard = true;
+        if (!preserveFailure)
+            s.result.state = 'stopping';
+        for (const id of s.linked)
+            s.partial.add(id);
+        try {
+            await this.finishRecorder(s, op, timeout);
+            s.result.capture_completed_at_ms ??= this.time.wall();
+            await this.finishArtifact(s);
+            s.result.cleanup = { status: 'complete', remaining_resources: [] };
+            s.terminal = this.time.mono();
+            if (!preserveFailure) {
+                s.result.state = s.discard ? 'cancelled' : 'completed';
+                s.result.reason = s.discard ? 'TRACE_CANCELLED' : null;
+                s.result.recovery = null;
+                s.result.completion_reason = s.discard ? 'cancelled' : op === 'duration' ? 'duration_limit' : 'requested';
+            }
+        }
+        catch (error) {
+            this.fail(s, reasonFor(error, s.recording?.recorder.alive() ? 'TRACE_STOP_FAILED' : 'TRACE_ARTIFACT_FAILED'));
+            s.result.cleanup.status = 'failed';
+            // 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 discardStoppedFiles(s) {
+        try {
+            if (s.directory)
+                await fs.rm(s.directory, { recursive: true, force: true });
+            s.result.cleanup = { status: 'complete', remaining_resources: [] };
+            s.terminal = this.time.mono();
+        }
+        catch { /* retain failed cleanup and owned path for cancel retry */ }
+    }
+    async finishRecorder(s, op, timeout) {
+        if (!s.recording || s.recorderOk !== undefined)
+            return;
+        const ended = await this.native.stop(s.recording, timeout);
+        s.recorderOk = ended.code === 0 && !ended.timedOut;
+        if (ended.output.includes('[Warning]'))
+            s.result.warnings = ['INSTRUMENTS_RUN_WARNING: one or more Instruments warnings; coverage may be incomplete.'];
+        if (!s.recorderOk && !s.discard)
+            throw new Error(classifyTraceFailure(ended));
+        if (op === 'duration' && !ended.output.includes('Reached specified time limit') && this.time.mono() < s.deadline && !s.discard)
+            throw new Error('RECORDER_EXITED');
+    }
+    async finishArtifact(s) {
+        if (!s.discard && !s.result.artifact) {
+            if (!s.recording || !s.app || !s.recorderOk)
+                throw new Error('RECORDER_EXITED');
+            s.result.artifact = await this.native.validate(s.recording, s.result.device.id, s.app);
+        }
+        if (s.discard && s.directory)
+            await fs.rm(s.directory, { recursive: true, force: true });
+        else if (s.directory)
+            await Promise.all(['notification', 'notification.c'].map(p => fs.rm(path.join(s.directory, p), { force: true })));
+    }
+    async link(id, device, correlation) {
+        const s = this.get(id);
+        if (device.platform !== 'ios' || device.id !== s.result.device.id)
+            throw new TraceError('TRACE_NOT_FOUND');
+        const status = await this.control(id, 'status');
+        if (status.state !== 'recording')
+            throw new TraceError('TRACE_NOT_FOUND');
+        return this.serial(s, async () => {
+            if (s.result.state !== 'recording' || !s.recording?.recorder.alive() || this.time.mono() >= s.deadline)
+                throw new TraceError('TRACE_NOT_FOUND');
+            if (!s.result.correlation_ids.includes(correlation)) {
+                if (s.result.correlation_ids.length >= 1000)
+                    throw new TraceError('TRACE_BUSY');
+                s.result.correlation_ids.push(correlation);
+            }
+            s.linked.add(correlation);
+            let finished;
+            return () => finished ??= (async () => {
+                let active = false;
+                try {
+                    active = (await this.control(id, 'status')).state === 'recording';
+                }
+                catch { /* unknown is partial */ }
+                s.linked.delete(correlation);
+                return { trace_id: id, coverage: !active || s.partial.has(correlation) ? 'partial' : 'covered', clock_alignment: 'unknown' };
+            })();
+        });
+    }
+    async shutdown() {
+        this.closing = true;
+        this.native.shutdown();
+        const active = [...this.sessions.values()].filter(s => s.result.cleanup.status !== 'complete');
+        // Signal immediately even when an in-flight start/validation owns the serial queue.
+        for (const s of active)
+            s.recording?.recorder.signal('SIGINT');
+        let timer;
+        await Promise.race([Promise.allSettled(active.map(s => this.control(s.result.trace_id, 'cancel', 8000))),
+            new Promise(resolve => { timer = setTimeout(resolve, 9000); })]);
+        if (timer)
+            clearTimeout(timer);
+        return active.filter(s => s.result.cleanup.status !== 'complete').map(s => this.snapshot(s));
+    }
+}

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 () => {
@@ -43,11 +48,19 @@ export async function getAppReadiness(args, wait = false) {
                 let count = 0;
                 while (wait || count < 2) {
                     remainingBudget();
-                    debugPause = device.platform === 'android' ? pausedReadiness(device.id) : null;
+                    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;
@@ -21,14 +50,14 @@ export class ReadinessTracker {
         this.summary = {
             state: 'unknown', scope: 'device_ui', basis: 'insufficient', captured_at_ms: null,
             sample_count: 0, stable_for_ms: 0, snapshot_session_id: null, snapshot_revision: null,
-            evidence: [], limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', 'INSUFFICIENT_SAMPLES'], capabilities: { ...capabilities, debugger_paused: this.platform === 'android' }
+            evidence: [], limitations: [...baselineLimitations, ['android', 'ios'].includes(this.platform) ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', 'INSUFFICIENT_SAMPLES'], capabilities: { ...capabilities, debugger_paused: ['android', 'ios'].includes(this.platform) }
         };
     }
     unavailable(code = 'OBSERVATION_FAILED') {
         this.signature = null;
         this.summary = {
             ...this.summary, state: 'unknown', basis: 'insufficient', stable_for_ms: 0,
-            sample_count: this.summary.sample_count + 1, limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', code],
+            sample_count: this.summary.sample_count + 1, limitations: [...baselineLimitations, ['android', 'ios'].includes(this.platform) ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', code],
             evidence: [...this.summary.evidence, { code, source: 'ui_tree', captured_at_ms: null, snapshot_revision: null }].slice(-8)
         };
         return this.summary;
@@ -38,7 +67,7 @@ export class ReadinessTracker {
         return this.summary;
     }
     observe(sample, acquisitionStartedAtMs, now = performance.now()) {
-        const paused = this.platform === 'android' ? pausedReadiness(this.deviceId) : null;
+        const paused = pausedReadiness(this.deviceId, this.platform);
         if (paused) {
             this.summary = paused;
             return this.summary;
@@ -66,7 +95,7 @@ export class ReadinessTracker {
             captured_at_ms: tree.captured_at_ms, snapshot_session_id: tree.snapshot_session_id, snapshot_revision: tree.snapshot_revision,
             sample_count: this.summary.sample_count + 1, stable_for_ms: stableFor,
             evidence: [...this.summary.evidence, { code, source: 'ui_tree', captured_at_ms: tree.captured_at_ms, snapshot_revision: tree.snapshot_revision }].slice(-8),
-            limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', ...(state === 'unknown' ? ['INSUFFICIENT_SAMPLES'] : [])], capabilities: { ...capabilities, debugger_paused: this.platform === 'android' }
+            limitations: [...baselineLimitations, ['android', 'ios'].includes(this.platform) ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', ...(state === 'unknown' ? ['INSUFFICIENT_SAMPLES'] : [])], capabilities: { ...capabilities, debugger_paused: ['android', 'ios'].includes(this.platform) }
         };
         return this.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);