mobile-debug-mcp 0.32.4 → 0.34.0

package/dist/observe/evidence.js

@@ -0,0 +1,280 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+const sessionId = randomUUID();
+const context = new AsyncLocalStorage();
+const history = new Map();
+const active = new Map();
+const orders = new Map();
+const stamp = () => ({ wall: Date.now(), mono: performance.now() });
+const deviceKey = (d) => `${d.platform}:${d.id}`;
+const sameDevice = (a, b) => !!a && !!b && deviceKey(a) === deviceKey(b);
+function validDevice(d) {
+    return d && ['android', 'ios'].includes(d.platform) && typeof d.id === 'string' && d.id && !['default', 'booted'].includes(d.id)
+        ? { platform: d.platform, id: d.id } : null;
+}
+function orderFor(device) {
+    if (!device)
+        return null;
+    const key = deviceKey(device);
+    let order = orders.get(key);
+    if (!order) {
+        order = { sequence: 0, active: 0, lastStarted: -Infinity };
+        orders.set(key, order);
+        if (orders.size > 1000) {
+            for (const [oldKey, oldOrder] of orders) {
+                if (oldKey !== key && oldOrder.active === 0)
+                    orders.delete(oldKey);
+                if (orders.size <= 1000)
+                    break;
+            }
+        }
+    }
+    return order;
+}
+function prune() {
+    const now = performance.now();
+    for (const [key, record] of history) {
+        if (record.completed !== null && now - record.completed >= 600000)
+            history.delete(key);
+    }
+    while (history.size > 1000)
+        history.delete(history.keys().next().value);
+}
+export function validateActionRef(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value) ||
+        Object.keys(value).some(key => !['sessionId', 'actionId'].includes(key)))
+        throw new Error('INVALID_ARGUMENT: invalid actionRef');
+    const ref = value;
+    for (const v of [ref.sessionId, ref.actionId])
+        if (typeof v !== 'string' || v.length < 1 || v.length > 128)
+            throw new Error('INVALID_ARGUMENT: invalid actionRef');
+    return { sessionId: ref.sessionId, actionId: ref.actionId };
+}
+export function evidenceSessionId() { return sessionId; }
+export function currentEvidenceCorrelationId() { return context.getStore()?.correlationId; }
+export function bindSystemTrace(traceId) {
+    const current = context.getStore();
+    if (current)
+        current.systemTraceId = traceId;
+}
+export function currentEvidenceActionId() { return context.getStore()?.action?.id; }
+export function bindEvidenceDevice(device) {
+    const current = context.getStore();
+    const target = validDevice(device);
+    if (!current || !target)
+        return;
+    current.device ??= target;
+    if (current.isAction && current.action)
+        current.action.device ??= target;
+}
+export function markEvidenceVerification() {
+    const current = context.getStore();
+    if (current) {
+        current.verification = stamp();
+        if (current.isAction && current.action)
+            current.action.verification = current.verification;
+    }
+}
+export async function evidenceDispatch(device, operation) {
+    const current = context.getStore();
+    if (!current?.isAction || !current.action)
+        return operation();
+    bindEvidenceDevice(device);
+    const record = current.action;
+    const start = stamp();
+    record.dispatchStart ??= start;
+    record.dispatchEnd = null;
+    const order = orderFor(validDevice(device));
+    if (order) {
+        order.sequence++;
+        order.active++;
+        order.lastStarted = start.mono;
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        record.dispatchEnd = stamp();
+        if (order)
+            order.active--;
+    }
+}
+export function omitEvidence(kind) {
+    const current = context.getStore();
+    if (!current)
+        return;
+    const start = stamp();
+    current.observations.push({ value: {
+            evidence_id: randomUUID(), kind, status: 'omitted', capture_started_at_ms: null,
+            capture_completed_at_ms: null, source_captured_at_ms: null, age_ms: null,
+            freshness: kind === 'logs' ? 'not_applicable' : 'unknown', freshness_reasons: [], device: current.device
+        }, start, end: null, order: null, startSequence: 0, endSequence: 0, overlapping: false, reused: false });
+}
+export async function captureEvidence(kind, device, operation) {
+    const current = context.getStore();
+    if (!current)
+        return operation();
+    const target = validDevice(device);
+    if (target)
+        bindEvidenceDevice(target);
+    const order = orderFor(target);
+    const start = stamp();
+    const acquisition = { value: {
+            evidence_id: randomUUID(), kind, status: 'failed', capture_started_at_ms: start.wall,
+            capture_completed_at_ms: null, source_captured_at_ms: null, age_ms: null,
+            freshness: 'unknown', freshness_reasons: [], device: target
+        }, start, end: null, order, startSequence: order?.sequence ?? 0,
+        endSequence: 0, overlapping: !!order?.active, reused: false };
+    current.observations.push(acquisition);
+    try {
+        const result = await operation();
+        const value = acquisition.value;
+        const resolved = validDevice(result?.device) ?? target;
+        value.device = resolved;
+        if (resolved)
+            bindEvidenceDevice(resolved);
+        const failure = result?.error ?? result?.meta?.error;
+        value.status = failure || result?.success === false || (kind === 'fingerprint' && !result?.fingerprint) ? 'failed' : 'captured';
+        if (failure)
+            value.error = failure;
+        const source = result?.captured_at_ms;
+        if (Number.isFinite(source) && source > 0) {
+            value.source_captured_at_ms = source;
+            acquisition.reused = source < start.wall;
+        }
+        if (kind === 'ui_tree') {
+            value.snapshot_session_id = result?.snapshot_session_id;
+            value.snapshot_revision = result?.snapshot_revision;
+        }
+        if (kind === 'logs') {
+            const entries = result?.logs ?? result?.entries ?? [];
+            const times = entries.map((e) => {
+                const t = e?.timestamp ?? e?._iso;
+                return typeof t === 'number' ? t : typeof t === 'string' ? Date.parse(t) : NaN;
+            }).filter((t) => Number.isFinite(t));
+            value.clock = 'device_or_unknown';
+            value.event_time_comparable = false;
+            value.earliest_entry_at_ms = times.length ? times.reduce((a, b) => Math.min(a, b)) : null;
+            value.latest_entry_at_ms = times.length ? times.reduce((a, b) => Math.max(a, b)) : null;
+        }
+        return result;
+    }
+    catch (error) {
+        acquisition.value.error = error instanceof Error ? error.message : String(error);
+        throw error;
+    }
+    finally {
+        acquisition.end = stamp();
+        acquisition.value.capture_completed_at_ms = acquisition.end.wall;
+        acquisition.endSequence = order?.sequence ?? 0;
+        acquisition.overlapping ||= !!order?.active || acquisition.startSequence !== acquisition.endSequence;
+        if (acquisition.value.status === 'captured' && acquisition.value.source_captured_at_ms === null && kind !== 'logs') {
+            acquisition.value.source_captured_at_ms = acquisition.end.wall;
+        }
+    }
+}
+function association(current) {
+    if (current.isAction)
+        return { association: 'self', association_reason: null };
+    if (!current.ref)
+        return { association: 'none', association_reason: null };
+    const reason = current.ref.sessionId !== sessionId ? 'SESSION_MISMATCH' : !current.action ? 'ACTION_UNAVAILABLE' :
+        !sameDevice(current.device, current.action.device) ? 'DEVICE_MISMATCH' : null;
+    return { association: reason ? 'unavailable' : 'explicit', association_reason: reason };
+}
+function assemble(current) {
+    const end = stamp();
+    const link = association(current);
+    const action = link.association === 'unavailable' ? null : current.action;
+    const clockChanged = end.wall < current.start.wall;
+    const observations = current.observations.map(a => {
+        const v = { ...a.value, freshness_reasons: [] };
+        if (v.status === 'omitted')
+            return v;
+        const componentAction = sameDevice(v.device, action?.device ?? null) ? action : null;
+        const sourceMono = a.end && v.source_captured_at_ms !== null ? a.end.mono + v.source_captured_at_ms - a.end.wall : a.end?.mono;
+        const reason = (freshness, code) => { v.freshness = freshness; v.freshness_reasons.push(code); };
+        if (v.kind === 'logs')
+            reason('unknown', 'DEVICE_CLOCK_UNVERIFIED');
+        else if (clockChanged || (a.end && a.end.wall < a.start.wall))
+            reason('unknown', 'CLOCK_DISCONTINUITY');
+        else if (v.source_captured_at_ms !== null && a.end && v.source_captured_at_ms > a.end.wall)
+            reason('unknown', 'CLOCK_DISCONTINUITY');
+        else if (!v.device || !a.order || orders.get(deviceKey(v.device)) !== a.order || v.status !== 'captured' || !a.end)
+            reason('unknown', 'CAPTURE_TIME_UNKNOWN');
+        else if (componentAction?.dispatchStart && sourceMono !== undefined && sourceMono < componentAction.dispatchStart.mono)
+            reason('stale', 'BEFORE_ACTION');
+        else if (a.order && (a.order.sequence > a.endSequence || (a.reused && sourceMono !== undefined && sourceMono < a.order.lastStarted)))
+            reason('stale', 'SUPERSEDED_BY_ACTION');
+        else if (a.overlapping)
+            reason('unknown', 'OVERLAPPING_ACTION');
+        else if (a.reused)
+            reason('unknown', 'REUSED_OBSERVATION');
+        else {
+            v.freshness = 'fresh';
+        }
+        if (!clockChanged && a.end && a.end.wall >= a.start.wall && v.source_captured_at_ms !== null && v.source_captured_at_ms <= end.wall) {
+            v.age_ms = Math.max(0, end.mono - a.end.mono + a.end.wall - v.source_captured_at_ms);
+        }
+        return { ...v, session_id: sessionId, correlation_id: componentAction?.correlationId ?? current.correlationId,
+            action_id: componentAction?.id ?? null, association: componentAction ? 'internal' : link.association };
+    });
+    return {
+        session_id: sessionId, correlation_id: action?.correlationId ?? current.correlationId,
+        action_id: action?.id ?? null, device: current.device, ...link,
+        ...(current.ref ? { requested_action_ref: current.ref } : {}),
+        operation_started_at_ms: current.start.wall, operation_completed_at_ms: current.end?.wall ?? end.wall,
+        dispatch_started_at_ms: action?.dispatchStart?.wall ?? null,
+        dispatch_completed_at_ms: action?.dispatchEnd?.wall ?? null,
+        verification_completed_at_ms: current.verification?.wall ?? action?.verification?.wall ?? null,
+        observations, trace_context: { supported: !!current.systemTraceId, trace_id: current.systemTraceId ?? null, markers: [] }
+    };
+}
+export async function withEvidence(options, operation) {
+    prune();
+    const parent = context.getStore();
+    const id = randomUUID();
+    const record = options.action ? { id, correlationId: parent?.correlationId ?? id, device: null,
+        dispatchStart: null, dispatchEnd: null, verification: null, completed: null } : options.ref?.sessionId === sessionId ? active.get(options.ref.actionId) ?? history.get(options.ref.actionId) ?? null : null;
+    const current = { systemTraceId: parent?.systemTraceId, correlationId: options.action ? record.correlationId : options.journey ? id : randomUUID(),
+        action: record, ref: options.ref, device: null, start: stamp(), end: null, verification: null, observations: [], children: [], isAction: !!options.action };
+    if (options.action && record)
+        active.set(id, record);
+    if (parent && options.action)
+        parent.children.push(current);
+    try {
+        return await context.run(current, async () => {
+            const result = await operation();
+            current.end = stamp();
+            return { result, evidence: assemble(current) };
+        });
+    }
+    finally {
+        if (options.action && record) {
+            active.delete(id);
+            record.completed = performance.now();
+            history.set(id, record);
+            prune();
+        }
+    }
+}
+export function refreshJourneyEvidence(steps) {
+    const current = context.getStore();
+    if (!current)
+        return;
+    for (const step of steps) {
+        const previous = step.result?.evidence;
+        const child = current.children.find(c => c.action?.id === previous?.action_id);
+        if (child && step.result)
+            step.result.evidence = assemble(child);
+    }
+}
+export function completeJourneyVerification(actionId) {
+    const child = context.getStore()?.children.find(c => c.action?.id === actionId);
+    if (child?.action) {
+        child.verification = stamp();
+        child.action.verification = child.verification;
+    }
+}

