mobile-debug-mcp 0.35.0 → 0.36.0

package/test/device/automated/observe/ios-system-trace.smoke.ts

@@ -0,0 +1,119 @@
+import { verifyIosTraceShutdown } from '../../../helpers/ios-trace-shutdown.js'
+import assert from 'node:assert/strict'
+import { execFileSync } from 'node:child_process'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { createHash } from 'node:crypto'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { buildReadinessFixture, readinessAppId } from '../../../fixtures/readiness-app/build.js'
+
+const inputEnvironment = () => Object.fromEntries(['IDB_COMPANION','MCP_IDB_PATH','IDB_PATH','XCRUN_PATH'].flatMap(key=>process.env[key]?[[key,process.env[key]!]]:[]))
+async function run() {
+  const deviceId=process.env.IOS_SYSTEM_TRACE_DEVICE
+  if(process.env.SKIP_DEVICE_TESTS==='1'||!deviceId){console.log('iOS system trace smoke: UNRUN (set IOS_SYSTEM_TRACE_DEVICE to an explicit simulator UDID)');return}
+  assert.equal(process.platform,'darwin')
+  const command=(args:string[])=>execFileSync('xcrun',args,{encoding:'utf8',timeout:120000,stdio:'pipe'})
+  const sims=JSON.parse(command(['simctl','list','devices','--json']))
+  const device=Object.values(sims.devices).flat().find((d:any)=>d.udid===deviceId) as any
+  assert.ok(device?.isAvailable,'Explicit available simulator required')
+  let booted=false,installed=false,fixture:ReturnType<typeof buildReadinessFixture>|undefined
+  const client=new Client({name:'ios-system-trace-smoke',version:'1.0.0'})
+  const transport=new StdioClientTransport({command:process.execPath,args:['dist/server.js'],stderr:'pipe',env:inputEnvironment()})
+  const owned=new Set<string>(),artifacts:string[]=[],checks:Record<string,unknown>={}
+  let journeyFailure: Error | undefined
+  const target={platform:'ios',deviceId},traceTarget={...target,appId:readinessAppId}
+  const call=async(name:string,args:Record<string,unknown>)=>{
+    const result=await client.callTool({name,arguments:args},undefined,{timeout:180000})
+    return JSON.parse((result.content as any[]).find(c=>c.type==='text').text)
+  }
+  const start=async(durationMs=90000)=>{
+    const r=await call('start_system_trace',{...traceTarget,durationMs})
+    if(r.trace_id&&r.cleanup?.status!=='complete')owned.add(r.trace_id)
+    assert.equal(r.state,'recording',JSON.stringify(r));assert.ok(r.recording_ready_at_ms>=r.capture_started_at_ms)
+    return r
+  }
+  const stop=async(id:string)=>{
+    const r=await call('stop_system_trace',{traceId:id})
+    if(r.artifact)artifacts.push(r.artifact.path)
+    assert.equal(r.state,'completed',JSON.stringify(r));assert.equal(r.cleanup.status,'complete')
+    assert.equal(r.artifact.validation.readable,true);owned.delete(id);return r
+  }
+  try{
+    if(device.state!=='Booted'){command(['simctl','boot',deviceId]);booted=true;command(['simctl','bootstatus',deviceId,'-b'])}
+    let preexisting=false
+    try{const existing=command(['simctl','get_app_container',deviceId,readinessAppId,'app']).trim();await fs.stat(existing);preexisting=true}catch{/* absent or stale simulator registration */}
+    assert.equal(preexisting,false,'Refuse to replace a pre-existing fixture')
+    fixture=buildReadinessFixture('ios');command(['simctl','install',deviceId,fixture.artifact]);installed=true
+    command(['simctl','launch',deviceId,readinessAppId])
+    await client.connect(transport)
+    const cap=await call('get_system_trace_capabilities',traceTarget)
+    assert.equal(cap.supported,true,JSON.stringify(cap));assert.equal(cap.prerequisites.permissions,'unknown')
+    const tree=await call('get_ui_tree',target)
+    assert.ok(tree.elements.some((e:any)=>e.text==='Ready'),'Fixture must be semantically visible')
+    assert.ok(tree.elements.some((e:any)=>e.text==='Show loader'),'Fixture button must be semantically visible')
+    const recording=await start()
+    const baselineJourney=await call('run_journey',{...target,systemTraceId:recording.trace_id,steps:[{id:'ready',type:'assert',timeoutMs:10000,assertion:{kind:'element_visible',selector:{text:'Ready'}}}]})
+    assert.equal(baselineJourney.success,true,JSON.stringify(baselineJourney));checks.linked_baseline='PASS; Ready asserted via built-server journey'
+    const journeySubmitted=Date.now()
+    const journey=await call('run_journey',{...target,systemTraceId:recording.trace_id,steps:[
+      {id:'show-loader',type:'tap',selector:{text:'Show loader'},verificationMode:'none'},
+      {id:'done',type:'assert',timeoutMs:30000,assertion:{kind:'element_visible',selector:{text:'Done'}}}
+    ]})
+    if (!journey.success) journeyFailure = new Error(`Traced fixture input journey failed at ${journey.stopped_at_step_id}; ${journey.steps[0].result?.failure_code}`)
+    else assert.equal(journey.steps[1].status,'passed')
+    assert.equal(journey.evidence.trace_context.trace_id,recording.trace_id)
+    assert.equal(journey.steps[0].result.evidence.trace_context.trace_id,recording.trace_id)
+    assert.equal(journey.system_trace.coverage,'covered');assert.ok(recording.recording_ready_at_ms<=journeySubmitted)
+    const completed=await stop(recording.trace_id)
+    assert.equal(completed.device.id,deviceId);assert.equal(completed.app_id,readinessAppId)
+    assert.deepEqual(completed.correlation_ids,[baselineJourney.evidence.correlation_id,journey.evidence.correlation_id]);assert.ok(completed.artifact.validation.sample_rows>0)
+    checks.journey={status:journey.success?'PASS':'FAIL',trace_id:recording.trace_id,correlation_id:journey.evidence.correlation_id,
+      ready_at_ms:recording.recording_ready_at_ms,journey_submitted_at_ms:journeySubmitted,outcome:journey.success?'Done visible via journey UI-tree assertion':journeyFailure?.message,
+      sample_rows:completed.artifact.validation.sample_rows,artifact_bytes:completed.artifact.size_bytes,warnings:completed.warnings}
+    const stale=await call('run_journey',{...target,systemTraceId:recording.trace_id,steps:[{id:'must-not-tap',type:'tap',selector:{text:'Show loader'},verificationMode:'none'}]})
+    assert.equal(stale.error.code,'TRACE_NOT_FOUND')
+    const unchanged=await call('expect_element_visible',{...target,selector:{text:journey.success?'Done':'Ready'},timeoutMs:10000})
+    assert.ok(unchanged.success||unchanged.visible||unchanged.status==='success',JSON.stringify(unchanged))
+    checks.stale_id='PASS; rejected tap left prior fixture label visible'
+    const cancelled=await start(30000),directory=cancelled.cleanup.remaining_resources[0]
+    const cancel=await call('cancel_system_trace',{traceId:cancelled.trace_id})
+    assert.equal(cancel.state,'cancelled');assert.equal(cancel.cleanup.status,'complete');assert.equal(cancel.artifact,null);owned.delete(cancelled.trace_id)
+    await assert.rejects(()=>fs.stat(directory),{code:'ENOENT'});checks.cancel='PASS'
+    const short=await start(5000)
+    let expired=short
+    for(let i=0;i<90&&expired.state==='recording';i++){
+      await new Promise(r=>setTimeout(r,500));expired=await call('get_system_trace_status',{traceId:short.trace_id})
+    }
+    if(expired.artifact)artifacts.push(expired.artifact.path)
+    assert.equal(expired.state,'completed',JSON.stringify(expired));assert.equal(expired.completion_reason,'duration_limit');assert.equal(expired.cleanup.status,'complete');owned.delete(short.trace_id);checks.expiry='PASS'
+    const failedRecording=await start(60000)
+    const failedJourney=await call('run_journey',{...target,systemTraceId:failedRecording.trace_id,steps:[{id:'missing',type:'assert',timeoutMs:1000,assertion:{kind:'element_visible',selector:{text:'impossible-trace-fixture-label'}}}]})
+    assert.equal(failedJourney.success,false)
+    assert.equal((await call('get_system_trace_status',{traceId:failedRecording.trace_id})).state,'recording')
+    await stop(failedRecording.trace_id);checks.failed_journey='PASS; failure retained capture for explicit stop'
+    await verifyIosTraceShutdown(traceTarget,inputEnvironment());checks.shutdown='PASS; owned recording and partial directory removed'
+    const live=command(['simctl','spawn',deviceId,'launchctl','list'])
+    assert.ok(live.includes(`UIKitApplication:${readinessAppId}[`),'Recorder cleanup must leave the fixture app running')
+    checks.app_survived_cleanup='PASS'
+    const hash=createHash('sha256')
+    for(const file of ['dist/server.js','dist/observe/system-trace.js','dist/observe/system-trace-router.js','dist/observe/ios-trace/native.js','dist/observe/ios-trace/sessions.js','dist/observe/ios-trace/process.js'])hash.update(await fs.readFile(file))
+    checks.status=journeyFailure?'FAIL':'PASS';checks.build_sha256=hash.digest('hex');checks.runtime=process.version;checks.device=deviceId;checks.server=client.getServerVersion()
+    checks.physical_device='UNRUN; unsupported initial matrix';checks.native_failure_injection='UNRUN on real target; deterministic unit tests separate'
+    checks.input_toolchain=process.env.IDB_COMPANION?'Explicit test companion via IDB_COMPANION; see investigation.md':'Repository default idb companion'
+    if(journeyFailure) throw journeyFailure
+  }catch(error){checks.status='FAIL';checks.error=String(error);throw error}finally{
+    const errors:string[]=[]
+    for(const id of owned)try{const r=await call('cancel_system_trace',{traceId:id});if(r.artifact&&!artifacts.includes(r.artifact.path))artifacts.push(r.artifact.path);if(r.cleanup?.status!=='complete')errors.push(id)}catch{errors.push(id)}
+    await client.close()
+    for(const file of artifacts)await fs.rm(path.dirname(file),{recursive:true,force:true})
+    if(installed)command(['simctl','uninstall',deviceId,readinessAppId])
+    if(fixture)await fs.rm(fixture.directory,{recursive:true,force:true})
+    if(booted)command(['simctl','shutdown',deviceId])
+    checks.cleanup={trace_errors:errors,fixture_removed:installed,simulator_shutdown:booted,host_artifacts_removed:true}
+    console.log(JSON.stringify(checks))
+    if(process.env.IOS_SYSTEM_TRACE_EVIDENCE_PATH)await fs.writeFile(process.env.IOS_SYSTEM_TRACE_EVIDENCE_PATH,JSON.stringify(checks,null,2)+'\n')
+    assert.deepEqual(errors,[],'Trace cleanup failed')
+  }
+}
+run().catch(error=>{console.error(error);process.exitCode=1})

