mobile-debug-mcp 0.35.0 → 0.37.0

package/test/fixtures/ios-debugger-app/Main.swift

@@ -0,0 +1,95 @@
+import UIKit
+
+@inline(never) func increment(_ value: Int) -> Int {
+    let adjusted = value + 1 // STEP_INCREMENT
+    return adjusted // STEP_RETURN
+}
+@inline(never) func helper(_ value: Int) -> Int {
+    let result = increment(value) // STEP_HELPER
+    return result // HELPER_RETURN
+}
+actor AsyncWork {
+    func child(_ input: Int) async -> Int {
+        try? await Task.sleep(nanoseconds: 300_000_000)
+        let childValue = input + 1
+        return childValue // CHILD_RETURN
+    }
+    @inline(never) func calculate(_ seed: Int) async -> Int {
+        let known = seed
+        async let childResult = child(known)
+        let after = await childResult // BEFORE_AWAIT
+        let answer = helper(after + known - seed) // AFTER_AWAIT
+        return answer // ASYNC_RETURN
+    }
+}
+class Controller: UIViewController {
+    let label = UILabel()
+    var task: Task<Void, Never>?
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        view.backgroundColor = .white
+        label.text = "Debugger ready"
+        label.accessibilityIdentifier = "debugger-result"
+        let stack = UIStackView()
+        stack.axis = .vertical
+        stack.spacing = 24
+        stack.addArrangedSubview(label)
+        for (title, action) in [("Calculate", #selector(calculate)), ("Run async", #selector(runAsync)), ("Start cancellation", #selector(startCancellation)), ("Cancel task", #selector(cancelTask))] {
+            let button = UIButton(type: .system)
+            button.setTitle(title, for: .normal)
+            button.addTarget(self, action: action, for: .touchUpInside)
+            stack.addArrangedSubview(button)
+        }
+        stack.translatesAutoresizingMaskIntoConstraints = false
+        view.addSubview(stack)
+        NSLayoutConstraint.activate([stack.centerXAnchor.constraint(equalTo: view.centerXAnchor), stack.centerYAnchor.constraint(equalTo: view.centerYAnchor)])
+    }
+    @objc func calculate() {
+        let known = 41
+        let result = helper(known) // BREAK_CALCULATE
+        label.text = "Debugger result \(result)" // CALCULATE_DONE
+    }
+    @objc func runAsync() {
+        task = Task { @MainActor in
+            let result = await AsyncWork().calculate(42)
+            label.text = "Async result \(result)"
+        }
+    }
+    @objc func startCancellation() {
+        label.text = "Task running"
+        task = Task { @MainActor in
+            do {
+                try await Task.sleep(nanoseconds: 60_000_000_000)
+                label.text = "Unexpected completion"
+            } catch {
+                let cancelled = Task.isCancelled
+                label.text = cancelled ? "Task cancelled" : "Unexpected error" // CANCELLED
+            }
+        }
+    }
+    @objc func cancelTask() { task?.cancel() }
+}
+@main class App: UIResponder, UIApplicationDelegate {
+    var window: UIWindow?
+    func application(_ application: UIApplication, didFinishLaunchingWithOptions options: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+        window = UIWindow(frame: UIScreen.main.bounds)
+        window?.rootViewController = Controller()
+        window?.makeKeyAndVisible()
+        // Test-only control channel; no HID dependency or debugger evaluation.
+        Timer.scheduledTimer(withTimeInterval: 0.05, repeats: true) { [weak self] _ in
+            let commandFile = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0].appendingPathComponent("debugger-command")
+            guard let command = try? String(contentsOf: commandFile, encoding: .utf8),
+                  let controller = self?.window?.rootViewController as? Controller else { return }
+            try? FileManager.default.removeItem(at: commandFile)
+            switch command {
+            case "exit": exit(0)
+            case "calculate": controller.calculate()
+            case "async": controller.runAsync()
+            case "start-cancellation": controller.startCancellation()
+            case "cancel": controller.cancelTask()
+            default: break
+            }
+        }
+        return true
+    }
+}

package/test/fixtures/ios-debugger-app/README.md

@@ -0,0 +1,27 @@
+# iOS debugger fixture
+
+Disposable UIKit app for simulator-only LLDB MCP checks. Builds with Xcode's
+`swiftc -g -Onone`; no external package or user app is used. Select an explicit
+booted simulator:
+
+```sh
+npm run build
+MCP_IOS_DEBUGGER_DEVICE=<UDID> node --import tsx test/device/automated/debugger/runtime.ios.test.ts
+# Include the real 60-second pause expiry:
+MCP_IOS_DEBUGGER_DEVICE=<UDID> MCP_IOS_DEBUGGER_EXTENDED=1 node --import tsx test/device/automated/debugger/runtime.ios.test.ts
+```
+
+Requires macOS, full Xcode with Swift-enabled LLDB/Python, and working idb UI-tree
+reads. The test installs/removes only `dev.mobiledebug.iosfixture`, and cleans its
+private temporary build/module-cache directory. It does not boot/shut down devices.
+The app's fixture-only `Documents/debugger-command` file invokes the same actions
+as its buttons through a main-loop timer. The smoke runner writes only that file
+because the installed idb HID backend expects SimulatorKit at a path absent in
+this Xcode. This is a fixture trigger, not evidence that MCP tap delivery
+succeeded. Paused MCP taps must be rejected before delivery. Completion and
+cancellation use fresh MCP UI-tree assertions.
+
+Async work uses a suspended child operation in an actor, known values on either
+side of await, a main-actor UI update and a separate cancellation task. Boundary
+stepping is recorded independently from source-breakpoint coverage. Stop-scoped
+thread/frame IDs do not establish logical task identity.

