mobile-debug-mcp 0.33.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

@@ -0,0 +1,67 @@
+package dev.mobiledebugmcp.debugfixture;
+import android.app.Activity;
+import android.os.Bundle;
+import android.widget.Button;
+import android.widget.LinearLayout;
+import android.widget.TextView;
+
+public class MainActivity extends Activity {
+  TextView status;
+  @Override public void onCreate(Bundle saved) {
+    super.onCreate(saved);
+    LinearLayout layout = new LinearLayout(this); layout.setOrientation(1); layout.setPadding(0, 160, 0, 0);
+    status = new TextView(this); status.setText("Ready"); layout.addView(status);
+    Button button = new Button(this); button.setText("Calculate");
+    button.setOnClickListener(v -> calculate(7)); layout.addView(button);
+    Button late = new Button(this); late.setText("Late class");
+    late.setOnClickListener(v -> {
+      try { Class.forName("dev.mobiledebugmcp.debugfixture.LateWork").getDeclaredMethod("work").invoke(null); }
+      catch (Exception e) { status.setText("Late failed"); }
+    }); layout.addView(late);
+    Button noLocals = new Button(this); noLocals.setText("No locals");
+    noLocals.setOnClickListener(v -> {
+      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');
+    Object object = new Object();
+    int answer = increment(known); // BREAK_CALCULATE
+    status.setText("Result " + answer); // BREAK_RESULT
+  }
+  int increment(int value) {
+    int result = value + 1; // BREAK_INCREMENT
+    return result;
+  }
+}
+
+class LateWork {
+  public static void work() {
+    int local = 99; // BREAK_LATE
+    android.util.Log.i("DebugFixture", "late " + local);
+  }
+}

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/NoLocals.java

@@ -0,0 +1,7 @@
+package dev.mobiledebugmcp.debugfixture;
+public class NoLocals {
+  public static void work() {
+    int hidden = 5; // BREAK_NO_LOCALS
+    android.util.Log.i("DebugFixture", "metadata " + hidden);
+  }
+}

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

@@ -0,0 +1,65 @@
+# 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
+loads a second class reflectively to check pending source breakpoints. NoLocals
+is compiled with source/line tables and no variable tables to verify explicit ART
+metadata uncertainty.
+
+Build helper uses SDK platform/build-tools 36, the existing direct javac/D8/aapt2
+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

@@ -0,0 +1,39 @@
+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 debuggerAppId = 'dev.mobiledebugmcp.debugfixture'
+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)
+  const run = (cmd: string, args: string[]) => execFileSync(cmd, args, { cwd: directory, encoding: 'utf8', stdio: 'pipe' })
+  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="${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/helpers/perfetto.ts

@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict'
+
+// Minimal local protobuf reader for format/content evidence, not trace analysis.
+// Field numbers: google/perfetto protos/perfetto/trace/{trace,trace_packet}.proto
+// and trace/ftrace/{ftrace_event_bundle,ftrace_event}.proto. Unknown fields skipped.
+export function protobufFields(bytes: Buffer): Array<{ field: number; wire: number; value: Buffer | bigint }> {
+  let offset = 0
+  const result: Array<{ field: number; wire: number; value: Buffer | bigint }> = []
+  function varint() {
+    let value = 0n
+    for (let shift = 0n; shift < 70n; shift += 7n) {
+      assert.ok(offset < bytes.length, 'Truncated protobuf varint')
+      const byte = bytes[offset++]
+      value |= BigInt(byte & 127) << shift
+      if (!(byte & 128)) return value
+    }
+    throw new Error('Oversized protobuf varint')
+  }
+  while (offset < bytes.length) {
+    const key = Number(varint()), field = Math.floor(key / 8), wire = key % 8
+    assert.ok(field > 0)
+    let value: Buffer | bigint
+    if (wire === 0) value = varint()
+    else {
+      const length = wire === 2 ? Number(varint()) : wire === 1 ? 8 : wire === 5 ? 4 : -1
+      assert.ok(Number.isSafeInteger(length) && length >= 0 && length <= bytes.length - offset, 'Invalid protobuf length/wire')
+      value = bytes.subarray(offset, offset + length); offset += length
+    }
+    result.push({ field, wire, value })
+  }
+  return result
+}
+export function inspectPerfetto(bytes: Buffer, duration: number) {
+  const root = protobufFields(bytes)
+  assert.ok(root.length > 0)
+  assert.ok(root.every(f => f.field === 1 && f.wire === 2), 'Trace.packet must be repeated length-delimited messages')
+  const packets = root.map(f => protobufFields(f.value as Buffer))
+  const config = packets.flat().find(f => f.field === 33 && f.wire === 2)
+  assert.ok(config, 'Missing TracePacket.trace_config')
+  assert.equal(protobufFields(config.value as Buffer).find(f => f.field === 3)?.value, BigInt(duration))
+  const bundles = packets.flat().filter(f => f.field === 1 && f.wire === 2).map(f => protobufFields(f.value as Buffer))
+  let events = 0, compactBundles = 0
+  for (const bundle of bundles) {
+    for (const f of bundle) {
+      if (f.field === 2 && f.wire === 2) {
+        const event = protobufFields(f.value as Buffer)
+        assert.ok(event.some(e => e.field === 1 && e.wire === 0), 'FtraceEvent timestamp missing')
+        events++
+      }
+      if (f.field === 4 && f.wire === 2) {
+        assert.ok(protobufFields(f.value as Buffer).some(e => [1, 7].includes(e.field) && e.wire === 2))
+        compactBundles++
+      }
+    }
+  }
+  assert.ok(events + compactBundles > 0, 'No captured kernel/scheduler events')
+  return { packets: packets.length, ftrace_bundles: bundles.length, events, compact_sched_bundles: compactBundles,
+    validation: 'local protobuf structure, trace config duration and timestamped ftrace/compact scheduler content; not full Perfetto analysis' }
+}

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')