mobile-debug-mcp 0.35.0 → 0.37.0

package/src/debugger/lldb/worker.py

@@ -0,0 +1,203 @@
+"""Private JSON worker for simulator LLDB. Stdout is exclusively bounded IPC."""
+import json
+import os
+import queue
+import sys
+import threading
+import time
+import lldb
+from inspection import Inspection
+from breakpoints import Breakpoints
+
+requests = queue.Queue(maxsize=64)
+output_lock = threading.Lock()
+
+
+def send(value):
+    data = json.dumps(value, separators=(",", ":"))
+    if len(data.encode()) > 1024 * 1024:
+        raise ValueError("DEBUGGER_WORKER_FAILED")
+    with output_lock:
+        sys.stdout.write(data + "\n")
+        sys.stdout.flush()
+
+
+def read_input():
+    try:
+        while True:
+            line = sys.stdin.buffer.readline(1024 * 1024 + 1)
+            if not line:
+                break
+            if len(line) > 1024 * 1024:
+                break
+            requests.put(json.loads(line), timeout=1)
+    except Exception:
+        pass
+    finally:
+        # EOF must remain observable even when the queue was filled by a dead parent.
+        eof.set()
+
+
+eof = threading.Event()
+
+
+class Worker:
+    def __init__(self):
+        self.debugger = lldb.SBDebugger.Create(False)
+        self.debugger.SetAsync(True)
+        self.debugger.SetUseColor(False)
+        lldb.SBDebugger.SetInternalVariable("target.load-script-from-symbol-file", "false", self.debugger.GetInstanceName())
+        self.output = open(os.devnull, "w")
+        self.debugger.SetOutputFileHandle(self.output, False)
+        self.debugger.SetErrorFileHandle(self.output, False)
+        self.process = None
+        self.attached = False
+        self.breakpoints = None
+        self.inspection = Inspection()
+        self.created = self.activity = time.monotonic()
+        self.paused_at = None
+        self.last_stop = 0
+        self.terminal = False
+
+    def attach(self, args):
+        self.debugger.SetAsync(False)
+        target = self.debugger.CreateTarget(args["executablePath"])
+        if not target.IsValid():
+            raise ValueError("DEBUGGER_WORKER_FAILED")
+        self.breakpoints = Breakpoints(target)
+        error = lldb.SBError()
+        self.process = target.AttachToProcessWithID(self.debugger.GetListener(), args["pid"], error)
+        self.debugger.SetAsync(True)
+        self.attached = self.process.IsValid()
+        if not error.Success() or not self.process.IsValid():
+            raise ValueError("DEBUGGER_WORKER_FAILED")
+        actual = self.process.GetProcessInfo().GetExecutableFile()
+        if not actual.IsValid() or os.path.realpath(str(actual)) != os.path.realpath(args["executablePath"]):
+            self.process.Detach()
+            raise ValueError("DEBUGGER_WORKER_FAILED")
+        self.last_stop = self.process.GetStopID()
+        if not self.process.Continue().Success():
+            raise ValueError("DEBUGGER_WORKER_FAILED")
+        return {"attached": True}
+
+    def detach(self):
+        self.inspection.invalidate()
+        if self.breakpoints:
+            self.breakpoints.clear()
+        if self.attached:
+            if not self.process.IsValid():
+                raise ValueError("DEBUGGER_WORKER_FAILED")
+            if self.process.GetState() not in (lldb.eStateExited, lldb.eStateDetached):
+                error = self.process.Detach()
+                if not error.Success():
+                    raise ValueError("DEBUGGER_WORKER_FAILED")
+            self.attached = False
+        self.terminal = True
+        return {"detached": True}
+
+    def poll(self):
+        # Removing process events updates LLDB's public state/thread snapshot.
+        # Polling GetState alone can leave the initial attach stop cached.
+        for _ in range(32):
+            event = lldb.SBEvent()
+            if not self.debugger.GetListener().GetNextEvent(event):
+                break
+            if lldb.SBProcess.EventIsProcessEvent(event):
+                lldb.SBProcess.GetStateFromEvent(event)
+        if not self.process or self.terminal:
+            return
+        state = self.process.GetState()
+        if state in (lldb.eStateExited, lldb.eStateDetached):
+            self.inspection.invalidate()
+            self.terminal = True
+            send({"event": "terminated", "reason": "process_exit" if state == lldb.eStateExited else "detached"})
+        elif state == lldb.eStateStopped and self.process.GetStopID() != self.last_stop:
+            self.breakpoints.refresh()
+            event = self.inspection.stopped(self.process)
+            if event:
+                self.last_stop = self.process.GetStopID()
+                self.paused_at = time.monotonic()
+                send(event)
+
+    def command(self, args):
+        command = args["command"]
+        if command == "attach":
+            return self.attach(args)
+        if command == "detach":
+            return self.detach()
+        if not self.process or self.terminal:
+            raise ValueError("DEBUGGER_DISCONNECTED")
+        if command in ("heartbeat", "state"):
+            return {"breakpoints": self.breakpoints.refresh()}
+        if command == "set":
+            return self.breakpoints.set(args)
+        if command == "remove":
+            return self.breakpoints.remove(args["breakpointId"])
+        if command in ("stack", "locals", "step", "resume"):
+            if args.get("stopId") != self.inspection.stop_id:
+                raise ValueError("DEBUGGER_STALE_REFERENCE")
+            if self.process.GetState() != lldb.eStateStopped:
+                raise ValueError("DEBUGGER_NOT_PAUSED")
+        if command == "stack":
+            return self.inspection.stack(args)
+        if command == "locals":
+            return self.inspection.locals(args)
+        if command in ("step", "resume"):
+            thread = self.inspection.thread(args) if command == "step" else None
+            self.inspection.invalidate()
+            self.paused_at = None
+            if command == "resume":
+                if not self.process.Continue().Success():
+                    raise ValueError("DEBUGGER_WORKER_FAILED")
+            else:
+                error = lldb.SBError()
+                if args["kind"] == "into":
+                    thread.StepInto(None, lldb.LLDB_INVALID_LINE_NUMBER, error, lldb.eOnlyDuringStepping)
+                elif args["kind"] == "over":
+                    thread.StepOver(lldb.eOnlyDuringStepping, error)
+                else:
+                    thread.StepOut(error)
+                if not error.Success():
+                    raise ValueError("DEBUGGER_WORKER_FAILED")
+            return {"resumed": True}
+        raise ValueError("INVALID_ARGUMENT")
+
+    def expired(self):
+        now = time.monotonic()
+        return ("pause_limit" if self.paused_at and now - self.paused_at >= 60 else
+                "idle_limit" if now - self.activity >= 300 else
+                "session_limit" if now - self.created >= 1800 else None)
+
+
+def main():
+    worker = Worker()
+    threading.Thread(target=read_input, daemon=True).start()
+    try:
+        while not eof.is_set():
+            worker.poll()
+            reason = worker.expired()
+            if reason:
+                worker.detach()
+                send({"event": "terminated", "reason": reason})
+                break
+            try:
+                args = requests.get(timeout=0.02)
+            except queue.Empty:
+                continue
+            worker.activity = time.monotonic()
+            try:
+                result = worker.command(args)
+                send({"id": args["id"], "result": result})
+            except Exception as error:
+                allowed = {"INVALID_ARGUMENT", "DEBUGGER_NOT_PAUSED", "DEBUGGER_STALE_REFERENCE", "DEBUGGER_DISCONNECTED"}
+                code = str(error) if isinstance(error, ValueError) and str(error) in allowed else "DEBUGGER_WORKER_FAILED"
+                send({"id": args["id"], "error": {"code": code}})
+    finally:
+        try:
+            worker.detach()
+        finally:
+            lldb.SBDebugger.Destroy(worker.debugger)
+
+
+if __name__ == "__main__":
+    main()