package/test/fixtures/ios-debugger-app/build.ts

@@ -0,0 +1,21 @@
+import { execFileSync } from 'node:child_process'
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+export const iosDebuggerAppId = 'dev.mobiledebug.iosfixture'
+export const iosDebuggerSource = fileURLToPath(new URL('./Main.swift', import.meta.url))
+export function buildIOSDebuggerFixture() {
+  const directory = mkdtempSync(path.join(os.tmpdir(), 'mobile-debug-ios-fixture-'))
+  const app = path.join(directory, 'DebuggerFixture.app')
+  try {
+    execFileSync('/bin/mkdir', ['-p', app])
+    const sdk = execFileSync('xcrun', ['--sdk', 'iphonesimulator', '--show-sdk-path'], { encoding: 'utf8' }).trim()
+    execFileSync('xcrun', ['swiftc', '-g', '-module-cache-path', path.join(directory, 'modules'), '-Onone', '-parse-as-library', '-sdk', sdk, '-target', `${os.arch() === 'arm64' ? 'arm64' : 'x86_64'}-apple-ios18.0-simulator`, '-module-name', 'DebuggerFixture', iosDebuggerSource, '-o', path.join(app, 'DebuggerFixture')], { timeout: 120000, stdio: 'pipe' })
+    writeFileSync(path.join(app, 'Info.plist'), `<?xml version="1.0"?><plist version="1.0"><dict><key>CFBundleIdentifier</key><string>${iosDebuggerAppId}</string><key>CFBundleExecutable</key><string>DebuggerFixture</string><key>CFBundleName</key><string>DebuggerFixture</string><key>CFBundlePackageType</key><string>APPL</string><key>CFBundleVersion</key><string>1</string><key>CFBundleShortVersionString</key><string>1.0</string><key>LSRequiresIPhoneOS</key><true/><key>UILaunchScreen</key><dict/></dict></plist>`)
+    return { app, directory }
+  } catch (error) {
+    rmSync(directory, { recursive: true, force: true })
+    throw error
+  }
+}

package/test/fixtures/latency-journey-app/build.ts

@@ -1,5 +1,5 @@
 import { execFileSync } from 'node:child_process'
