mobile-debug-mcp 0.34.0 → 0.36.0

package/test/fixtures/coroutine-app/MainActivity.kt

@@ -0,0 +1,100 @@
+package dev.mobiledebugmcp.coroutinefixture
+
+import android.app.Activity
+import android.os.Bundle
+import android.widget.Button
+import android.widget.LinearLayout
+import android.widget.TextView
+import java.util.concurrent.Executors
+import kotlinx.coroutines.*
+
+class MainActivity : Activity() {
+  private val first = Executors.newSingleThreadExecutor { Thread(it, "fixture-first") }.asCoroutineDispatcher()
+  private val second = Executors.newSingleThreadExecutor { Thread(it, "fixture-second") }.asCoroutineDispatcher()
+  private val scope = CoroutineScope(SupervisorJob() + first)
+  private var gate = CompletableDeferred<Unit>()
+  private var job: Job? = null
+  private lateinit var status: TextView
+
+  override fun onCreate(saved: Bundle?) {
+    super.onCreate(saved)
+    val layout = LinearLayout(this)
+    layout.orientation = LinearLayout.VERTICAL
+    layout.setPadding(0, 160, 0, 0)
+    status = TextView(this)
+    status.text = "Coroutine ready"
+    layout.addView(status)
+    fun button(label: String, action: () -> Unit) {
+      val button = Button(this)
+      button.text = label
+      button.setOnClickListener { action() }
+      layout.addView(button)
+    }
+    button("Complete run") { start(false) }
+    button("Cancellation run") { start(true) }
+    button("Release gate") { gate.complete(Unit) }
+    button("Cancel job") { job?.cancel() }
+    setContentView(layout)
+  }
+
+  private fun show(text: String) { runOnUiThread { status.text = text } }
+
+  private fun start(cancel: Boolean) {
+    if (job?.isActive == true) { show("Coroutine busy"); return }
+    gate = CompletableDeferred()
+    job = scope.launch {
+      if (cancel) cancelWork() else completeWork()
+    }
+  }
+
+  private suspend fun completeWork() {
+    val firstThread = Thread.currentThread().name
+    val known = 42
+    check(firstThread == "fixture-first") // BREAK_BEFORE
+    // Queued on the same single-thread executor: runs only after gate.await yields.
+    first.executor.execute { show("Coroutine waiting") }
+    gate.await() // BREAK_SUSPEND
+    val after = known + 1 // BREAK_AFTER
+    withContext(second) {
+      val dispatcherThread = Thread.currentThread().name
+      val nested = async { helper(after) } // BREAK_DISPATCH
+      check(dispatcherThread == "fixture-second")
+      val answer = nested.await()
+      show("Coroutine result $answer") // BREAK_RESULT
+    }
+  }
+
+  private fun helper(value: Int): Int {
+    val result = increment(value) // BREAK_HELPER
+    return result // BREAK_HELPER_RETURN
+  }
+
+  private fun increment(value: Int): Int {
+    val result = value + 1 // BREAK_INCREMENT
+    return result // BREAK_INCREMENT_RETURN
+  }
+
+  private suspend fun cancelWork() = coroutineScope {
+    val child = launch(second) {
+      try {
+        // The child must yield at gate.await before this queued work can run.
+        second.executor.execute { show("Cancellation waiting") }
+        gate.await()
+        error("Cancelled child must not cross gate")
+      } finally {
+        show("Cancellation finally") // BREAK_CANCEL
+      }
+    }
+    try { child.join() } finally {
+      withContext(NonCancellable) { child.cancelAndJoin() }
+      show("Coroutine cancelled")
+    }
+  }
+
+  override fun onDestroy() {
+    scope.cancel()
+    first.close()
+    second.close()
+    super.onDestroy()
+  }
+}

package/test/fixtures/coroutine-app/README.md