package/src/debugger/sessions.ts

@@ -1,6 +1,8 @@
 import { atStage, classify, diagnostic, type DebuggerDiagnostic, type DiagnosticStage } from './diagnostics.js';
 import type { WorkerReply } from './protocol.js';
 import { registerDebuggerPauseProvider } from './guard.js';
+import { IOSDebugNative } from './ios.js';
+import { createIOSWorker, prepareIOSWorker, iosCapabilities, iosLimitations } from './ios-worker.js';
 import { randomUUID } from 'node:crypto';
 import { AndroidDebugNative, type DebugNative, type DebugTarget } from './android.js';
 import { createWorker, prepareWorker, DebuggerError, withDebuggerBudget, debuggerRemaining, type DebugWorker, type WorkerEvent } from './worker.js';
@@ -56,14 +58,16 @@ interface ResultPayload {
 }
 export const debuggerCapabilities = { attach: true, breakpoints: true, stacks: true, locals: true, step: true, resume: true,
     evaluation: false, mutation: false, coroutines: false, native: false };
-const limitations = ['JAVA_KOTLIN_BYTECODE_ONLY', 'DEBUG_METADATA_REQUIRED', 'SHALLOW_LOCALS', 'ALL_THREADS_SUSPEND', 'DEVICE_WIDE_UI_GUARD'];
+export const androidLimitations = ['JAVA_KOTLIN_BYTECODE_ONLY', 'DEBUG_METADATA_REQUIRED', 'SHALLOW_LOCALS', 'ALL_THREADS_SUSPEND', 'DEVICE_WIDE_UI_GUARD'];
 export function debuggerExpiry(created: number, activity: number, pausedAt: number | undefined, now: number) {
     return pausedAt !== undefined && now - pausedAt >= 60000 ? 'pause_limit' : now - activity >= 300000 ? 'idle_limit' : now - created >= 1800000 ? 'session_limit' : null;
 }
 export class DebuggerSessions {
     private sessions = new Map<string, Session>();
     private closing = false;
-    constructor(private native: DebugNative = new AndroidDebugNative(), private workerFactory = createWorker, private prerequisite = prepareWorker) { }
+    constructor(private native: DebugNative = new AndroidDebugNative(), private workerFactory: (event: (event: WorkerEvent) => void) => Promise<DebugWorker> = createWorker, private prerequisite: () => Promise<unknown> = prepareWorker, private options: { platform?: 'android' | 'ios'; capabilities?: Record<string, boolean>; limitations?: string[] } = {}) { }
+    private get platform() { return this.options.platform ?? 'android'; }
+    private get workerResource() { return this.platform === 'ios' ? 'lldb_worker' : 'jdi_worker'; }
     private prune() {
         const terminal = [...this.sessions.values()].filter(s => s.terminalAt !== undefined && s.cleanup.status === 'complete');
         for (const s of terminal)
@@ -80,9 +84,10 @@ export class DebuggerSessions {
         const success = payload.success ?? (!['failed', 'disconnected'].includes(s.state) && s.cleanup.status !== 'failed');
         const code = s.cleanup.status === 'failed' ? 'DEBUGGER_CLEANUP_FAILED' : s.state === 'disconnected' ? 'DEBUGGER_DISCONNECTED' : s.reason?.match(/^[A-Z_]+$/) ? s.reason : 'DEBUGGER_WORKER_FAILED';
         return structuredClone({ success, ...(!success ? { error: { code, message: code, retryable: false, diagnostic: s.cleanup.status === 'failed' ? diagnostic('cleanup', 'operation_failed') : s.diagnostic ?? diagnostic('unknown', 'unknown') } } : {}), debug_session_id: s.id,
-            device: { platform: 'android', id: s.device }, target: s.target, state: s.state, captured_at_ms: Date.now(),
-            capabilities: debuggerCapabilities, limitations, cleanup: s.cleanup, reason: s.reason, stop: s.stop, ...payload });
+            device: { platform: this.platform, id: s.device }, target: s.target, state: s.state, captured_at_ms: Date.now(),
+            capabilities: this.options.capabilities ?? debuggerCapabilities, limitations: this.options.limitations ?? androidLimitations, cleanup: s.cleanup, reason: s.reason, stop: s.stop, ...payload });
     }
