mobile-debug-mcp 0.34.0 → 0.35.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/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/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')

package/test/unit/debugger/diagnostic-sessions.test.ts

@@ -0,0 +1,67 @@
+import assert from 'node:assert/strict'
+import { DebuggerSessions } from '../../../src/debugger/sessions.js'
+import type { DebugNative, DebugTarget } from '../../../src/debugger/android.js'
+import { DebuggerError, type WorkerEvent } from '../../../src/debugger/worker.js'
+import { diagnostic } from '../../../src/debugger/diagnostics.js'
+const target: DebugTarget = { app_id: 'test.app', process_name: 'test.app', pid: 1, uid: 2, start_identity: '3' }
+let removed = 0
+let closed = 0
+let cleanupFails = false
+let mode = ''
+const callbacks = new Map<string, (event: WorkerEvent) => void>()
+const native: DebugNative = {
+  candidates: async () => [target], identity: async () => target, forward: async () => 12345,
+  removeForward: async () => { if (cleanupFails) throw new Error('private'); removed++ }
+}
+const sessions = new DebuggerSessions(native, async emit => {
+  callbacks.set(mode, emit)
+  return {
+    call: async command => {
+      if (command === 'attach' && mode === 'attach') throw new DebuggerError('DEBUGGER_WORKER_FAILED', diagnostic('attach', 'connection_refused'))
+      if (command === 'step') {
+        emit({ event: 'worker_failed', diagnostic: diagnostic('ipc', 'invalid_message') })
+        throw new DebuggerError('DEBUGGER_WORKER_FAILED', diagnostic('ipc', 'invalid_message'))
+      }
+      return {}
+    },
+    close: async () => { closed++ }
+  }
+}, async () => ({ java: 'unused', directory: 'unused' }))
+try {
+  mode = 'attach'
+  const failed = await sessions.attach('one', 'test.app')
+  assert.equal(failed.error.code, 'DEBUGGER_WORKER_FAILED')
+  assert.deepEqual(failed.error.diagnostic, diagnostic('attach', 'connection_refused'))
+  assert.equal(failed.cleanup.status, 'complete')
+  assert.equal(closed, 1); assert.equal(removed, 1)
+  mode = 'first'
+  const first = await sessions.attach('one', 'test.app')
+  mode = 'second'
+  const second = await sessions.attach('two', 'test.app')
+  callbacks.get('first')!({ event: 'stopped', stop_id: 'stop' })
+  await assert.rejects(sessions.command(first.debug_session_id, 'step', { stopId: 'stop' }), /DEBUGGER_WORKER_FAILED/)
+  const terminal = await sessions.command(first.debug_session_id, 'state')
+  assert.deepEqual(terminal.error.diagnostic, diagnostic('ipc', 'invalid_message'), 'event/rejection race retains primary evidence after cleanup')
+  assert.equal(terminal.cleanup.status, 'complete')
+  await assert.rejects(sessions.command(first.debug_session_id, 'stack', {}), (e: unknown) => e instanceof DebuggerError && e.code === 'DEBUGGER_DISCONNECTED' && e.diagnostic?.reason === 'invalid_message')
+  assert.equal((await sessions.command(second.debug_session_id, 'state')).success, true, 'other device is isolated')
+  const aborted = new AbortController(); aborted.abort()
+  await assert.rejects(sessions.command(second.debug_session_id, 'events', { signal: aborted.signal }), (e: unknown) => e instanceof DebuggerError && e.diagnostic?.stage === 'command' && e.diagnostic.reason === 'cancelled')
+  cleanupFails = true
+  const incomplete = await sessions.command(second.debug_session_id, 'detach')
+  assert.equal(incomplete.error.code, 'DEBUGGER_CLEANUP_FAILED')
+  assert.deepEqual(incomplete.error.diagnostic, diagnostic('cleanup', 'operation_failed'))
+  cleanupFails = false
+  assert.equal((await sessions.command(second.debug_session_id, 'detach')).cleanup.status, 'complete')
+  mode = 'shutdown'
+  const shutdown = await sessions.attach('three', 'test.app')
+  await sessions.shutdown()
+  assert.equal(sessions.summary(shutdown.debug_session_id).cleanup.status, 'complete')
+} finally { await sessions.shutdown() }
+const badProbes = new DebuggerSessions({ ...native, candidates: async () => { throw new Error('private-token') } }, undefined,
+  async () => { throw new DebuggerError('DEBUGGER_UNSUPPORTED', diagnostic('compilation', 'operation_failed')) })
+const probe = await badProbes.capabilities('one', 'test.app')
+assert.equal(probe.success, true); assert.equal(probe.supported, false)
+assert.deepEqual(probe.diagnostics, [diagnostic('compilation', 'operation_failed'), diagnostic('target_resolution', 'unknown')])
+assert.ok(!JSON.stringify(probe).includes('private-token'))
+console.log('PASS diagnostic session retention/races, cleanup retry, isolation, shutdown and ordered capability diagnostics')