-import { mkdirSync } from 'node:fs'
+import { existsSync, mkdirSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -11,7 +11,7 @@ export function buildFixture() {
   const androidJar = path.join(sdk, 'platforms', 'android-36', 'android.jar')
   const java = process.env.JAVA_HOME
   const tool = (name: string) => java ? path.join(java, 'bin', name) : name
-  const run = (cmd: string, args: string[]) => execFileSync(cmd, args, { cwd: out, stdio: 'pipe' })
+  const run = (cmd: string, args: string[]) => execFileSync(cmd, args, { cwd: out, stdio: 'pipe', timeout: 60000, killSignal: 'SIGKILL' })
   mkdirSync(path.join(out, 'classes'), { recursive: true })
   run(tool('javac'), ['--release', '8', '-classpath', androidJar, '-d', 'classes', path.join(root, 'src/MainActivity.java')])
   run(tool('jar'), ['cf', 'classes.jar', '-C', 'classes', '.'])
@@ -20,7 +20,7 @@ export function buildFixture() {
   run('zip', ['-q', 'unsigned.apk', 'classes.dex'])
   run(path.join(buildTools, 'zipalign'), ['-f', '4', 'unsigned.apk', 'aligned.apk'])
   // Ephemeral signing material is generated outside version control.
-  try { run(tool('keytool'), ['-genkeypair', '-keystore', 'fixture.jks', '-storepass', 'android', '-keypass', 'android', '-alias', 'fixture', '-dname', 'CN=Latency Fixture', '-keyalg', 'RSA', '-validity', '3650']) } catch { /* Existing local fixture key. */ }
+  if (!existsSync(path.join(out, 'fixture.jks'))) run(tool('keytool'), ['-genkeypair', '-keystore', 'fixture.jks', '-storepass', 'android', '-keypass', 'android', '-alias', 'fixture', '-dname', 'CN=Latency Fixture', '-keyalg', 'RSA', '-validity', '3650'])
   run(path.join(buildTools, 'apksigner'), ['sign', '--ks', 'fixture.jks', '--ks-pass', 'pass:android', '--out', 'fixture.apk', 'aligned.apk'])
   return path.join(out, 'fixture.apk')
 }

package/test/helpers/ios-trace-shutdown.ts

@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict'
+import { promises as fs } from 'node:fs'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+
+export async function verifyIosTraceShutdown(target: Record<string,unknown>, env: Record<string,string> = {}) {
+  const client=new Client({name:'ios-trace-shutdown',version:'1.0.0'})
+  const transport=new StdioClientTransport({command:process.execPath,args:['dist/server.js'],stderr:'pipe',env})
+  let diagnostics=''
+  transport.stderr?.on('data',chunk=>{diagnostics=(diagnostics+String(chunk)).slice(-4096)})
+  try {
+    await client.connect(transport)
+    const capability=await client.callTool({name:'get_system_trace_capabilities',arguments:target},undefined,{timeout:120000})
+    const capabilities=JSON.parse((capability.content as any[]).find(c=>c.type==='text').text)
+    assert.equal(capabilities.supported,true,JSON.stringify(capabilities))
+    const response=await client.callTool({name:'start_system_trace',arguments:{...target,durationMs:30000}},undefined,{timeout:120000})
+    const result=JSON.parse((response.content as any[]).find(c=>c.type==='text').text)
+    assert.equal(result.state,'recording',JSON.stringify(result))
+    const directory=result.cleanup.remaining_resources[0]
+    assert.ok(transport.pid)
+    process.kill(transport.pid,'SIGTERM')
+    let removed=false
+    for(let i=0;i<24;i++){
+      try {await fs.stat(directory)} catch(error) {if((error as NodeJS.ErrnoException).code==='ENOENT'){removed=true;break}throw error}
+      await new Promise(resolve=>setTimeout(resolve,500))
+    }
+    assert.equal(removed,true,`Server shutdown must remove its owned partial trace directory; ${diagnostics}`)
+  } finally {await client.close()}
+}

package/test/unit/debugger/handle-guards.test.ts

@@ -0,0 +1,89 @@
+import assert from 'node:assert/strict'
+import { debuggerSessions, iosDebuggerSessions } from '../../../src/debugger/sessions.js'
+import { handleToolCall } from '../../../src/server-core.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { markDispatchStarted } from '../../../src/utils/operation-budget.js'
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+
+const original = {
+  androidPaused: debuggerSessions.paused, androidActive: debuggerSessions.hasActiveSessions,
+  iosPaused: iosDebuggerSessions.paused, iosActive: iosDebuggerSessions.hasActiveSessions,
+  tree: ToolsObserve.getUITreeHandler, tap: ToolsInteract.tapHandler
+}
+let iosPaused = false, androidPaused = false, racePause = false, reads = 0, androidResolutions = 0
+const inputs: { platform?: string; deviceId?: string }[] = []
+const pause: any = { debug_session_id: 'ios-session', target: { app_id: 'test.app', pid: 1 }, state: 'paused', captured_at_ms: 1 }
+const tree = (platform: string, id: string): any => ({ device: { platform, id }, resolution: { width: 100, height: 100 },
+  elements: [{ text: 'Target', resourceId: 'target', bounds: [0, 0, 40, 40], visible: true, enabled: true, clickable: true }] })
+const payload = (response: any) => JSON.parse(response.content.find((item: any) => item.type === 'text').text)
+const call = async (elementId: string, hints: Record<string, unknown> = {}) => payload(await handleToolCall('tap_element', {
+  elementId, verificationMode: 'none', responseMode: 'compact', ...hints
+}))
+_setDeviceListersForTests({
+  listAndroidDevices: async () => { androidResolutions++; return [{ id: 'android', platform: 'android' } as any] },
+  listIOSDevices: async () => ['ios-a', 'ios-b'].map(id => ({ id, platform: 'ios', booted: true } as any))
+})
+debuggerSessions.hasActiveSessions = () => true
+iosDebuggerSessions.hasActiveSessions = () => true
+debuggerSessions.paused = id => androidPaused && id === 'android' ? { ...pause, debug_session_id: 'android-session' } : null
+iosDebuggerSessions.paused = id => iosPaused && id === 'ios-a' ? pause : null
+ToolsInteract._resetResolvedUiElementsForTests()
+try {
+  ToolsObserve.getUITreeHandler = async ({ platform, deviceId }) => {
+    reads++
+    if (racePause) iosPaused = true
+    return tree(platform!, deviceId!)
+  }
+  ToolsInteract.tapHandler = async ({ platform, deviceId, x, y }) => {
+    markDispatchStarted()
+    inputs.push({ platform, deviceId })
+    return { success: true, device: { platform, id: deviceId }, x, y } as any
+  }
+  const handle = async (platform: 'android' | 'ios', deviceId: string) => {
+    const result = await ToolsInteract.waitForUIHandler({ platform, deviceId, selector: { text: 'Target' }, condition: 'exists', timeout_ms: 1000 })
+    assert.equal(result.status, 'success')
+    return result.element.elementId
+  }
+  const ios = await handle('ios', 'ios-a')
+  const otherIOS = await handle('ios', 'ios-b')
+  const android = await handle('android', 'android')
+  reads = 0; androidResolutions = 0; iosPaused = true
+  for (const hints of [{}, { deviceId: 'ios-a' }, { platform: 'ios' }]) {
+    const blocked = await call(ios, hints)
+    assert.equal(blocked.failure_code, 'DEBUGGER_PAUSED')
+    const details = payload(await handleToolCall('get_interaction_diagnostics', { sessionId: blocked.diagnostics.session_id, resultId: blocked.diagnostics.result_id }))
+    assert.equal(details.result.debugger.debug_session_id, 'ios-session')
+    assert.equal(blocked.delivery_status, 'not_delivered'); assert.equal(blocked.dispatch_started, false)
+  }
+  assert.equal(reads, 0, 'A known pause must block before hierarchy reads')
+  assert.equal(inputs.length, 0); assert.equal(androidResolutions, 0, 'An iOS handle must not resolve an Android device')
+
+  iosPaused = false
+  assert.equal((await call(ios)).success, true)
+  assert.deepEqual(inputs.pop(), { platform: 'ios', deviceId: 'ios-a' })
+  racePause = true
+  const raced = await call(ios)
+  assert.equal(raced.failure_code, 'DEBUGGER_PAUSED')
+  assert.equal(raced.delivery_status, 'not_delivered'); assert.equal(inputs.length, 0, 'A pause during target refresh must block native dispatch')
+  racePause = false
+
+  assert.equal((await call(android)).success, true, 'An unrelated iOS pause must not block Android')
+  assert.deepEqual(inputs.pop(), { platform: 'android', deviceId: 'android' })
+  androidPaused = true
+  assert.equal((await call(android)).failure_code, 'DEBUGGER_PAUSED')
+  assert.equal((await call(otherIOS)).success, true, 'Other iOS devices must remain usable')
+  assert.deepEqual(inputs.pop(), { platform: 'ios', deviceId: 'ios-b' })
+  androidPaused = false; reads = 0
+  for (const hints of [{ platform: 'android', deviceId: 'android' }, { platform: 'ios', deviceId: 'ios-b' }]) {
+    assert.equal((await call(ios, hints)).failure_code, 'STALE_REFERENCE', 'Explicit mismatches retain handle validation')
+  }
+  assert.equal((await call('unknown', { platform: 'ios', deviceId: 'ios-b' })).failure_code, 'STALE_REFERENCE')
+  assert.equal(reads, 0); assert.equal(inputs.length, 0)
+  console.log('PASS stored-handle debugger guards: omitted target, no observation/input while paused, racing pause, platform/device isolation and mismatches')
+} finally {
+  debuggerSessions.paused = original.androidPaused; debuggerSessions.hasActiveSessions = original.androidActive
+  iosDebuggerSessions.paused = original.iosPaused; iosDebuggerSessions.hasActiveSessions = original.iosActive
+  ToolsObserve.getUITreeHandler = original.tree; ToolsInteract.tapHandler = original.tap
+  ToolsInteract._resetResolvedUiElementsForTests(); _resetDeviceListersForTests()
+}

package/test/unit/debugger/ios-preparation.test.ts

@@ -0,0 +1,57 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { mkdtemp, writeFile, rm } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+const exec = promisify(execFile)
+const directory = await mkdtemp(path.join(os.tmpdir(), 'debugger-fake-lldb-'))
+const python = path.join(directory, 'python')
+const xcrun = path.join(directory, 'xcrun')
+const log = path.join(directory, 'calls')
+const failed = path.join(directory, 'failed')
+try {
+  await writeFile(xcrun, `#!${process.execPath}
+const fs=require('node:fs');fs.appendFileSync(${JSON.stringify(log)},'xcrun\\n');
+console.log(process.argv[2]==='lldb'?'/fake/lldb-python':${JSON.stringify(python)});
+`, { mode: 0o700 })
+  await writeFile(python, `#!${process.execPath}
+const fs=require('node:fs');
+if(process.argv.includes('-c')) {
+ fs.appendFileSync(${JSON.stringify(log)},'probe\\n');
+ if(!fs.existsSync(${JSON.stringify(failed)})){fs.writeFileSync(${JSON.stringify(failed)},'');process.exit(1)}
+ console.log('ready');
+} else {
+ fs.appendFileSync(${JSON.stringify(log)},'worker\\n');
+ require('node:readline').createInterface({input:process.stdin}).on('line',line=>{
+  const request=JSON.parse(line);console.log(JSON.stringify({id:request.id,result:{detached:true}}));
+ });
+}
+`, { mode: 0o700 })
+  const code = `
+import assert from 'node:assert/strict';import {readFileSync} from 'node:fs';
+// Load the TypeScript toolchain before emulating macOS so Linux selects its own esbuild.
+const {prepareIOSWorker,createIOSWorker}=await import('./src/debugger/ios-worker.ts');
+// Isolate platform emulation and native binaries from the unit runner process.
+Object.defineProperty(process,'platform',{value:'darwin'});
+const first=prepareIOSWorker();assert.strictEqual(first,prepareIOSWorker());
+const failed=await Promise.allSettled([first,prepareIOSWorker()]);
+assert.ok(failed.every(result=>result.status==='rejected'));
+const retry=prepareIOSWorker();assert.notStrictEqual(first,retry);
+assert.strictEqual(retry,prepareIOSWorker());
+const configuration=await retry;
+assert.equal(configuration.python,${JSON.stringify(python)});
+assert.equal(configuration.env.PYTHONPATH,'/fake/lldb-python');
+assert.equal(configuration.env.PYTHONNOUSERSITE,'1');
+assert.strictEqual(await prepareIOSWorker(),configuration);
+const worker=await createIOSWorker(()=>{});await worker.close();
+const calls=readFileSync(${JSON.stringify(log)},'utf8').trim().split('\\n');
+assert.equal(calls.filter(call=>call==='xcrun').length,4);
+assert.equal(calls.filter(call=>call==='probe').length,2);
+assert.equal(calls.filter(call=>call==='worker').length,1);
+console.log('PASS shared iOS preparation, failed-probe retry, configuration and worker cache reuse');
+`
+  const result = await exec(process.execPath, ['--import', 'tsx', '--input-type=module', '-e', code], {
+    env: { ...process.env, XCRUN_PATH: xcrun }, timeout: 15000
+  })
+  console.log(result.stdout.trim())
+} finally { await rm(directory, { recursive: true, force: true }) }

package/test/unit/debugger/ios.test.ts

@@ -0,0 +1,104 @@
+import assert from 'node:assert/strict'
+import { mkdtemp, writeFile, rm, realpath } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { IOSDebugNative } from '../../../src/debugger/ios.js'
+import { DebuggerSessions, iosDebuggerSessions, debuggerSessions } from '../../../src/debugger/sessions.js'
+import { iosCapabilities, iosLimitations } from '../../../src/debugger/ios-worker.js'
+import { debuggerContracts, debuggerTools } from '../../../src/server/schemas/debugger-schema.js'
+import { withDebuggerGuard, checkDebuggerGuard, pausedReadiness } from '../../../src/debugger/guard.js'
+import { execCommandWithDiagnostics } from '../../../src/utils/ios/utils.js'
+import { handleDebugger } from '../../../src/server/handlers/debugger-handlers.js'
+import { DebuggerError, type WorkerEvent } from '../../../src/debugger/worker.js'
+const directory = await mkdtemp(path.join(os.tmpdir(), 'ios-debugger-unit-'))
+await writeFile(path.join(directory, 'App'), '')
+const executable = await realpath(path.join(directory, 'App'))
+const device = 'F9243BAF-62A8-4990-8A99-17F527F56FDA'
+let processPath = executable, started = 'Mon Nov 4 12:00:00 2026', services = '123\t0\tUIKitApplication:dev.fixture.app[uuid]'
+const calls: string[][] = []
+const native = new IOSDebugNative(async (file, args) => {
+  calls.push([file, ...args])
+  if (args[0] === 'simctl' && args[1] === 'list') return JSON.stringify({ devices: { runtime: [{ udid: device, state: 'Booted' }] } })
+  if (args.includes('get_app_container')) return directory
+  if (file === '/usr/bin/plutil') return 'App'
+  if (args.includes('launchctl')) return services
+  if (args.includes('comm=')) return processPath
+  if (args.includes('lstart=')) return started
+  throw new Error('unexpected native command')
+})
+const base = { debugSessionId: 's', line: 1 }
+for (const selector of [{}, { className: 'dev.App', sourceFile: '/tmp/App.swift' }, { sourceFile: 'App.swift' }]) {
+  assert.equal(debuggerContracts.set_debugger_breakpoint.schema.safeParse({ ...base, ...selector }).success, false)
+}
+for (const selector of [{ className: 'dev.App' }, { sourceFile: '/tmp/App.swift' }]) {
+  assert.equal(debuggerContracts.set_debugger_breakpoint.schema.safeParse({ ...base, ...selector }).success, true)
+}
+assert.ok(debuggerTools.find(t => t.name === 'attach_debugger')!.inputSchema.properties.platform)
+let emit: (event: WorkerEvent) => void = () => {}
+let closed = 0
+const sessions = new DebuggerSessions(native, async onEvent => {
+  emit = onEvent
+  return { call: async (command, args) => {
+    if (command === 'step' && args?.threadId === 'foreign') throw new DebuggerError('DEBUGGER_STALE_REFERENCE')
+    if (command === 'attach') { assert.equal(args?.pid, 123); assert.equal(args?.executablePath, executable); emit({ event: 'stopped', stop_id: 'racing-stop', thread_id: 't' }) }
+    return { breakpoints: [] }
+  }, close: async () => { closed++ } }
+}, async () => {}, { platform: 'ios', capabilities: iosCapabilities, limitations: iosLimitations })
+const androidPause = debuggerSessions.paused, iosPause = iosDebuggerSessions.paused
+try {
+  const candidates = await native.candidates(device, 'dev.fixture.app')
+  assert.equal(candidates[0].pid, 123); assert.equal(candidates[0].executable_path, executable)
+  assert.equal(candidates[0].uid, null)
+  await assert.rejects(native.candidates('booted', 'dev.fixture.app'), /INVALID_ARGUMENT/)
+  await assert.rejects(native.candidates('00000000-0000-0000-0000-000000000000', 'dev.fixture.app'), /DEBUGGER_UNSUPPORTED/)
+  processPath = '/tmp/foreign-process'
+  await assert.rejects(native.identity(device, candidates[0]), /PROCESS_CHANGED/)
+  processPath = executable; started = 'new process'
+  await assert.rejects(native.identity(device, candidates[0]), /PROCESS_CHANGED/)
+  started = candidates[0].start_identity
+  services = '999\t0\tUIKitApplication:dev.fixture.other[uuid]'
+  await assert.rejects(native.identity(device, candidates[0]), /PROCESS_CHANGED/)
+  services = '123\t0\tUIKitApplication:dev.fixture.app[uuid]'
+  const attached = await sessions.attach(device, 'dev.fixture.app')
+  assert.equal(attached.device.platform, 'ios'); assert.equal(attached.state, 'paused', 'racing attach stop is preserved')
+  assert.deepEqual(attached.cleanup.remaining_resources, ['lldb_worker'])
+  await assert.rejects(sessions.command(attached.debug_session_id, 'set', { className: 'Wrong', line: 1 }), /INVALID_ARGUMENT/)
+  emit({ event: 'stopped', stop_id: 'fresh', thread_id: 't' })
+  await assert.rejects(sessions.command(attached.debug_session_id, 'step', { stopId: 'fresh', threadId: 'foreign', kind: 'into' }), /DEBUGGER_STALE_REFERENCE/)
+  assert.equal(sessions.paused(device)?.stop?.stop_id, 'fresh', 'Rejected step preserves known suspension and guard')
+  await assert.rejects(sessions.command(attached.debug_session_id, 'locals', { stopId: 'racing-stop' }), /DEBUGGER_STALE_REFERENCE/)
+  iosDebuggerSessions.paused = id => id === 'same-id' ? { ...attached, debug_session_id: 'ios' } : null
+  debuggerSessions.paused = id => id === 'same-id' ? { ...attached, debug_session_id: 'android' } : null
+  assert.equal(pausedReadiness('same-id', 'ios')?.debug_session_id, 'ios')
+  assert.equal(pausedReadiness('same-id', 'android')?.debug_session_id, 'android')
+  await assert.rejects(withDebuggerGuard('ios', 'same-id', async () => checkDebuggerGuard(true)), /DEBUGGER_PAUSED/)
+  await withDebuggerGuard('ios', 'other', async () => checkDebuggerGuard())
+  await assert.rejects(withDebuggerGuard('ios', 'same-id', async () => execCommandWithDiagnostics(['simctl', 'launch', 'same-id', 'dev.fixture.app'])), /DEBUGGER_PAUSED/, 'Diagnostic fallback cannot resend a paused lifecycle command')
+  assert.equal((await sessions.command(attached.debug_session_id, 'detach')).cleanup.status, 'complete')
+  assert.equal(closed, 1)
+  assert.ok(!calls.some(call => call.includes('forward')), 'iOS must not allocate or remove ADB forwards')
+  const original = iosDebuggerSessions.capabilities
+  try {
+    iosDebuggerSessions.capabilities = async () => { throw new DebuggerError('DEBUGGER_UNSUPPORTED') }
+    const response = await handleDebugger('get_debugger_capabilities', { platform: 'ios', deviceId: device, appId: 'dev.fixture.app' })
+    const payload = JSON.parse(response.content[0].text)
+    assert.equal(payload.device.platform, 'ios'); assert.equal(payload.capabilities.coroutines, false)
+    assert.ok(!/JDK|Java worker|ADB/.test(payload.error.diagnostic.recovery))
+  } finally { iosDebuggerSessions.capabilities = original }
+  console.log('PASS iOS target membership, process identity, contracts, session routing, racing stops and platform guards')
+} finally {
+  debuggerSessions.paused = androidPause; iosDebuggerSessions.paused = iosPause
+  await sessions.shutdown(); await rm(directory, { recursive: true, force: true })
+}
+
+// Confirmed detach and process-exit evidence are required for cleanup success.
+const { IOSWorker } = await import('../../../src/debugger/ios-worker.js')
+let transportClosed = 0
+const disconnected = new IOSWorker({ call: async () => { throw new Error('transport lost') }, close: async () => { transportClosed++ } }, () => false)
+await assert.rejects(disconnected.close(), /DEBUGGER_CLEANUP_FAILED/)
+assert.equal(transportClosed, 1)
+const exited = new IOSWorker({ call: async () => { throw new Error('must not need detach') }, close: async () => {} }, () => true)
+await exited.close()
+const confirmed = new IOSWorker({ call: async () => ({ detached: true }), close: async () => {} }, () => false)
+await confirmed.close()
+console.log('PASS iOS cleanup requires confirmed release; worker exit alone is insufficient')

package/test/unit/debugger/lldb-worker.py

@@ -0,0 +1,166 @@
+"""Platform-independent regression checks for the optional LLDB worker."""
+import pathlib
+import sys
+import types
+
+root = pathlib.Path(__file__).resolve().parents[3] / 'src/debugger/lldb'
+sys.path.insert(0, str(root))
+lldb = types.SimpleNamespace(eStateInvalid=0, eStateStopped=5, eStateExited=10, eStateDetached=9,
+                            eStopReasonNone=1, eStopReasonInvalid=0, eStopReasonBreakpoint=3)
+sys.modules['lldb'] = lldb
+import worker
+from inspection import Inspection
+from breakpoints import Breakpoints
+
+# Independent pause, idle and absolute expiry cannot be extended by heartbeats.
+w = object.__new__(worker.Worker)
+clock = [100.0]
+worker.time.monotonic = lambda: clock[0]
+w.created, w.activity, w.paused_at = 0, 100, 40
+assert w.expired() == 'pause_limit'
+w.paused_at = None
+clock[0] = 400
+assert w.expired() == 'idle_limit'
+w.activity = 1800
+clock[0] = 1800
+assert w.expired() == 'session_limit'
+
+# An internal transition with an empty thread list must not create a pause epoch.
+i = Inspection()
+p = types.SimpleNamespace(GetNumThreads=lambda: 0, GetState=lambda: 5, GetSelectedThread=lambda: types.SimpleNamespace(IsValid=lambda: False))
+assert i.stopped(p) is None
+assert i.stop_id is None
+for method, args in [(i.thread, {'stopId': 'old', 'threadId': 'old'}),
+                     (i.locals, {'stopId': 'old', 'frameId': 'old'})]:
+    try:
+        method(args)
+        raise AssertionError('Stale reference accepted')
+    except ValueError as error:
+        assert str(error) == 'DEBUGGER_STALE_REFERENCE'
+
+# Exact source-line resolver must never request nearest-code relocation.
+class Entry:
+    def IsValid(self): return True
+    def GetFileSpec(self): return '/tmp/App.swift'
+    def GetLine(self): return 13
+class Location:
+    def GetAddress(self): return types.SimpleNamespace(GetLineEntry=lambda: Entry())
+    def SetEnabled(self, enabled): self.enabled = enabled
+class Breakpoint:
+    def __init__(self): self.location = Location()
+    def __iter__(self): return iter([self.location])
+    def GetID(self): return 1
+class Target:
+    def __init__(self): self.deleted = False; self.bp = Breakpoint()
+    def BreakpointCreateByLocation(self, *args):
+        assert args[-1] is False
+        return self.bp
+    def BreakpointDelete(self, identity): self.deleted = True
+    def FindCompileUnits(self, source): return types.SimpleNamespace(GetSize=lambda: 1)
+lldb.SBFileSpec = lambda source: source
+lldb.SBFileSpecList = list
+t = Target()
+b = Breakpoints(t)
+r = b.set({'sourceFile': '/tmp/App.swift', 'line': 12})
+assert r['status'] == 'rejected'
+assert t.bp.location.enabled is False and t.deleted
+
+# Polling must consume events before reading the process snapshot.
+trace = []
+class Listener:
+    def GetNextEvent(self, event): trace.append('consume'); return False
+class Process:
+    def GetState(self): trace.append('state'); return 6
+w.debugger = types.SimpleNamespace(GetListener=lambda: Listener())
+w.process, w.terminal = Process(), False
+lldb.SBEvent = object
+w.poll()
+assert trace == ['consume', 'state']
+
+# EOF cleanup must release an actual target, never call Kill or expression APIs.
+w.attached = True
+w.inspection = Inspection()
+w.breakpoints = types.SimpleNamespace(clear=lambda: None)
+w.process = types.SimpleNamespace(IsValid=lambda: True, GetState=lambda: 5,
+    Detach=lambda: types.SimpleNamespace(Success=lambda: True))
+assert w.detach() == {'detached': True}
+assert w.terminal
+print('PASS LLDB worker expiry, transient stops, stale references, exact lines, events and detach')
+
+# Static Swift bool decoding must preserve boolean meaning without formatters.
+lldb.eNoDynamicValues, lldb.eTypeIsScalar, lldb.eTypeIsInteger, lldb.eTypeIsFloat = 0, 1, 2, 4
+class BoolValue:
+    def GetNonSyntheticValue(self): return self
+    def GetName(self): return 'cancelled'
+    def GetTypeName(self): return 'Swift.Bool'
+    def GetError(self): return types.SimpleNamespace(Success=lambda: True)
+    def GetType(self): return types.SimpleNamespace(GetTypeFlags=lambda: 0)
+    def GetValue(self): return '1'
+    def GetChildMemberWithName(self, name):
+        assert name == '_value'
+        return types.SimpleNamespace(GetNonSyntheticValue=lambda: self)
+    def IsValid(self): return True
+values = types.SimpleNamespace(GetSize=lambda: 1, GetValueAtIndex=lambda index: BoolValue())
+i.stop_id = '00000000-0000-0000-0000-000000000001'
+i.frames['frame'] = types.SimpleNamespace(GetVariables=lambda *args: values)
+assert i.locals({'stopId': i.stop_id, 'frameId': 'frame'})['locals'][0]['value'] == 'true'
+
+# Reference summaries are stable within a stop and never expose the pointer.
+pointer = types.SimpleNamespace(GetValue=lambda: '0x1234')
+first = i.object_identity(pointer, 'Controller')
+assert first == i.object_identity(pointer, 'Controller') and '1234' not in first
+i.stop_id = '00000000-0000-0000-0000-000000000002'
+assert first != i.object_identity(pointer, 'Controller')
+
+# Repeated stack pages reuse references and cannot grow beyond the stop cap.
+import inspection
+original_location = inspection.location
+inspection.location = lambda frame: {'source_file': '/tmp/App.swift', 'line': 1}
+try:
+    i.invalidate()
+    i.stop_id = '00000000-0000-0000-0000-000000000001'
+    i.threads['thread'] = types.SimpleNamespace(GetNumFrames=lambda: 1001, GetFrameAtIndex=lambda index: object())
+    args = {'stopId': i.stop_id, 'threadId': 'thread', 'limit': 100}
+    assert i.stack(args)['frames'][0]['frame_id'] == i.stack(args)['frames'][0]['frame_id']
+    for offset in range(0, 1000, 100): i.stack({**args, 'offset': offset})
+    assert len(i.frames) == 1000
+    i.threads['other'] = i.threads['thread']
+    result = i.stack({**args, 'threadId': 'other'})
+    assert result['frames'] == [] and result['truncated']
+finally:
+    inspection.location = original_location
+print('PASS static bool decoding, opaque identities and bounded stable frame references')
+
+# Error-reporting StepInto requires LLDB's UINT32_MAX sentinel, not line zero.
+lldb.LLDB_INVALID_LINE_NUMBER, lldb.eOnlyDuringStepping = 4294967295, 0
+lldb.SBError = lambda: types.SimpleNamespace(Success=lambda: True)
+class StepThread:
+    def StepInto(self, target, end_line, error, run_mode):
+        assert target is None and end_line == 4294967295
+w.terminal = False
+w.inspection = Inspection()
+w.inspection.stop_id = 'stop'
+w.inspection.threads['thread'] = StepThread()
+w.process = types.SimpleNamespace(GetState=lambda: 5)
+assert w.command({'command': 'step', 'stopId': 'stop', 'threadId': 'thread', 'kind': 'into'}) == {'resumed': True}
+assert w.inspection.stop_id is None
+print('PASS LLDB step error overload uses the documented invalid-line sentinel')
+
+# Signals and exceptions must not be misrepresented as completed source steps.
+lldb.eStopReasonPlanComplete, lldb.eStopReasonSignal, lldb.eStopReasonException = 8, 5, 6
+lldb.eStopReasonWatchpoint, lldb.eStopReasonExec = 4, 7
+assert inspection.stop_reason(types.SimpleNamespace(GetStopReason=lambda: 5)) == 'signal'
+assert inspection.stop_reason(types.SimpleNamespace(GetStopReason=lambda: 6)) == 'exception'
+assert inspection.stop_reason(types.SimpleNamespace(GetStopReason=lambda: 8)) == 'step'
+assert inspection.stop_reason(types.SimpleNamespace(GetStopReason=lambda: 99)) == 'unknown'
+print('PASS LLDB stop reasons preserve signal/exception versus step evidence')
+
+# Losing a previously owned process handle cannot prove detach or resume.
+w.attached = True
+w.process = types.SimpleNamespace(IsValid=lambda: False)
+try:
+    w.detach()
+    raise AssertionError('Lost process handle incorrectly confirmed detach')
+except ValueError as error:
+    assert str(error) == 'DEBUGGER_WORKER_FAILED'
+print('PASS lost process handles preserve cleanup uncertainty')

package/test/unit/debugger/lldb-worker.test.ts

@@ -0,0 +1,10 @@
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+const result = spawnSync('python3', ['-B', fileURLToPath(new URL('./lldb-worker.py', import.meta.url))], { encoding: 'utf8', timeout: 15000 })
+if ((result.error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT') {
+  console.log('UNRUN optional LLDB Python worker checks: python3 is unavailable')
+} else {
+  assert.equal(result.status, 0, result.stderr || result.error?.message)
+  console.log(result.stdout.trim())
+}