package/dist/observe/index.js

@@ -1,4 +1,7 @@
+import { omitEvidence } from './evidence.js';
+import { withResolvedDevice } from '../utils/resolve-device.js';
 import { measure } from '../utils/timing.js';
+import { ReadinessTracker } from './readiness.js';
 import { resolveTargetDevice } from '../utils/resolve-device.js';
 import { AndroidObserve } from './android.js';
 import { iOSObserve } from './ios.js';
@@ -136,16 +139,22 @@ export class ToolsObserve {
     }
     static async getUITreeHandler({ platform, deviceId, responseMode = 'debug', sinceSnapshotRevision }) {
         const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId);
+        const acquisitionStarted = Date.now();
         const tree = await observe.getUITree(resolved.id);
+        tree.readiness = new ReadinessTracker(resolved.platform, resolved.id).observe(tree, acquisitionStarted);
         if (responseMode !== 'compact')
             return tree;
         const revision = tree?.snapshot_revision ?? null;
+        const session = { snapshot_session_id: tree?.snapshot_session_id, readiness: tree.readiness };
+        if (tree?.error)
+            return { ...session, delta_available: false, snapshot_revision: revision, error: tree.error };
         const baseRevision = sinceSnapshotRevision;
         if (!Number.isInteger(baseRevision) || revision === null) {
-            return { delta_available: false, snapshot_revision: revision };
+            return { ...session, delta_available: false, snapshot_revision: revision };
         }
         const delta = getStateDelta(`${resolved.platform}:${resolved.id}`, baseRevision, revision);
