mobile-debug-mcp 0.35.0 → 0.36.0

package/src/debugger/ios.ts

@@ -0,0 +1,45 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import path from 'node:path'
+import { realpath } from 'node:fs/promises'
+import { getXcrunCmd } from '../utils/ios/utils.js'
+import type { DebugNative, DebugTarget } from './android.js'
+import { DebuggerError, debuggerRemaining, debuggerSignal, nativeError } from './worker.js'
+const exec = promisify(execFile)
+export async function iosExec(file: string, args: string[], env?: NodeJS.ProcessEnv) {
+  try { return (await exec(file, args, { timeout: debuggerRemaining(5000), signal: debuggerSignal(), maxBuffer: 1024 * 1024, ...(env ? { env } : {}) })).stdout.trim() }
+  catch (e) { throw nativeError(e, 'DEVICE_UNAVAILABLE') }
+}
+export class IOSDebugNative implements DebugNative {
+  constructor(private run = iosExec) {}
+  private sim(args: string[]) { return this.run(getXcrunCmd(), ['simctl', ...args]) }
+  async candidates(device: string, app: string): Promise<DebugTarget[]> {
+    if (!/^[A-Fa-f0-9]{8}(?:-[A-Fa-f0-9]{4}){3}-[A-Fa-f0-9]{12}$/.test(device) || !/^[A-Za-z0-9][A-Za-z0-9.-]+$/.test(app)) throw new DebuggerError('INVALID_ARGUMENT')
+    const inventory = JSON.parse(await this.sim(['list', 'devices', 'booted', '--json'])) as { devices: Record<string, { udid: string; state: string }[]> }
+    if (!Object.values(inventory.devices).flat().some(d => d.udid === device && d.state === 'Booted')) throw new DebuggerError('DEBUGGER_UNSUPPORTED')
+    const services = await this.sim(['spawn', device, 'launchctl', 'list'])
+    const pids = this.processes(services, app)
+    if (!pids.length) return []
+    const container = await this.sim(['get_app_container', device, app, 'app'])
+    const executable = await this.run('/usr/bin/plutil', ['-extract', 'CFBundleExecutable', 'raw', '-o', '-', path.join(container, 'Info.plist')])
+    if (path.basename(executable) !== executable || !executable) throw new DebuggerError('PROCESS_NOT_FOUND')
+    const executablePath = await realpath(path.join(container, executable))
+    return Promise.all(pids.map(pid => this.identity(device, { app_id: app, pid, process_name: executable, executable_path: executablePath, start_identity: '', uid: null })))
+  }
+  private processes(services: string, app: string) {
+    return services.split('\n').flatMap(line => {
+      const [pid, , label] = line.trim().split(/\s+/)
+      return /^\d+$/.test(pid) && label?.startsWith(`UIKitApplication:${app}[`) ? [Number(pid)] : []
+    })
+  }
+  async identity(device: string, target: DebugTarget): Promise<DebugTarget> {
+    const services = await this.sim(['spawn', device, 'launchctl', 'list'])
+    if (!this.processes(services, target.app_id).includes(target.pid)) throw new DebuggerError('PROCESS_CHANGED')
+    const command = await this.run('/bin/ps', ['-ww', '-p', String(target.pid), '-o', 'comm='])
+    const started = await this.run('/bin/ps', ['-p', String(target.pid), '-o', 'lstart='])
+    if (command !== target.executable_path || !started || (target.start_identity && started !== target.start_identity)) throw new DebuggerError('PROCESS_CHANGED')
+    return { ...target, start_identity: started }
+  }
+  async forward(): Promise<number> { throw new DebuggerError('DEBUGGER_UNSUPPORTED') }
+  async removeForward() { throw new DebuggerError('DEBUGGER_UNSUPPORTED') }
+}

package/src/debugger/lldb/breakpoints.py

@@ -0,0 +1,51 @@
+"""Owned source breakpoints with exact-line checking, including late image loads."""
+import os
+import uuid
+import lldb
+
+
+class Breakpoints:
+    def __init__(self, target):
+        self.target = target
+        self.owned = {}
+
+    def describe(self, key):
+        bp, source, line = self.owned[key]
+        locations = []
+        rejected = False
+        for loc in bp:
+            entry = loc.GetAddress().GetLineEntry()
+            actual = str(entry.GetFileSpec())
+            exact = entry.IsValid() and os.path.normpath(actual) == source and entry.GetLine() == line
+            loc.SetEnabled(exact)
+            if exact:
+                locations.append({"source_file": actual, "line": line})
+            else:
+                rejected = True
+        known_source = self.target.FindCompileUnits(lldb.SBFileSpec(source)).GetSize() > 0
+        status = "resolved" if locations else "rejected" if rejected or known_source else "pending"
+        return {"breakpoint_id": key, "status": status, "locations": locations}
+
+    def set(self, args):
+        source = os.path.normpath(args["sourceFile"])
+        bp = self.target.BreakpointCreateByLocation(lldb.SBFileSpec(source), args["line"], 0, 0, lldb.SBFileSpecList(), False)
+        key = str(uuid.uuid4())
+        self.owned[key] = (bp, source, args["line"])
+        result = self.describe(key)
+        if result["status"] == "rejected":
+            self.target.BreakpointDelete(bp.GetID())
+            del self.owned[key]
+        return result
+
+    def refresh(self):
+        return [self.describe(key) for key in list(self.owned)]
+
+    def remove(self, key):
+        if key in self.owned:
+            bp, _, _ = self.owned.pop(key)
+            self.target.BreakpointDelete(bp.GetID())
+        return {"removed": True}
+
+    def clear(self):
+        for key in list(self.owned):
+            self.remove(key)