package/test/fixtures/contracts/tool-definitions.json

@@ -1,10 +1,35 @@
 [
   {
     "name": "get_debugger_capabilities",
-    "description": "Probe optional Android JDK/JDWP prerequisites and matching running debuggable processes; does not attach.",
+    "description": "Probe optional platform debugger prerequisites and matching running debuggable processes; does not attach.",
     "inputSchema": {
       "type": "object",
       "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "platform": {
+                "const": "ios"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "deviceId": {
+                "pattern": "^[A-Fa-f0-9]{8}(?:-[A-Fa-f0-9]{4}){3}-[A-Fa-f0-9]{12}$"
+              }
+            }
+          }
+        },
+        {
+          "not": {
+            "required": [
+              "expectedState"
+            ]
+          }
+        }
+      ],
       "required": [
         "platform",
         "deviceId",
@@ -22,7 +47,8 @@
         "platform": {
           "type": "string",
           "enum": [
-            "android"
+            "android",
+            "ios"
           ]
         },
         "deviceId": {
@@ -34,7 +60,7 @@
           "type": "string",
           "minLength": 1,
           "maxLength": 512,
-          "pattern": "^[A-Za-z][\\w]*(?:\\.[A-Za-z][\\w]*)+$"
+          "pattern": "^[A-Za-z][\\w-]*(?:\\.[A-Za-z][\\w-]*)+$"
         },
         "processId": {
           "type": "integer",
@@ -47,8 +73,32 @@
           "maximum": 30000,
           "default": 10000
         }
-      },
+      }
+    }
+  },
+  {
+    "name": "attach_debugger",
+    "description": "Attach an owned Android JDI or iOS simulator LLDB session. Requires an explicit device and debuggable app; choose processId when ambiguous. Stops suspend all app threads. Auto-detach: 60s paused, 5m idle, 30m total.",
+    "inputSchema": {
+      "type": "object",
+      "additionalProperties": false,
       "allOf": [
+        {
+          "if": {
+            "properties": {
+              "platform": {
+                "const": "ios"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "deviceId": {
+                "pattern": "^[A-Fa-f0-9]{8}(?:-[A-Fa-f0-9]{4}){3}-[A-Fa-f0-9]{12}$"
+              }
+            }
+          }
+        },
         {
           "not": {
             "required": [
@@ -56,15 +106,7 @@
             ]
           }
         }
-      ]
-    }
-  },
-  {
-    "name": "attach_debugger",
-    "description": "Attach an owned Android JDI session. Requires an explicit device and debuggable app; choose processId when ambiguous. Stops suspend all app threads. Auto-detach: 60s paused, 5m idle, 30m total.",
-    "inputSchema": {
-      "type": "object",
-      "additionalProperties": false,
+      ],
       "required": [
         "platform",
         "deviceId",
@@ -82,7 +124,8 @@
         "platform": {
           "type": "string",
           "enum": [
-            "android"
+            "android",
+            "ios"
           ]
         },
         "deviceId": {
@@ -94,7 +137,7 @@
           "type": "string",
           "minLength": 1,
           "maxLength": 512,
-          "pattern": "^[A-Za-z][\\w]*(?:\\.[A-Za-z][\\w]*)+$"
+          "pattern": "^[A-Za-z][\\w-]*(?:\\.[A-Za-z][\\w-]*)+$"
         },
         "processId": {
           "type": "integer",
@@ -107,16 +150,7 @@
           "maximum": 30000,
           "default": 10000
         }
-      },
-      "allOf": [
-        {
-          "not": {
-            "required": [
-              "expectedState"
-            ]
-          }
-        }
-      ]
+      }
     }
   },
   {
@@ -162,13 +196,34 @@
   },
   {
     "name": "set_debugger_breakpoint",
-    "description": "Set an exact binary-class and executable-source-line breakpoint; unloaded classes remain pending. No silent line relocation.",
+    "description": "Set an exact source breakpoint: Android className or iOS absolute sourceFile (exactly one), plus line; unloaded classes/images remain pending. No silent line relocation.",
     "inputSchema": {
       "type": "object",
       "additionalProperties": false,
+      "oneOf": [
+        {
+          "required": [
+            "className"
+          ],
+          "not": {
+            "required": [
+              "sourceFile"
+            ]
+          }
+        },
+        {
+          "required": [
+            "sourceFile"
+          ],
+          "not": {
+            "required": [
+              "className"
+            ]
+          }
+        }
+      ],
       "required": [
         "debugSessionId",
-        "className",
         "line"
       ],
       "properties": {
@@ -191,6 +246,12 @@
           "maxLength": 512,
           "pattern": "^[A-Za-z_$][\\w$]*(?:\\.[A-Za-z_$][\\w$]*)*$"
         },
+        "sourceFile": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "pattern": "^\\/[^\\0\\r\\n]+$"
+        },
         "line": {
           "type": "integer",
           "minimum": 0,
@@ -372,7 +433,7 @@
   },
   {
     "name": "get_debugger_locals",
-    "description": "Read at most 100 shallow locals. Sensitive values returned only on request; strings truncate at 256 characters. No evaluation or field traversal.",
+    "description": "Read at most 100 shallow locals. Sensitive values returned only on request; strings truncate at 256 characters; iOS aggregates return type summaries. No evaluation or field traversal.",
     "inputSchema": {
       "type": "object",
       "additionalProperties": false,
@@ -534,7 +595,7 @@
   },
   {
     "name": "detach_debugger",
-    "description": "Dispose the owned debugger connection, release owned suspension and remove its exact forward. Idempotent; retries incomplete cleanup.",
+    "description": "Dispose the owned debugger connection, release owned suspension and remove its owned transport. Idempotent; retries incomplete cleanup.",
     "inputSchema": {
       "type": "object",
       "additionalProperties": false,
@@ -575,7 +636,7 @@
   },
   {
     "name": "get_system_trace_capabilities",
-    "description": "Probe Android Perfetto prerequisites without recording. Device-wide system tracing is optional; iOS is unsupported.",
+    "description": "Probe Android Perfetto or iOS Instruments prerequisites without recording. iOS requires explicit booted simulator deviceId; reports template matrix and unknown profiling permissions.",
     "inputSchema": {
       "type": "object",
       "additionalProperties": false,
@@ -593,8 +654,57 @@
         "deviceId": {
           "type": "string",
           "minLength": 1
+        },
+        "appId": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-zA-Z0-9._-]+$",
+          "description": "iOS only: running development app bundle identifier; required for iOS start."
+        },
+        "template": {
+          "type": "string",
+          "enum": [
+            "System Trace",
+            "Time Profiler",
+            "Animation Hitches",
+            "Hangs"
+          ],
+          "description": "iOS only. Default Time Profiler; initial simulator support is Time Profiler only."
         }
       },
+      "oneOf": [
+        {
+          "properties": {
+            "platform": {
+              "const": "android"
+            }
+          },
+          "not": {
+            "anyOf": [
+              {
+                "required": [
+                  "appId"
+                ]
+              },
+              {
+                "required": [
+                  "template"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "properties": {
+            "platform": {
+              "const": "ios"
+            }
+          },
+          "required": [
+            "deviceId"
+          ]
+        }
+      ],
       "allOf": [
         {
           "not": {
@@ -608,7 +718,7 @@
   },
   {
     "name": "start_system_trace",
-    "description": "Start bounded Android Perfetto recording, returning an owned trace_id. Run an existing journey with systemTraceId, then stop to retrieve a local artifact or cancel to discard. Device-wide traces may contain sensitive system annotations; no upload.",
+    "description": "Start bounded Android Perfetto or iOS simulator Time Profiler recording, returning an owned trace_id after readiness. iOS requires explicit deviceId and running appId. Run an existing journey with systemTraceId, then stop to retrieve a local artifact or cancel to discard. Traces can contain sensitive system metadata, logs and paths; local user-managed retention, no upload.",
     "inputSchema": {
       "type": "object",
       "additionalProperties": false,
@@ -627,6 +737,22 @@
           "type": "string",
           "minLength": 1
         },
+        "appId": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-zA-Z0-9._-]+$",
+          "description": "iOS only: running development app bundle identifier; required for iOS start."
+        },
+        "template": {
+          "type": "string",
+          "enum": [
+            "System Trace",
+            "Time Profiler",
+            "Animation Hitches",
+            "Hangs"
+          ],
+          "description": "iOS only. Default Time Profiler; initial simulator support is Time Profiler only."
+        },
         "durationMs": {
           "type": "integer",
           "minimum": 1000,
@@ -634,6 +760,40 @@
           "default": 30000
         }
       },
+      "oneOf": [
+        {
+          "properties": {
+            "platform": {
+              "const": "android"
+            }
+          },
+          "not": {
+            "anyOf": [
+              {
+                "required": [
+                  "appId"
+                ]
+              },
+              {
+                "required": [
+                  "template"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "properties": {
+            "platform": {
+              "const": "ios"
+            }
+          },
+          "required": [
+            "deviceId",
+            "appId"
+          ]
+        }
+      ],
       "allOf": [
         {
           "not": {
@@ -673,7 +833,7 @@
   },
   {
     "name": "stop_system_trace",
-    "description": "Stop owned capture gracefully and retrieve a local Perfetto artifact. Retry after a transfer/cleanup failure.",
+    "description": "Stop owned capture gracefully and retrieve a local Perfetto file or validated Instruments .trace bundle. Retry after a transfer/cleanup failure.",
     "inputSchema": {
       "type": "object",
       "additionalProperties": false,

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/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()}
+}