-        return delta ? { delta_available: true, state_delta: delta, snapshot_revision: revision } : {
+        return delta ? { ...session, delta_available: true, state_delta: delta, snapshot_revision: revision } : {
+            ...session,
             delta_available: false,
             snapshot_revision: revision,
             reason: 'BASE_REVISION_UNAVAILABLE'
@@ -192,14 +201,23 @@ export class ToolsObserve {
             return await observe.startLogStream(packageName, resolved.id, sid);
         }
     }
-    static async readLogStreamHandler({ platform, sessionId, limit, since }) {
+    static async readLogStreamHandler({ platform, sessionId, limit, since, deviceId }) {
         const sid = sessionId || 'default';
-        const { observe } = await ToolsObserve.resolveObserve(platform);
+        const android = new AndroidObserve();
+        const ios = new iOSObserve();
+        const observe = platform === 'android' ? android : platform === 'ios' ? ios :
+            ios.getLogStreamDevice(sid) && !android.getLogStreamDevice(sid) ? ios : android;
+        const streamDevice = observe.getLogStreamDevice(sid);
+        if (deviceId && streamDevice && streamDevice.id !== deviceId)
+            throw new Error('LOG_STREAM_DEVICE_MISMATCH');
         return await observe.readLogStream(sid, limit ?? 100, since);
     }
     static async stopLogStreamHandler({ platform, sessionId }) {
         const sid = sessionId || 'default';
-        const { observe } = await ToolsObserve.resolveObserve(platform);
+        const android = new AndroidObserve();
+        const ios = new iOSObserve();
+        const observe = platform === 'android' ? android : platform === 'ios' ? ios :
+            ios.getLogStreamDevice(sid) && !android.getLogStreamDevice(sid) ? ios : android;
         return await observe.stopLogStream(sid);
     }
     static async captureScreenshotHandler({ platform, deviceId }) {
@@ -217,6 +235,15 @@ export class ToolsObserve {
         return await observe.getScreenFingerprint(resolved.id);
     }
     static async captureDebugSnapshotHandler({ reason, includeLogs = true, includeScreenshot = true, logLines = 200, platform, appId, deviceId, sessionId } = {}) {
+        const { resolved } = await ToolsObserve.resolveObserve(platform, deviceId, appId);
+        return withResolvedDevice(resolved, () => ToolsObserve.collectDebugSnapshot({ reason, includeLogs, includeScreenshot, logLines,
+            platform: resolved.platform, appId, deviceId: resolved.id, sessionId }));
+    }
+    static async collectDebugSnapshot({ reason, includeLogs = true, includeScreenshot = true, logLines = 200, platform, appId, deviceId, sessionId } = {}) {
+        if (!includeScreenshot)
+            omitEvidence('screenshot');
+        if (!includeLogs)
+            omitEvidence('logs');
         const timestamp = Date.now();
         const raw = {
             timestamp,
@@ -236,7 +263,7 @@ export class ToolsObserve {
             currentScreen: (!platform || platform === 'android') ? ToolsObserve.getCurrentScreenHandler({ deviceId }) : Promise.resolve(null),
             fingerprint: ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }),
             uiTree: ToolsObserve.getUITreeHandler({ platform, deviceId }),
-            readLogStream: includeLogs ? ToolsObserve.readLogStreamHandler({ platform, sessionId: sid, limit: logLines }) : Promise.resolve({ entries: [] }),
+            readLogStream: includeLogs ? ToolsObserve.readLogStreamHandler({ platform, deviceId, sessionId: sid, limit: logLines }) : Promise.resolve({ entries: [] }),
         };
         const results = await Promise.allSettled(Object.values(tasks));
         const keys = Object.keys(tasks);

package/dist/observe/ios.js

@@ -1,3 +1,5 @@
+import { randomUUID } from 'node:crypto';
+import { captureEvidence } from './evidence.js';
 import { spawn } from "child_process";
 import { remainingBudget } from '../utils/operation-budget.js';
 import { execCmd } from '../utils/exec.js';
@@ -256,17 +258,21 @@ export function traverseIDBNode(node, elements, parentIndex = -1, depth = 0) {
     return currentIndex;
 }
 const iosActiveLogStreams = new Map();
-export function _setIOSActiveLogStream(sessionId, file) {
-    iosActiveLogStreams.set(sessionId, { proc: {}, file });
+export function _setIOSActiveLogStream(sessionId, file, device) {
+    iosActiveLogStreams.set(sessionId, { proc: {}, file, device });
 }
 export function _clearIOSActiveLogStream(sessionId) {
     iosActiveLogStreams.delete(sessionId);
 }
 export class iOSObserve {
+    getLogStreamDevice(sessionId = 'default') { return iosActiveLogStreams.get(sessionId)?.device ?? null; }
     async getDeviceMetadata(deviceId = "booted") {
         return getIOSDeviceMetadata(deviceId);
     }
     async getLogs(filters = {}) {
+        return captureEvidence('logs', { platform: 'ios', id: filters.deviceId ?? '' }, () => this.collectGetLogs(filters));
+    }
+    async collectGetLogs(filters = {}) {
         const { appId, deviceId = 'booted', pid, tag, level, contains, since_seconds, limit } = filters;
         const args = ['simctl', 'spawn', deviceId, 'log', 'show', '--style', 'syslog'];
         // Default to last N seconds if no since_seconds provided; limit lines handled after parsing
@@ -418,8 +424,11 @@ export class iOSObserve {
         }
     }
     async captureScreenshot(deviceId = "booted") {
+        return captureEvidence('screenshot', { platform: 'ios', id: deviceId ?? '' }, () => this.collectCaptureScreenshot(deviceId));
+    }
+    async collectCaptureScreenshot(deviceId = "booted") {
         const device = await getIOSDeviceMetadata(deviceId);
-        const tmpFile = `/tmp/mcp-ios-screenshot-${Date.now()}.png`;
+        const tmpFile = `/tmp/mcp-ios-screenshot-${randomUUID()}.png`;
         try {
             await iosExecCommand(['simctl', 'io', deviceId, 'screenshot', tmpFile], deviceId);
             const buffer = await fs.readFile(tmpFile);
@@ -485,6 +494,9 @@ export class iOSObserve {
         }
     }
     async getUITree(deviceId = "booted") {
+        return captureEvidence('ui_tree', { platform: 'ios', id: deviceId ?? '' }, () => this.collectGetUITree(deviceId));
+    }
+    async collectGetUITree(deviceId = "booted") {
         const measurement = createObservationMeasurement('ios');
         let device;
         try {
@@ -608,11 +620,14 @@ export class iOSObserve {
         }
     }
     async getScreenFingerprint(deviceId = 'booted') {
+        return captureEvidence('fingerprint', { platform: 'ios', id: deviceId ?? '' }, () => this.collectGetScreenFingerprint(deviceId));
+    }
+    async collectGetScreenFingerprint(deviceId = 'booted') {
         try {
             const tree = await this.getUITree(deviceId);
             if (!tree || tree.error)
                 return { fingerprint: null, error: tree && tree.error };
-            return computeScreenFingerprint(tree, null, 'ios', 50);
+            return { ...computeScreenFingerprint(tree, null, 'ios', 50), captured_at_ms: tree.captured_at_ms };
         }
         catch (e) {
             return { fingerprint: null, error: e instanceof Error ? e.message : String(e) };
@@ -652,9 +667,10 @@ export class iOSObserve {
             });
             proc.on('close', () => {
                 stream.end();
-                iosActiveLogStreams.delete(sessionId);
+                if (iosActiveLogStreams.get(sessionId)?.proc === proc)
+                    iosActiveLogStreams.delete(sessionId);
             });
-            iosActiveLogStreams.set(sessionId, { proc, file });
+            iosActiveLogStreams.set(sessionId, { proc, file, device: { platform: 'ios', id: deviceId ?? '' } });
             return { success: true, stream_started: true };
         }
         catch {
@@ -673,6 +689,9 @@ export class iOSObserve {
         return { success: true };
     }
     async readLogStream(sessionId = 'default', limit = 100, since) {
+        return captureEvidence('logs', this.getLogStreamDevice(sessionId), () => this.collectReadLogStream(sessionId, limit, since));
+    }
+    async collectReadLogStream(sessionId = 'default', limit = 100, since) {
         const entry = iosActiveLogStreams.get(sessionId);
         if (!entry)
             return { entries: [] };

package/dist/observe/readiness-service.js

@@ -0,0 +1,124 @@
+import { pausedReadiness } from '../debugger/guard.js';
+import { resolveTargetDevice, withResolvedDevice } from '../utils/resolve-device.js';
+import { remainingBudget, runWithBudget } from '../utils/operation-budget.js';
+import { ToolsObserve } from './index.js';
+import { isDeviceUnavailable, ReadinessTracker, withReadinessTracker } from './readiness.js';
+function budgetExpired(error) {
+    if (/ACTION_TIMEOUT/.test(String(error)))
+        return true;
+    try {
+        remainingBudget();
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+async function resolve(target) {
+    if (target.platform)
+        return resolveTargetDevice({ ...target, platform: target.platform });
+    try {
+        return await resolveTargetDevice({ ...target, platform: 'android' });
+    }
+    catch {
+        return resolveTargetDevice({ ...target, platform: 'ios' });
+    }
+}
+export async function readinessDelay(ms) {
+    await new Promise(resolve => setTimeout(resolve, Math.min(ms, remainingBudget(ms))));
+    remainingBudget();
+}
+export async function getAppReadiness(args, wait = false) {
+    const started = performance.now();
+    let device = null;
+    let tracker = new ReadinessTracker(args.platform ?? 'android', args.deviceId ?? '');
+    let failureCode;
+    let debugPause = null;
+    await runWithBudget(args.timeoutMs ?? (wait ? 30000 : 15000), async () => {
+        try {
+            device = await resolve(args);
+            remainingBudget();
+            tracker = new ReadinessTracker(device.platform, device.id, args.stabilityMs ?? 500);
+            await withResolvedDevice(device, async () => {
+                let count = 0;
+                while (wait || count < 2) {
+                    remainingBudget();
+                    debugPause = device.platform === 'android' ? pausedReadiness(device.id) : null;
+                    if (debugPause) {
+                        failureCode = wait ? 'DEBUGGER_PAUSED' : undefined;
+                        return;
+                    }
+                    const captureStarted = Date.now();
+                    try {
+                        const tree = await ToolsObserve.getUITreeHandler({ platform: device.platform, deviceId: device.id });
+                        remainingBudget();
+                        tracker.observe(tree, captureStarted);
+                        if (isDeviceUnavailable(tree?.error)) {
+                            failureCode = 'DEVICE_UNAVAILABLE';
+                            return;
+                        }
+                    }
+                    catch (error) {
+                        if (/ACTION_TIMEOUT/.test(String(error)))
+                            throw error;
+                        tracker.unavailable();
+                        if (isDeviceUnavailable(error)) {
+                            failureCode = 'DEVICE_UNAVAILABLE';
+                            return;
+                        }
+                    }
+                    count++;
+                    if (tracker.summary.state === 'settled' || (!wait && tracker.summary.state === 'loading'))
+                        return;
+                    if (!wait && count === 2)
+                        return;
+                    await readinessDelay(wait ? args.pollIntervalMs ?? 500 : args.stabilityMs ?? 500);
+                }
+            });
+        }
+        catch (error) {
+            const expired = budgetExpired(error);
+            if (expired)
+                tracker.deadline();
+            else
+                tracker.unavailable();
+            failureCode = !expired && (!device || isDeviceUnavailable(error)) ? 'DEVICE_UNAVAILABLE' : wait ? 'READINESS_TIMEOUT' : 'READINESS_UNAVAILABLE';
+        }
+    });
+    if (debugPause)
+        return { success: !wait, device, readiness: debugPause, elapsed_ms: performance.now() - started, ...(wait ? { failure_code: 'DEBUGGER_PAUSED' } : {}) };
+    const state = tracker.summary.state;
+    const success = !failureCode && (wait ? state === 'settled' : state !== 'unknown');
+    return { success, device, readiness: tracker.summary, 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 ?? '');
+    let resolved = false;
+    return runWithBudget(timeoutMs, async () => {
+        try {
+            const device = await resolve(target);
+            resolved = true;
+            remainingBudget();
+            tracker = new ReadinessTracker(device.platform, device.id);
+            const result = await withResolvedDevice(device, () => withReadinessTracker(tracker, () => operation(device)));
+            try {
+                remainingBudget();
+            }
+            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 { ...result, readiness: tracker.summary };
+        }
+        catch (error) {
+            const expired = budgetExpired(error);
+            if (expired)
+                tracker.deadline();
+            else
+                tracker.unavailable();
+            return { ...failure(!expired && (!resolved || isDeviceUnavailable(error)) ? 'DEVICE_UNAVAILABLE' : 'TIMEOUT', performance.now() - started, tracker.summary.sample_count), readiness: tracker.summary };
+        }
+    });
+}

package/dist/observe/readiness.js

@@ -0,0 +1,88 @@
+import { pausedReadiness } from '../debugger/guard.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { remainingBudget } from '../utils/operation-budget.js';
+import { computeSnapshotSignature, getSnapshotSessionId } from './snapshot-metadata.js';
+const baselineLimitations = ['NORMALIZED_UI_ONLY', 'FOREGROUND_APP_UNVERIFIED', 'UNRESPONSIVE_SIGNAL_UNSUPPORTED'];
+const capabilities = { loading: true, transitioning: true, settled: true, unresponsive: false, debugger_paused: false };
+export function isDeviceUnavailable(error) {
+    return /device.*(?:not found|offline|disconnected)|no devices found|READINESS_DEVICE_UNAVAILABLE/i.test(String(error));
+}
+export class ReadinessTracker {
+    platform;
+    deviceId;
+    stabilityMs;
+    signature = null;
+    stableSince = 0;
+    summary;
+    constructor(platform, deviceId, stabilityMs = 500) {
+        this.platform = platform;
+        this.deviceId = deviceId;
+        this.stabilityMs = stabilityMs;
+        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' }
+        };
+    }
+    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],
+            evidence: [...this.summary.evidence, { code, source: 'ui_tree', captured_at_ms: null, snapshot_revision: null }].slice(-8) };
+        return this.summary;
+    }
+    deadline() {
+        this.summary = { ...this.summary, limitations: [...new Set([...this.summary.limitations, 'DEADLINE_EXCEEDED'])] };
+        return this.summary;
+    }
+    observe(tree, acquisitionStartedAtMs, now = performance.now()) {
+        const paused = this.platform === 'android' ? pausedReadiness(this.deviceId) : null;
+        if (paused) {
+            this.summary = paused;
+            return this.summary;
+        }
+        if (tree?.error)
+            return this.unavailable('OBSERVATION_FAILED');
+        if (!tree || tree.device?.platform !== this.platform || tree.device?.id !== this.deviceId ||
+            tree.snapshot_session_id !== getSnapshotSessionId() || !Number.isSafeInteger(tree.snapshot_revision) || tree.snapshot_revision <= 0 ||
+            !Number.isFinite(tree.captured_at_ms) || tree.captured_at_ms < acquisitionStartedAtMs || tree.captured_at_ms <= 0 ||
+            !Array.isArray(tree.elements) || !tree.elements.length || tree.elements.some((element) => !element || typeof element !== 'object') ||
+            !Number.isFinite(tree.resolution?.width) || !Number.isFinite(tree.resolution?.height) || tree.resolution.width <= 0 || tree.resolution.height <= 0)
+            return this.unavailable('OBSERVATION_INVALID');
+        const signature = computeSnapshotSignature(tree);
+        if (!signature)
+            return this.unavailable('OBSERVATION_INVALID');
+        const nativeLoading = tree.elements.some((element) => element.visible === true && ['android.widget.ProgressBar', 'ActivityIndicator', 'ProgressIndicator'].includes(element.type));
+        const textLoading = tree.elements.some((element) => element.visible === true && [element.text, element.contentDescription].some(label => typeof label === 'string' && /^(loading|please\s+wait)[.\s…]*$/i.test(label.trim())));
+        const previous = this.signature;
+        const unchanged = previous === signature;
+        if (!unchanged || nativeLoading || textLoading)
+            this.stableSince = now;
+        this.signature = signature;
+        const stableFor = unchanged && !nativeLoading && !textLoading ? Math.max(0, now - this.stableSince) : 0;
+        const state = nativeLoading || textLoading ? 'loading' : !previous ? 'unknown' : !unchanged ? 'transitioning' : stableFor >= this.stabilityMs ? 'settled' : 'unknown';
+        const code = nativeLoading ? 'NATIVE_LOADING_INDICATOR' : textLoading ? 'LOADING_LABEL' : state === 'transitioning' ? 'SNAPSHOT_CHANGED' : state === 'settled' ? 'SNAPSHOT_STABLE' : 'INSUFFICIENT_SAMPLES';
+        this.summary = {
+            state, scope: 'device_ui', basis: textLoading && !nativeLoading ? 'heuristic' : state === 'unknown' ? 'insufficient' : 'observed',
+            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' }
+        };
+        return this.summary;
+    }
+}
+const waits = new AsyncLocalStorage();
+export function currentReadinessWait() { return waits.getStore(); }
+export function withReadinessTracker(tracker, operation) { return waits.run(tracker, operation); }
+export function observeReadinessWait(tree, startedAtMs) {
+    const tracker = waits.getStore();
+    if (!tracker)
+        return;
+    remainingBudget();
+    const summary = tracker.observe(tree, startedAtMs);
+    if (isDeviceUnavailable(tree?.error))
+        throw new Error('READINESS_DEVICE_UNAVAILABLE');
+    if (summary.limitations.some(code => ['OBSERVATION_INVALID', 'OBSERVATION_FAILED'].includes(code)))
+        throw new Error('READINESS_SAMPLE_INVALID');
+}