+    owns(id: string) { return this.sessions.has(id); }
     summary(id: string) { return this.result(this.get(id)); }
     hasActiveSessions() { return [...this.sessions.values()].some(s => s.cleanup.status !== 'complete'); }
     paused(device: string) { const s = [...this.sessions.values()].find(s => s.device === device && s.state === 'paused'); return s ? this.result(s) : null; }
@@ -112,13 +117,13 @@ export class DebuggerSessions {
             s.events.shift();
     }
     async capabilities(device: string, app: string, pid?: number) {
-        const prerequisites: Record<string, boolean> = { jdk: false, device: false, process: false };
+        const prerequisites: Record<string, boolean> = { [this.platform === 'ios' ? 'lldb' : 'jdk']: false, device: false, process: false };
         let candidates: DebugTarget[] = [];
         const reasons: string[] = [];
         const diagnostics: DebuggerDiagnostic[] = [];
         try {
             await atStage('prerequisite', 'DEBUGGER_UNSUPPORTED', () => this.prerequisite());
-            prerequisites.jdk = true;
+            prerequisites[this.platform === 'ios' ? 'lldb' : 'jdk'] = true;
         }
         catch (e) {
             if (e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED'].includes(e.code))
@@ -139,9 +144,9 @@ export class DebuggerSessions {
             reasons.push(e instanceof DebuggerError ? e.code : 'DEVICE_UNAVAILABLE');
             diagnostics.push(classify(e, 'target_resolution', 'DEVICE_UNAVAILABLE').diagnostic ?? diagnostic('target_resolution', 'unknown'));
         }
-        return { success: true, debug_session_id: null, device: { platform: 'android', id: device }, target: null, state: null,
+        return { success: true, debug_session_id: null, device: { platform: this.platform, id: device }, target: null, state: null,
             captured_at_ms: Date.now(), supported: Object.values(prerequisites).every(Boolean), prerequisites, candidates,
-            ...(diagnostics.length ? { diagnostics } : {}), capabilities: debuggerCapabilities, reasons, limitations, cleanup: { status: 'complete', remaining_resources: [] } };
+            ...(diagnostics.length ? { diagnostics } : {}), capabilities: this.options.capabilities ?? debuggerCapabilities, reasons, limitations: this.options.limitations ?? androidLimitations, cleanup: { status: 'complete', remaining_resources: [] } };
     }
     async attach(device: string, app: string, pid?: number, timeout = 10000) {
         this.prune();
@@ -167,16 +172,19 @@ export class DebuggerSessions {
                 if (candidates.length > 1)
                     throw new DebuggerError('PROCESS_AMBIGUOUS');
                 s.target = candidates[0];
+                if (this.platform === 'android') {
                 stage = 'forwarding';
                 s.port = await atStage('forwarding', 'DEBUGGER_ATTACH_FAILED', () => this.native.forward(device, s.target!.pid));
                 remaining();
                 s.cleanup.remaining_resources.push(`forward:tcp:${s.port}`);
+                }
                 stage = 'worker_start';
                 s.worker = await atStage('worker_start', 'DEBUGGER_ATTACH_FAILED', () => this.workerFactory(event => this.event(s, event)));
                 remaining();
-                s.cleanup.remaining_resources.push('jdi_worker');
+                s.cleanup.remaining_resources.push(this.workerResource);
+                if (this.platform === 'ios') await atStage('target_resolution', 'DEBUGGER_ATTACH_FAILED', () => this.native.identity(device, s.target!));
                 stage = 'attach';
-                await atStage('attach', 'DEBUGGER_ATTACH_FAILED', () => s.worker!.call('attach', { port: s.port, timeoutMs: remaining() }, remaining()));
+                await atStage('attach', 'DEBUGGER_ATTACH_FAILED', () => s.worker!.call('attach', { port: s.port, ...(this.platform === 'ios' ? { pid: s.target!.pid, executablePath: s.target!.executable_path } : {}), timeoutMs: remaining() }, remaining()));
                 stage = 'target_resolution';
                 await atStage('target_resolution', 'DEBUGGER_ATTACH_FAILED', () => this.native.identity(device, s.target!));
                 remaining();
@@ -227,7 +235,7 @@ export class DebuggerSessions {
                     s.worker = undefined;
                 }
                 catch {
-                    remaining.push('jdi_worker');
+                    remaining.push(this.workerResource);
                 }
             }
             if (s.port !== undefined && s.target) {
@@ -275,6 +283,7 @@ export class DebuggerSessions {
     private assertCommandTarget(s: Session, command: string, args: CommandArgs) {
         if (!s.worker || ['detaching', 'detached', 'disconnected', 'failed'].includes(s.state))
             throw new DebuggerError('DEBUGGER_DISCONNECTED', s.diagnostic ?? diagnostic('command', 'unavailable'));
+        if (command === 'set' && (this.platform === 'ios' ? typeof args.sourceFile !== 'string' || args.className !== undefined : typeof args.className !== 'string' || args.sourceFile !== undefined)) throw new DebuggerError('INVALID_ARGUMENT');
         if (['stack', 'locals', 'step', 'resume'].includes(command)) {
             if (args.stopId !== s.stop?.stop_id)
                 throw new DebuggerError('DEBUGGER_STALE_REFERENCE');
@@ -291,6 +300,7 @@ export class DebuggerSessions {
         if (command === 'state' && (s.cleanup.status === 'complete' || ['detaching', 'detached', 'disconnected', 'failed'].includes(s.state)))
             return this.result(s);
         this.assertCommandTarget(s, command, args);
+        const previous = { state: s.state, stop: s.stop, pausedAt: s.pausedAt };
         if (command === 'step' || command === 'resume') {
             s.state = 'running';
             s.stop = null;
@@ -301,6 +311,7 @@ export class DebuggerSessions {
             return this.result(s, command === 'state' ? { breakpoints: data.breakpoints } : { result: data });
         }
         catch (e) {
+            if (['step', 'resume'].includes(command) && s.state === 'running' && s.stop === null && e instanceof DebuggerError && ['INVALID_ARGUMENT', 'DEBUGGER_STALE_REFERENCE'].includes(e.code)) Object.assign(s, previous);
             return this.handleCommandError(s, command, classify(e, 'command', 'DEBUGGER_WORKER_FAILED'));
         }
     }
@@ -324,4 +335,5 @@ export class DebuggerSessions {
     async shutdown() { this.closing = true; await Promise.allSettled([...this.sessions.values()].filter(s => s.cleanup.status !== 'complete').map(s => this.serial(s, () => this.cleanup(s, true)))); return [...this.sessions.values()].filter(s => s.cleanup.status !== 'complete').map(s => this.result(s)); }
 }
 export const debuggerSessions = new DebuggerSessions();
-registerDebuggerPauseProvider(device => debuggerSessions.paused(device));
+export const iosDebuggerSessions = new DebuggerSessions(new IOSDebugNative(), createIOSWorker, prepareIOSWorker, { platform: 'ios', capabilities: iosCapabilities, limitations: iosLimitations });
+registerDebuggerPauseProvider((device, platform = 'android') => (platform === 'ios' ? iosDebuggerSessions : debuggerSessions).paused(device));

package/src/debugger/worker.ts

@@ -58,7 +58,7 @@ export interface DebugWorker {
   close(): Promise<void>
 }
 type WorkerFailureReason = 'spawn_failed' | 'process_exited' | 'write_failed' | 'invalid_message' | 'message_limit'
-export class JdiWorker implements DebugWorker {
+export class DebuggerProcess implements DebugWorker {
   private child: ChildProcessWithoutNullStreams
   private pending = new Map<number, { resolve(value: WorkerReply): void; reject(error: Error): void; timer: ReturnType<typeof setTimeout>; command: string }>()
   private sequence = 0
@@ -66,8 +66,8 @@ export class JdiWorker implements DebugWorker {
   private failure?: DebuggerError
   private replied = false
   private exited: Promise<void>
-  constructor(java: string, directory: string, private onEvent: (event: WorkerEvent) => void) {
-    this.child = spawn(java, ['-Xmx128m', '--add-modules', 'jdk.jdi', '-cp', directory, 'DebuggerWorker'], { stdio: ['pipe', 'pipe', 'pipe'] })
+  constructor(java: string, directory: string, private onEvent: (event: WorkerEvent) => void, launch?: { args: string[]; env: NodeJS.ProcessEnv }) {
+    this.child = spawn(java, launch?.args ?? ['-Xmx128m', '--add-modules', 'jdk.jdi', '-cp', directory, 'DebuggerWorker'], { stdio: ['pipe', 'pipe', 'pipe'], ...(launch ? { env: launch.env } : {}) })
     let buffer = ''
     this.exited = new Promise(resolve => { this.child.once('exit', () => { this.fail('process_exited'); resolve() }); this.child.once('error', () => { this.fail('spawn_failed'); resolve() }) })
     this.child.stdin.on('error', () => this.fail('write_failed'))
@@ -131,5 +131,8 @@ export class JdiWorker implements DebugWorker {
 }
 export async function createWorker(onEvent: (event: WorkerEvent) => void) {
   const { java, directory } = await prepareWorker()
-  return new JdiWorker(java, directory, onEvent)
+  return new DebuggerProcess(java, directory, onEvent)
 }
+
+// Compatibility export for existing JDI transport callers/tests.
+export { DebuggerProcess as JdiWorker }

package/src/interact/index.ts

@@ -157,11 +157,22 @@ export class ToolsInteract {
     return await interact.tap(x, y, resolved.id, timeoutMs)
   }
 
+  private static _getResolvedElement(elementId: string, platform?: 'android' | 'ios', deviceId?: string) {
+    const resolved = ToolsInteract._resolvedUiElements.get(elementId)
+    if (!resolved || (platform && resolved.platform !== platform) || (deviceId && resolved.deviceId !== deviceId)) return null
+    return resolved
+  }
+
+  static getResolvedElementTarget(elementId: string, platform?: 'android' | 'ios', deviceId?: string) {
+    const resolved = ToolsInteract._getResolvedElement(elementId, platform, deviceId)
+    return resolved ? { platform: resolved.platform, deviceId: resolved.deviceId } : null
+  }
+
   static async tapElementHandler({ elementId, verificationMode = 'full', timeoutMs, platform, deviceId, freshTree }: { elementId: string, verificationMode?: 'none' | 'light' | 'full', timeoutMs?: number, platform?: 'android' | 'ios', deviceId?: string, freshTree?: UiTree }): Promise<TapElementResponse> {
     const actionType = 'tap_element'
     const selector = { elementId }
-    const resolved = ToolsInteract._resolvedUiElements.get(elementId)
-    if (!resolved || (platform && resolved.platform !== platform) || (deviceId && resolved.deviceId !== deviceId)) {
+    const resolved = ToolsInteract._getResolvedElement(elementId, platform, deviceId)
+    if (!resolved) {
       return ToolsInteract._actionFailure(actionType, selector, null, 'STALE_REFERENCE', true, null)
     }
 

package/src/interact/waits/ui-change-wait.ts

@@ -5,7 +5,7 @@ import type { ScopeTree } from '../targeting/target-scope.js'
 import type { UiChangeScopeResult, UiChangeSignatureSet } from '../model.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, type ChangeInput, type ChangeWait } from './ui-change-state.js'
@@ -24,11 +24,16 @@ function changed(s: ChangeWait, signatures: UiChangeSignatureSet) {
     s.candidate = signatures; s.change = change; 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: ChangeWait, deps: ChangeDependencies) {
   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/src/interact/waits/ui-wait.ts

@@ -1,21 +1,22 @@
 import { systemClock } from '../../runtime/clock.js'
+import { benchmarkStage } from '../../utils/benchmark-metrics.js'
 import type { UiTree } from '../observation.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,
   type UIWaitInput, type UIWaitDependencies, type UIWaitState, type UIWaitResult } from './ui-wait-state.js'
 
 async function delay(s: UIWaitState, ms: number) {
-  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: UIWaitState, tree: UiTree, now: number): UIWaitResult | null {
   const age = typeof tree?.captured_at_ms === 'number' ? now - tree.captured_at_ms : null
   if (!(s.met && (age === null || age <= 500))) { s.stable = 0; return null }
   s.stable++
-  if (s.stable < (s.args.singleObservation ? 1 : 2) || (s.tracker && s.tracker.summary.state !== 'settled')) return null
+  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) }
 }
@@ -42,6 +43,8 @@ async function poll(s: UIWaitState, deps: UIWaitDependencies): Promise<UIWaitRes
   remainingBudget(); 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))) throw new Error('ACTION_TIMEOUT')

package/src/manage/index.ts

@@ -1,3 +1,4 @@
+import { validAppId } from '../utils/app-installation.js'
 import type { IOSBuildOptions } from './ios.js'
 import { promises as fs } from 'fs'
 import path from 'path'
@@ -303,6 +304,7 @@ export class ToolsManage {
   }
 
   static async listDevicesHandler({ platform, appId }: { platform?: 'android' | 'ios', appId?: string }) {
+    if (appId !== undefined && !validAppId(appId)) throw new Error('Invalid appId')
     const devices = await listDevices(platform, appId)
     return { devices }
   }

package/src/manage/ios.ts

@@ -1,3 +1,4 @@
+import { checkDebuggerGuard } from '../debugger/guard.js'
 import { buildIOS } from './ios/build.js'
 import type { IOSBuildOptions } from './ios/build-types.js'
 export type { IOSBuildOptions } from './ios/build-types.js'
@@ -160,6 +161,7 @@ export class iOSManage {
 
 async function installWithIdb(toInstall: string, deviceId: string) {
   await new Promise<void>((resolve, reject) => {
+    checkDebuggerGuard(true)
     const proc = spawn(getIdbCmd(), ['install', toInstall, '--udid', deviceId]);
     let stderr = '';
     proc.stderr.on('data', d => stderr += d.toString());

package/src/observe/device-readiness.ts

@@ -0,0 +1,96 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { DeviceReadiness } from '../contracts/device-readiness.js'
+import type { DeviceInfo } from '../types.js'
+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?: string): DeviceReadiness {
+  return { wakefulness: 'unknown', lock_state: 'unknown', input_ready: null, blockers: [], evidence: [], limitations: code ? [code] : [] }
+}
+function values(text: string, pattern: RegExp) { return [...text.matchAll(pattern)].map(match => match[1]) }
+function unique(items: string[]) { return items.length > 0 && new Set(items).size === 1 ? items[0] : null }
+export function parseAndroidPower(text: string): DeviceReadiness['wakefulness'] {
+  // 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: string): DeviceReadiness['lock_state'] {
+  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: DeviceReadiness): DeviceReadiness {
+  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: string): DeviceReadiness['lock_state'] {
+  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'
+}
+type Probe = (command: string, args: string[], timeout: number) => Promise<{ exitCode: number | null; stdout: string; stderr: string }>
+const probes = new AsyncLocalStorage<Probe>()
+export function withDeviceReadinessProbe<T>(probe: Probe, operation: () => Promise<T>) { return probes.run(probe, operation) }
+const nativeProbe: Probe = (command, args, timeout) => execCmd(command, args, { timeout })
+export async function observeDeviceReadiness(device?: Pick<DeviceInfo, 'platform' | 'id'> | null, probe: Probe = probes.getStore() ?? nativeProbe): Promise<DeviceReadiness> {
+  return benchmarkStage('device_readiness_ms', () => observe(device, probe))
+}
+async function observe(device: Pick<DeviceInfo, 'platform' | 'id'> | null | undefined, probe: Probe): Promise<DeviceReadiness> {
+  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: DeviceReadiness, id: string, kind: 'power' | 'window', probe: 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 as DeviceReadiness['wakefulness']
+    else state.lock_state = value as DeviceReadiness['lock_state']
+    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/src/observe/evidence.ts

@@ -214,15 +214,25 @@ export function refreshJourneyEvidence(steps: Array<{ result?: { evidence?: unkn
   const current = context.getStore()
   if (!current) return
   for (const step of steps) {
-    const previous = step.result?.evidence as { action_id?: string } | undefined
+    const previous = step.result?.evidence as { action_id?: string; observations?: Array<{ evidence_id: string }> } | undefined
     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: string) {
   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
   }
@@ -312,3 +322,22 @@ function recordCaptureTime(acquisition: Acquisition, result: EvidencePayload | n
     acquisition.reused = source < start.wall
   }
 }
+
+export class JourneyStepError extends Error {
+  constructor(readonly evidence: ReturnType<typeof assemble>, cause: unknown) {
+    super(cause instanceof Error ? cause.message : String(cause), { cause })
+  }
+}
+
+/** Retain per-step evidence without changing the parent journey's acquisition flow. */
+export async function withJourneyStepEvidence<T>(operation: () => Promise<T>) {
+  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
+  }
+}