@@ -0,0 +1,48 @@
+# Isolated Android coroutine debugger fixture
+
+Separate disposable package `dev.mobiledebugmcp.coroutinefixture`; the runner
+refuses to replace an existing installation. No server dependency, debug agent,
+automatic download or production app instrumentation is introduced.
+
+Requires Node 22+, JDK 17, Android SDK platform/build-tools 36, Kotlin JVM compiler
+and matching stdlib 2.0.21, and kotlinx-coroutines-core-jvm 1.9.0. Provide local
+paths explicitly:
+
+```sh
+export JAVA_HOME=/path/to/jdk-17
+export MCP_KOTLINC=/path/to/kotlin/bin/kotlinc
+export MCP_KOTLIN_STDLIB=/path/to/kotlin/lib/kotlin-stdlib.jar
+export MCP_COROUTINES_CORE=/path/to/kotlinx-coroutines-core-jvm-1.9.0.jar
+npm run build
+MCP_COROUTINE_DEVICE=emulator-5554 npx tsx test/device/automated/debugger/coroutine.android.test.ts
+```
+
+`npm run test:device` discovers the runner and reports **UNRUN** unless
+`MCP_COROUTINE_DEVICE` is set. A configured run with missing prerequisites fails;
+it cannot silently pass. Do not run other fixture journeys concurrently on the
+same serial. A physical device must be selected explicitly and reported separately.
+
+The source owns two named single-thread dispatcher executors, an explicit gate,
+nested async work and a cancellation/finally path. Readiness is posted by work
+queued on the same single-thread executor behind the coroutine, so the runner
+releases or cancels only after the gate wait has yielded. UI controls release the
+gate only after debugger resume. Compiler line/variable tables are captured for generated
+continuation classes as well as ordinary methods. The assessment compares existing
+MCP stops, thread stacks and shallow locals; none represents a reconstructed
+logical coroutine stack. A bounded step attempt is recorded as an observation,
+not a promise to follow work across suspension. Source breakpoints are tested
+independently as a workaround.
+
+The runner checks pause guards, old frame rejection, event-wait cancellation,
+completion/cancellation UI recovery and owned ADB forward cleanup. Finally it
+removes its package and temporary build/signing output. The overall JSON PASS is
+emitted only after cleanup; cleanup failures emit JSON FAIL and reject the run.
+Forward comparisons filter the selected serial and sort entries, so another
+device changing its forwards does not fail this journey. SIGKILL/host loss cannot
+execute finally; inspect outstanding sessions/packages manually after such loss.
+Local output includes synthetic fixture values, source/APK/server/dependency hashes
+and compiler metadata. Redirect stdout/stderr to an intentional local evidence
+file; no data is uploaded automatically.
+
+See the [accepted specification](../../../docs/specs/030-android-coroutine-validation/spec.md)
+and [implementation/verification record](../../../docs/specs/030-android-coroutine-validation/plan.md).

package/test/fixtures/coroutine-app/build.ts

@@ -0,0 +1,35 @@
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+export const coroutineAppId = 'dev.mobiledebugmcp.coroutinefixture'
+export function buildCoroutineFixture() {
+  if (!process.env.MCP_COROUTINES_CORE) throw new Error('MCP_COROUTINES_CORE must identify kotlinx-coroutines-core-jvm.jar')
+  if (!process.env.MCP_KOTLIN_STDLIB) throw new Error('MCP_KOTLIN_STDLIB must identify the matching Kotlin standard-library jar')
+  const source = path.dirname(fileURLToPath(import.meta.url))
+  const directory = mkdtempSync(path.join(tmpdir(), 'mcp-coroutine-fixture-'))
+  const java = process.env.JAVA_HOME ?? (existsSync('/Applications/Android Studio.app/Contents/jbr/Contents/Home') ? '/Applications/Android Studio.app/Contents/jbr/Contents/Home' : undefined)
+  const run = (cmd: string, args: string[]) => execFileSync(cmd, args, { cwd: directory, encoding: 'utf8', stdio: 'pipe', timeout: 120000 })
+  const sdk = process.env.ANDROID_HOME ?? path.join(process.env.HOME!, 'Library/Android/sdk')
+  const tools = path.join(sdk, 'build-tools/36.0.0')
+  const androidJar = path.join(sdk, 'platforms/android-36/android.jar')
+  const jdk = (name: string) => java ? path.join(java, 'bin', name) : name
+  try {
+    mkdirSync(path.join(directory, 'classes'))
+    writeFileSync(path.join(directory, 'AndroidManifest.xml'), `<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="${coroutineAppId}" android:versionCode="1" android:versionName="1.0"><uses-sdk android:minSdkVersion="26" android:targetSdkVersion="36"/><application android:debuggable="true" android:label="Debugger fixture" android:theme="@android:style/Theme.Material.Light.NoActionBar"><activity android:name=".MainActivity" android:exported="true"><intent-filter><action android:name="android.intent.action.MAIN"/><category android:name="android.intent.category.LAUNCHER"/></intent-filter></activity></application></manifest>`)
+    run(process.env.MCP_KOTLINC ?? 'kotlinc', ['-no-stdlib', '-no-reflect', '-jvm-target', '1.8', '-classpath', [androidJar, process.env.MCP_KOTLIN_STDLIB!, process.env.MCP_COROUTINES_CORE!].join(path.delimiter), '-d', 'classes', path.join(source, 'MainActivity.kt')])
+    run(jdk('jar'), ['cf', 'classes.jar', '-C', 'classes', '.'])
+    run(path.join(tools, 'd8'), ['--min-api', '26', '--lib', androidJar, '--output', directory, 'classes.jar', process.env.MCP_KOTLIN_STDLIB!, process.env.MCP_COROUTINES_CORE!])
+    run(path.join(tools, 'aapt2'), ['link', '-I', androidJar, '--manifest', 'AndroidManifest.xml', '-o', 'unsigned.apk'])
+    run('zip', ['-q', 'unsigned.apk', 'classes.dex'])
+    run(path.join(tools, 'zipalign'), ['-f', '4', 'unsigned.apk', 'aligned.apk'])
+    run(jdk('keytool'), ['-genkeypair', '-keystore', 'fixture.jks', '-storepass', 'android', '-keypass', 'android', '-alias', 'fixture', '-dname', 'CN=Readiness Fixture', '-keyalg', 'RSA', '-validity', '365'])
+    const artifact = path.join(directory, 'Debugger.apk')
+    run(path.join(tools, 'apksigner'), ['sign', '--ks', 'fixture.jks', '--ks-pass', 'pass:android', '--out', artifact, 'aligned.apk'])
+    return { artifact, directory }
+  } catch (error) {
+    rmSync(directory, { recursive: true, force: true })
+    throw error
+  }
+}