package/src/debugger/lldb/inspection.py

@@ -0,0 +1,109 @@
+"""Bounded, static inspection. Never evaluate expressions or object descriptions."""
+import uuid
+import re
+import lldb
+
+
+def location(frame):
+    entry = frame.GetLineEntry()
+    file = entry.GetFileSpec()
+    source = str(file)[:512] if file.IsValid() else None
+    return {"source_file": source, "line": entry.GetLine() if entry.IsValid() else None,
+            "method_name": (frame.GetFunctionName() or "")[:512], "class_name": None}
+
+
+class Inspection:
+    def __init__(self):
+        self.invalidate()
+
+    def invalidate(self):
+        self.stop_id = None
+        self.threads = {}
+        self.frames = {}
+
+    def stopped(self, process):
+        self.invalidate()
+        self.stop_id = str(uuid.uuid4())
+        selected = None
+        chosen = process.GetSelectedThread()
+        threads = [chosen] if chosen.IsValid() else []
+        for index in range(min(process.GetNumThreads(), 100)):
+            thread = process.GetThreadAtIndex(index)
+            if not chosen.IsValid() or thread.GetThreadID() != chosen.GetThreadID():
+                threads.append(thread)
+        for thread in threads[:100]:
+            key = str(uuid.uuid4())
+            self.threads[key] = thread
+            if selected is None and thread.GetStopReason() not in (lldb.eStopReasonNone, lldb.eStopReasonInvalid):
+                selected = key
+        if selected is None or process.GetState() != lldb.eStateStopped:
+            self.invalidate()
+            return None
+        thread = self.threads.get(selected)
+        return {"event": "stopped", "stop_id": self.stop_id, "thread_id": selected,
+                "reason": stop_reason(thread),
+                "location": location(thread.GetFrameAtIndex(0)) if thread else None,
+                "threads": [{"thread_id": key, "name": (t.GetName() or "")[:256]} for key, t in self.threads.items()],
+                "threads_truncated": process.GetNumThreads() > 100}
+
+    def thread(self, args):
+        if args.get("stopId") != self.stop_id or args.get("threadId") not in self.threads:
+            raise ValueError("DEBUGGER_STALE_REFERENCE")
+        return self.threads[args["threadId"]]
+
+    def stack(self, args):
+        thread = self.thread(args)
+        offset, limit = args.get("offset", 0), args.get("limit", 20)
+        count = min(thread.GetNumFrames(), 1000)
+        frames = []
+        for index in range(offset, min(count, offset + limit)):
+            frame = thread.GetFrameAtIndex(index)
+            key = self.stop_id + ":" + args["threadId"] + ":" + str(index)
+            if key not in self.frames and len(self.frames) >= 1000:
+                break
+            self.frames[key] = frame
+            frames.append({"frame_id": key, "index": index, **location(frame)})
+        return {"frames": frames, "truncated": count > offset + len(frames) or thread.GetNumFrames() > 1000}
+
+    def locals(self, args):
+        if args.get("stopId") != self.stop_id or args.get("frameId") not in self.frames:
+            raise ValueError("DEBUGGER_STALE_REFERENCE")
+        frame = self.frames[args["frameId"]]
+        values = frame.GetVariables(True, True, False, True, lldb.eNoDynamicValues)
+        result = []
+        for index in range(min(values.GetSize(), 100)):
+            value = values.GetValueAtIndex(index).GetNonSyntheticValue()
+            name, kind = (value.GetName() or "")[:256], (value.GetTypeName() or "")[:256]
+            if not value.GetError().Success():
+                result.append({"name": name, "type": kind, "availability": "unavailable"})
+                continue
+            primitive = value.GetType().GetTypeFlags() & (lldb.eTypeIsScalar | lldb.eTypeIsInteger | lldb.eTypeIsFloat)
+            text = value.GetValue() if primitive else None
+            # Swift value wrappers are not C scalars. Decode only standard primitive storage.
+            if kind in ("Swift.Int", "Swift.Int32", "Swift.Int64", "Swift.UInt", "Swift.Bool", "Swift.Double", "Swift.Float"):
+                storage = value.GetChildMemberWithName("_value").GetNonSyntheticValue()
+                if storage.IsValid() and storage.GetError().Success():
+                    text = storage.GetValue()
+            if kind == "Swift.Bool" and text in ("0", "1"):
+                text = "true" if text == "1" else "false"
+            result.append({"name": name, "type": kind, "value": text[:256] if text else None,
+                           "kind": "primitive" if text is not None else "object",
+                           "truncated": bool(text and len(text) > 256),
+                           "object_id": self.object_identity(value, kind) if text is None else None})
+        return {"availability": "available" if result else "unknown", "locals": result,
+                "reason": None if result else "EMPTY_OR_UNAVAILABLE_VARIABLE_METADATA",
+                "truncated": values.GetSize() > 100}
+
+    def object_identity(self, value, kind):
+        pointer = value.GetValue()
+        if pointer and re.fullmatch(r"0x[0-9a-fA-F]+", pointer):
+            return str(uuid.uuid5(uuid.UUID(self.stop_id), kind + ":" + pointer))
+        return None
+
+
+def stop_reason(thread):
+    if thread is None:
+        return "unknown"
+    return {lldb.eStopReasonBreakpoint: "breakpoint", lldb.eStopReasonPlanComplete: "step",
+            lldb.eStopReasonSignal: "signal", lldb.eStopReasonException: "exception",
+            lldb.eStopReasonWatchpoint: "watchpoint", lldb.eStopReasonExec: "exec"}.get(thread.GetStopReason(), "unknown")

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/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());