package/test/unit/debugger/diagnostics.test.ts

@@ -0,0 +1,80 @@
+import assert from 'node:assert/strict'
+import { mkdtemp, writeFile, rm } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { diagnostic, stages, reasons, classify, parseDiagnostic } from '../../../src/debugger/diagnostics.js'
+import { DebuggerError, JdiWorker, withDebuggerBudget, type WorkerEvent } from '../../../src/debugger/worker.js'
+import { parseWorkerMessage } from '../../../src/debugger/protocol.js'
+import { handleDebugger } from '../../../src/server/handlers/debugger-handlers.js'
+
+const secret = 'PRIVATE_LOCALS_TOKEN_/private/path'
+for (const stage of stages) for (const reason of reasons) {
+  const value = diagnostic(stage, reason)
+  assert.ok(Buffer.byteLength(JSON.stringify(value)) <= 512)
+  assert.ok(value.recovery.length <= 240 && /^[\x00-\x7f]*$/.test(value.recovery))
+  assert.deepEqual(Object.keys(value), ['stage', 'reason', 'recovery'])
+}
+assert.deepEqual(parseDiagnostic({ stage: 'attach', reason: 'connection_refused', recovery: secret, raw: secret }), diagnostic('attach', 'connection_refused'))
+assert.equal(classify(new Error(secret), 'attach', 'DEBUGGER_ATTACH_FAILED').diagnostic?.reason, 'unknown')
+assert.equal(classify(new DebuggerError('DEBUGGER_STALE_REFERENCE'), 'command', 'DEBUGGER_WORKER_FAILED').diagnostic, undefined)
+for (const hostile of [secret, { stage: secret, reason: 'unknown' }, { stage: 'attach', reason: secret }]) {
+  assert.throws(() => parseWorkerMessage({ id: 1, error: { code: 'DEBUGGER_WORKER_FAILED', diagnostic: hostile } }), /INVALID_WORKER_DIAGNOSTIC/)
+}
+assert.throws(() => parseWorkerMessage({ id: 1, error: { code: secret } }), /INVALID_WORKER_ERROR/)
+const cancelled = new AbortController(); cancelled.abort()
+const response = await handleDebugger('get_debugger_state', { debugSessionId: 'absent' }, cancelled.signal)
+assert.equal(response.isError, true)
+const payload = JSON.parse(response.content[0].text)
+assert.equal(payload.error.code, 'DEBUGGER_CANCELLED')
+assert.deepEqual(payload.error.diagnostic, diagnostic('unknown', 'cancelled'))
+assert.equal((await handleDebugger('get_debugger_state', {})).isError, true)
+
+const directory = await mkdtemp(path.join(os.tmpdir(), 'debugger-diagnostics-test-'))
+let index = 0
+async function worker(body: string, onEvent: (event: WorkerEvent) => void = () => {}) {
+  const file = path.join(directory, `worker-${index++}`)
+  await writeFile(file, `#!${process.execPath}\n${body}\n`, { mode: 0o700 })
+  return new JdiWorker(file, directory, onEvent)
+}
+async function fails(body: string, stage: string, reason: string) {
+  const w = await worker(body)
+  try {
+    await assert.rejects(w.call('attach', {}, 3000), (error: unknown) => {
+      assert.ok(error instanceof DebuggerError)
+      assert.equal(error.code, 'DEBUGGER_WORKER_FAILED')
+      assert.deepEqual(error.diagnostic, diagnostic(stage as typeof stages[number], reason as typeof reasons[number]))
+      assert.ok(!JSON.stringify(error).includes(secret))
+      return true
+    })
+  } finally { await w.close() }
+}
+try {
+  const missing = new JdiWorker(path.join(directory, 'missing'), directory, () => {})
+  try { await assert.rejects(missing.call('attach'), (e: unknown) => e instanceof DebuggerError && e.diagnostic?.reason === 'spawn_failed') } finally { await missing.close() }
+  await fails(`process.stderr.write(${JSON.stringify(secret)}); process.exit(7)`, 'worker_start', 'process_exited')
+  await fails(`process.stdout.write(${JSON.stringify(secret + '\n')}); setInterval(()=>{},1000)`, 'ipc', 'invalid_message')
+  await fails(`process.stdout.write('x'.repeat(1048577)+'\\n'); setInterval(()=>{},1000)`, 'ipc', 'message_limit')
+  const attach = await worker(`process.stdin.once('data', data => { const {id}=JSON.parse(data); console.log(JSON.stringify({id,error:{code:'DEBUGGER_WORKER_FAILED',diagnostic:{stage:'attach',reason:'connection_refused',raw:${JSON.stringify(secret)}}}})) })`)
+  try { await assert.rejects(attach.call('attach'), (e: unknown) => e instanceof DebuggerError && e.diagnostic?.reason === 'connection_refused') } finally { await attach.close() }
+  let ready = () => {}
+  const readyPromise = new Promise<void>(resolve => { ready = resolve })
+  const brokenPipe = await worker(`require('node:fs').closeSync(0); console.log(JSON.stringify({event:'ready'})); setInterval(()=>{},1000)`, () => ready())
+  try {
+    await readyPromise
+    await assert.rejects(brokenPipe.call('state'), (e: unknown) => e instanceof DebuggerError && e.diagnostic?.reason === 'write_failed')
+  } finally { await brokenPipe.close() }
+  const afterReply = await worker(`process.stdin.once('data',data=>{const {id}=JSON.parse(data); console.log(JSON.stringify({id,result:{}})); setTimeout(()=>process.exit(7),100)})`)
+  try {
+    await afterReply.call('state')
+    await assert.rejects(afterReply.call('state'), (e: unknown) => e instanceof DebuggerError && e.diagnostic?.stage === 'ipc' && e.diagnostic.reason === 'process_exited')
+  } finally { await afterReply.close() }
+  const idle = await worker('process.stdin.resume()')
+  try {
+    await assert.rejects(idle.call('stack', {}, 50), (e: unknown) => e instanceof DebuggerError && e.diagnostic?.stage === 'command' && e.diagnostic.reason === 'timeout')
+    const controller = new AbortController()
+    const call = withDebuggerBudget(1000, controller.signal, () => idle.call('attach'))
+    controller.abort()
+    await assert.rejects(call, (e: unknown) => e instanceof DebuggerError && e.diagnostic?.stage === 'attach' && e.diagnostic.reason === 'cancelled')
+  } finally { await idle.close() }
+} finally { await rm(directory, { recursive: true, force: true }) }
+console.log('PASS diagnostic bounds/privacy, strict IPC, real worker spawn/exit/malformed/oversize, attach failure, timeout/cancel and MCP wrapping')

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