package/test/fixtures/debugger-app/MainActivity.java

@@ -23,8 +23,29 @@ public class MainActivity extends Activity {
       try { Class.forName("dev.mobiledebugmcp.debugfixture.NoLocals").getDeclaredMethod("work").invoke(null); }
       catch (Exception e) { status.setText("Metadata failed"); }
     }); layout.addView(noLocals);
+    addLevelControl(layout);
     setContentView(layout);
   }
+  void addLevelControl(LinearLayout layout) {
+    TextView level = new TextView(this);
+    level.setGravity(android.view.Gravity.CENTER);
+    level.setText("25 %"); layout.addView(level);
+    android.widget.SeekBar slider = new android.widget.SeekBar(this);
+    slider.setMax(100); slider.setProgress(25);
+    slider.setContentDescription("Fixture level");
+    slider.setOnSeekBarChangeListener(new android.widget.SeekBar.OnSeekBarChangeListener() {
+      public void onProgressChanged(android.widget.SeekBar view, int progress, boolean fromUser) { level.setText(progress + " %"); }
+      public void onStartTrackingTouch(android.widget.SeekBar view) {}
+      public void onStopTrackingTouch(android.widget.SeekBar view) {}
+    });
+    layout.addView(slider);
+    LinearLayout range = new LinearLayout(this);
+    TextView minimum = new TextView(this); minimum.setText("0 %");
+    TextView maximum = new TextView(this); maximum.setText("100 %"); maximum.setGravity(android.view.Gravity.RIGHT);
+    range.addView(minimum, new LinearLayout.LayoutParams(0, 80, 1));
+    range.addView(maximum, new LinearLayout.LayoutParams(0, 80, 1));
+    layout.addView(range);
+  }
   void calculate(int seed) {
     int known = seed + 35;
     String longText = new String(new char[300]).replace('\0', 'x');

package/test/fixtures/debugger-app/MainActivity.kt

@@ -0,0 +1,32 @@
+package dev.mobiledebugmcp.debugfixture
+
+import android.app.Activity
+import android.os.Bundle
+import android.widget.Button
+import android.widget.LinearLayout
+import android.widget.TextView
+
+class MainActivity : Activity() {
+  private lateinit var status: TextView
+
+  override fun onCreate(saved: Bundle?) {
+    super.onCreate(saved)
+    val layout = LinearLayout(this)
+    layout.orientation = LinearLayout.VERTICAL
+    layout.setPadding(0, 160, 0, 0)
+    status = TextView(this)
+    status.text = "Kotlin ready"
+    layout.addView(status)
+    val button = Button(this)
+    button.text = "Kotlin calculate"
+    button.setOnClickListener { calculate(7) }
+    layout.addView(button)
+    setContentView(layout)
+  }
+
+  private fun calculate(seed: Int) {
+    val known = seed + 35 // BREAK_KOTLIN_BEFORE
+    val answer = known + 1 // BREAK_KOTLIN_KNOWN
+    status.text = "Kotlin result $answer" // BREAK_KOTLIN_RESULT
+  }
+}

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

@@ -1,5 +1,7 @@
 # Isolated Android debugger fixture
 
+[Contributing](../../../CONTRIBUTING.md) · [Documentation](../../../docs/README.md)
+
 Package `dev.mobiledebugmcp.debugfixture`, built with `android:debuggable=true`
 and Java source/line/local metadata. Calculate exposes `known=42`, an increment
 call for into/over/out stepping, and a visible `Result 43` after resume. Late class
@@ -11,3 +13,53 @@ Build helper uses SDK platform/build-tools 36, the existing direct javac/D8/aapt
 pattern, ephemeral signing material and temporary output. It does not modify other
 apps or display settings. The automated journey installs/removes only this fixture
 and checks session-owned ADB forwards. See [debugger tools](../../../docs/tools/debugger.md).
+
+## Kotlin locals validation
+
+The opt-in Kotlin variant compiles `MainActivity.kt` instead of the Java sources
+into the same disposable package. Do not run the variants concurrently on one
+device. It requires a Kotlin JVM compiler (`MCP_KOTLINC`, or `kotlinc` on PATH),
+the matching standard-library jar (`MCP_KOTLIN_STDLIB`), and a compatible JDK.
+Kotlin 2.0.21 with JDK 17 was used for the recorded validation. The fixture does
+not add Gradle, download a compiler, or change the server's dependencies.
+
+```sh
+npm run build
+export JAVA_HOME=/path/to/jdk-17
+export MCP_KOTLINC=/path/to/kotlin/bin/kotlinc
+export MCP_KOTLIN_STDLIB=/path/to/kotlin/lib/kotlin-stdlib.jar
+MCP_KOTLIN_DEVICE=emulator-5554 npx tsx test/device/automated/debugger/kotlin.android.test.ts
+```
+
+The compiler retains its default line/local metadata; D8 runs without shrinking
+or obfuscation. The runner checks the class-file local-variable scope tables,
+then reads `seed=7` before `known` is initialized, `known=42` before `answer` is
+initialized, and `answer=43` afterward through MCP. Old references must fail as
+stale. Resume/detach is followed by a fresh hierarchy assertion for
+`Kotlin result 43`; exact owned forwards, package and temporary files are cleaned
+up. Build failures also remove their temporary directory.
+
+`npm run test:device` includes this journey only when `MCP_KOTLIN_DEVICE` is set;
+otherwise it reports **UNRUN** explicitly. The existing Java journey separately
+covers absent variable tables. A local outside its compiler scope and missing
+metadata are different conditions; an empty ART table alone proves neither.
+See the [dated validation record](../../../docs/specs/029-kotlin-locals-validation/report.md).
+
+## Interaction regression journey
+
+The same isolated fixture is also used by the [interaction device check](../../device/automated/interact/interaction.android.test.ts)
+for clickable waits, stored handles, selector taps, visibility and enabled-state
+assertions. Run it after building the server:
+
+```sh
+MCP_INTERACTION_DEVICE=emulator-5554 npx tsx test/device/automated/interact/interaction.android.test.ts
+```
+
+It also runs in `npm run test:device` when `MCP_INTERACTION_DEVICE` or
+`MCP_DEBUGGER_DEVICE` selects a device. Fixture journeys run sequentially and
+remove their own package and temporary build outputs. This check does not attach
+a debugger or modify another app's data.
+
+The interaction journey also exercises a labelled native SeekBar. It adjusts
+from 25 toward 75, checks convergence within tolerance, and confirms the displayed
+value with a fresh hierarchy assertion. The same fixture cleanup applies.

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

@@ -1,10 +1,11 @@
 import { execFileSync } from 'node:child_process'
-import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 export const debuggerAppId = 'dev.mobiledebugmcp.debugfixture'
-export function buildDebuggerFixture() {
+export function buildDebuggerFixture(kotlin = false) {
+  if (kotlin && !process.env.MCP_KOTLIN_STDLIB) throw new Error('MCP_KOTLIN_STDLIB must identify the matching Kotlin standard-library jar')
   const source = path.dirname(fileURLToPath(import.meta.url))
   const directory = mkdtempSync(path.join(tmpdir(), 'mcp-debugger-fixture-'))
   const java = process.env.JAVA_HOME ?? (existsSync('/Applications/Android Studio.app/Contents/jbr/Contents/Home') ? '/Applications/Android Studio.app/Contents/jbr/Contents/Home' : undefined)
@@ -13,17 +14,26 @@ export function buildDebuggerFixture() {
   const tools = path.join(sdk, 'build-tools/36.0.0')
   const androidJar = path.join(sdk, 'platforms/android-36/android.jar')
   const jdk = (name: string) => java ? path.join(java, 'bin', name) : name
-  mkdirSync(path.join(directory, 'classes'))
-  writeFileSync(path.join(directory, 'AndroidManifest.xml'), `<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="${debuggerAppId}" android:versionCode="1" android:versionName="1.0"><uses-sdk android:minSdkVersion="26" android:targetSdkVersion="36"/><application android:debuggable="true" android:label="Debugger fixture" android:theme="@android:style/Theme.Material.Light.NoActionBar"><activity android:name=".MainActivity" android:exported="true"><intent-filter><action android:name="android.intent.action.MAIN"/><category android:name="android.intent.category.LAUNCHER"/></intent-filter></activity></application></manifest>`)
-  run(jdk('javac'), ['-g', '--release', '8', '-classpath', androidJar, '-d', 'classes', path.join(source, 'MainActivity.java')])
-  run(jdk('javac'), ['-g:source,lines', '--release', '8', '-classpath', androidJar, '-d', 'classes', path.join(source, 'NoLocals.java')])
-  run(jdk('jar'), ['cf', 'classes.jar', '-C', 'classes', '.'])
-  run(path.join(tools, 'd8'), ['--lib', androidJar, '--output', directory, 'classes.jar'])
-  run(path.join(tools, 'aapt2'), ['link', '-I', androidJar, '--manifest', 'AndroidManifest.xml', '-o', 'unsigned.apk'])
-  run('zip', ['-q', 'unsigned.apk', 'classes.dex'])
-  run(path.join(tools, 'zipalign'), ['-f', '4', 'unsigned.apk', 'aligned.apk'])
-  run(jdk('keytool'), ['-genkeypair', '-keystore', 'fixture.jks', '-storepass', 'android', '-keypass', 'android', '-alias', 'fixture', '-dname', 'CN=Readiness Fixture', '-keyalg', 'RSA', '-validity', '365'])
-  const artifact = path.join(directory, 'Debugger.apk')
-  run(path.join(tools, 'apksigner'), ['sign', '--ks', 'fixture.jks', '--ks-pass', 'pass:android', '--out', artifact, 'aligned.apk'])
-  return { artifact, directory }
+  try {
+    mkdirSync(path.join(directory, 'classes'))
+    writeFileSync(path.join(directory, 'AndroidManifest.xml'), `<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="${debuggerAppId}" android:versionCode="1" android:versionName="1.0"><uses-sdk android:minSdkVersion="26" android:targetSdkVersion="36"/><application android:debuggable="true" android:label="Debugger fixture" android:theme="@android:style/Theme.Material.Light.NoActionBar"><activity android:name=".MainActivity" android:exported="true"><intent-filter><action android:name="android.intent.action.MAIN"/><category android:name="android.intent.category.LAUNCHER"/></intent-filter></activity></application></manifest>`)
+    if (kotlin) {
+      run(process.env.MCP_KOTLINC ?? 'kotlinc', ['-no-stdlib', '-no-reflect', '-jvm-target', '1.8', '-classpath', [androidJar, process.env.MCP_KOTLIN_STDLIB!].join(path.delimiter), '-d', 'classes', path.join(source, 'MainActivity.kt')])
+    } else {
+      run(jdk('javac'), ['-g', '--release', '8', '-classpath', androidJar, '-d', 'classes', path.join(source, 'MainActivity.java')])
+      run(jdk('javac'), ['-g:source,lines', '--release', '8', '-classpath', androidJar, '-d', 'classes', path.join(source, 'NoLocals.java')])
+    }
+    run(jdk('jar'), ['cf', 'classes.jar', '-C', 'classes', '.'])
+    run(path.join(tools, 'd8'), ['--lib', androidJar, '--output', directory, 'classes.jar', ...(kotlin ? [process.env.MCP_KOTLIN_STDLIB!] : [])])
+    run(path.join(tools, 'aapt2'), ['link', '-I', androidJar, '--manifest', 'AndroidManifest.xml', '-o', 'unsigned.apk'])
+    run('zip', ['-q', 'unsigned.apk', 'classes.dex'])
+    run(path.join(tools, 'zipalign'), ['-f', '4', 'unsigned.apk', 'aligned.apk'])
+    run(jdk('keytool'), ['-genkeypair', '-keystore', 'fixture.jks', '-storepass', 'android', '-keypass', 'android', '-alias', 'fixture', '-dname', 'CN=Readiness Fixture', '-keyalg', 'RSA', '-validity', '365'])
+    const artifact = path.join(directory, 'Debugger.apk')
+    run(path.join(tools, 'apksigner'), ['sign', '--ks', 'fixture.jks', '--ks-pass', 'pass:android', '--out', artifact, 'aligned.apk'])
+    return { artifact, directory }
+  } catch (error) {
+    rmSync(directory, { recursive: true, force: true })
+    throw error
+  }
 }

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/README.md

@@ -1,5 +1,7 @@
 # Interaction latency fixture
 
+[Contributing](../../../CONTRIBUTING.md) · [Documentation](../../../docs/README.md)
+
 An offline native Android fixture, version 1.0. It requires Android SDK platform 36,
 build-tools 36.0.0 and JDK 21. The harness builds and signs it using those installed
 tools; no Gradle dependency download is needed.

package/test/fixtures/readiness-app/README.md

@@ -1,5 +1,7 @@
 # Readiness fixture
 
+[Contributing](../../../CONTRIBUTING.md) · [Documentation](../../../docs/README.md)
+
 Offline native Android/iOS simulator apps used only for explicit readiness
 verification. Ready stays visible while Show loader starts a 12-second loader;
 completion hides the loader and changes its status to Done. No permissions,

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/coroutine-lifecycle.test.ts

@@ -0,0 +1,43 @@
+import assert from 'node:assert/strict'
+import { deviceForwards, reportAfterCleanup } from '../../device/automated/debugger/coroutine-lifecycle.js'
+
+const baseline = deviceForwards('emulator-5554 tcp:2 jdwp:20\nemulator-5554 tcp:1 jdwp:10\nother-device tcp:3 jdwp:30', 'emulator-5554')
+assert.deepEqual(deviceForwards('other-device tcp:4 jdwp:40\nemulator-5554  tcp:1  jdwp:10\nemulator-5554 tcp:2 jdwp:20\n', 'emulator-5554'), baseline)
+assert.notDeepEqual(deviceForwards('emulator-5554 tcp:1 jdwp:10', 'emulator-5554'), baseline)
+assert.deepEqual(deviceForwards('emulator-55540 tcp:1 jdwp:10', 'emulator-5554'), [])
+
+const order: string[] = []
+await reportAfterCleanup(async () => { order.push('work'); return 42 }, async () => { order.push('cleanup') }, (status, result) => {
+  order.push(status)
+  assert.equal(result, 42)
+})
+assert.deepEqual(order, ['work', 'cleanup', 'PASS'])
+
+// Reproduce the review bug: cleanup rejects after work succeeds or fails.
+// The runner must reject and emit only FAIL in both cases.
+for (const workFails of [false, true]) {
+  const records: string[] = []
+  const cleanupError = new Error('cleanup')
+  const journeyError = new Error('journey')
+  await assert.rejects(reportAfterCleanup(async () => {
+    if (workFails) throw journeyError
+    return 42
+  }, async () => { throw cleanupError }, (status, evidence, error) => {
+    records.push(status)
+    assert.equal(evidence, undefined)
+    if (workFails) {
+      assert.ok(error instanceof AggregateError)
+      assert.deepEqual(error.errors, [journeyError, cleanupError])
+    } else assert.equal(error, cleanupError)
+  }), error => workFails ? error instanceof AggregateError : error === cleanupError)
+  assert.deepEqual(records, ['FAIL'])
+}
+let cleaned = false
+const workError = new Error('journey')
+await assert.rejects(reportAfterCleanup(async () => { throw workError }, async () => { cleaned = true }, (status, evidence, error) => {
+  assert.equal(cleaned, true)
+  assert.equal(status, 'FAIL')
+  assert.equal(evidence, undefined)
+  assert.equal(error, workError)
+}), error => error === workError)
+console.log('PASS coroutine assessment: cleanup precedes PASS; work/cleanup failures report FAIL; forwards scoped and sorted')