@@ -38,6 +38,10 @@ try {
   assert.equal(journey.steps[1].success, false)
   assert.equal(journey.steps[1].result.failure_code, 'DEBUGGER_PAUSED')
   assert.equal(calls, 2, 'no action queued or retried after pause')
+  _setDeviceListersForTests({ listAndroidDevices: async () => { throw new Error('resolution unavailable') } })
+  const failedResolution = payload(await handleToolCall('tap', { platform: 'android', deviceId: 'fixture', x: 1, y: 1 }))
+  assert.equal(failedResolution.error.tool, 'tap')
+  assert.match(failedResolution.error.message, /resolution unavailable/, 'resolution errors retain the MCP error envelope')
   console.log('PASS debugger readiness without UI acquisition, device scoping, dispatch guard, mid-journey pause preservation')
 } finally {
   debuggerSessions.paused = originalPause; debuggerSessions.hasActiveSessions = originalActive

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

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { mkdtemp, mkdir, 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-jdk-'))
+const secret = 'SECRET_COMPILER_OUTPUT'
+const run = async () => {
+  const code = `import {prepareWorker} from './src/debugger/worker.ts'; try {await prepareWorker(); process.exitCode=1} catch(e) {console.log(JSON.stringify({code:e.code,diagnostic:e.diagnostic}))}`
+  const { stdout, stderr } = await exec(process.execPath, ['--import', 'tsx', '--input-type=module', '-e', code], {
+    env: { ...process.env, ANDROID_STUDIO_JDK: directory }, timeout: 10000
+  })
+  assert.ok(!stdout.includes(secret)); assert.ok(!stderr.includes(secret))
+  return JSON.parse(stdout)
+}
+try {
+  await mkdir(path.join(directory, 'bin'))
+  const java = path.join(directory, 'bin', 'java')
+  await writeFile(java, `#!${process.execPath}\nconsole.error('openjdk version "17.0.1"');`, { mode: 0o700 })
+  await writeFile(path.join(directory, 'bin', 'javac'), `#!${process.execPath}\nconsole.error('${secret}');process.exit(1)`, { mode: 0o700 })
+  const compile = await run()
+  assert.equal(compile.code, 'DEBUGGER_UNSUPPORTED')
+  assert.equal(compile.diagnostic.stage, 'compilation'); assert.equal(compile.diagnostic.reason, 'operation_failed')
+  // Discovery succeeds; the actual bounded version subprocess then fails.
+  await writeFile(java, `#!${process.execPath}\nconst fs=require('node:fs');const marker=${JSON.stringify(path.join(directory, 'seen'))};if(fs.existsSync(marker)){console.error('${secret}');process.exit(1)}fs.writeFileSync(marker,'');console.error('openjdk version "17.0.1"');`, { mode: 0o700 })
+  const prerequisite = await run()
+  assert.equal(prerequisite.code, 'DEBUGGER_ATTACH_FAILED')
+  assert.equal(prerequisite.diagnostic.stage, 'prerequisite'); assert.equal(prerequisite.diagnostic.reason, 'unavailable')
+} finally { await rm(directory, { recursive: true, force: true }) }
+console.log('PASS isolated fake-JDK compilation/prerequisite classification without compiler output leakage')