mobile-debug-mcp 0.33.0 → 0.34.0

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

@@ -0,0 +1,104 @@
+import { execCmd } from '../../../../src/utils/exec.js'
+import { getAdbCmd } from '../../../../src/utils/android/utils.js'
+import { createHash } from 'node:crypto'
+import assert from 'node:assert/strict'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { inspectPerfetto } from '../../../helpers/perfetto.js'
+
+async function run() {
+  if (process.env.SKIP_DEVICE_TESTS === '1') { console.log('System trace smoke: SKIPPED (SKIP_DEVICE_TESTS=1)'); return }
+  const client = new Client({ name: 'system-trace-smoke', version: '1.0.0' })
+  const transport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
+  const parse = (r: any) => JSON.parse(r.content[0].text)
+  const call = async (name: string, args: Record<string, unknown>) => parse(await client.callTool({ name, arguments: args }, undefined, { timeout: 120000 }))
+  const owned: string[] = [], artifacts: string[] = []
+  try {
+    await client.connect(transport)
+    const devices = await call('list_devices', {})
+    const device = devices.devices.find((d: any) => d.platform === 'android' && d.simulator)
+    assert.ok(device, 'A running Android emulator is required')
+    const target = { platform: 'android', deviceId: device.id }
+    const cap = await call('get_system_trace_capabilities', target)
+    assert.equal(cap.supported, true, JSON.stringify(cap))
+    const fixtureLaunch = await call('start_app', { ...target, appId: 'com.android.settings', verificationMode: 'none', responseMode: 'compact' })
+    assert.equal(fixtureLaunch.success, true)
+    const baseline = await call('get_ui_tree', { ...target, responseMode: 'debug' })
+    const settingsNode = baseline.elements?.find((e: any) => e.visible && e.resourceId?.startsWith('com.android.settings:id/'))
+    assert.ok(settingsNode, 'Fresh baseline must contain a visible Settings-owned UI resource')
+    const settingsSelector = { resource_id: settingsNode.resourceId }
+    const start = await call('start_system_trace', { ...target, durationMs: 30000 })
+    owned.push(start.trace_id)
+    assert.equal(start.state, 'recording', JSON.stringify(start))
+    const journey = await call('run_journey', { ...target, systemTraceId: start.trace_id,
+      steps: [
+        { id: 'settings', type: 'start_app', appId: 'com.android.settings', verificationMode: 'none' },
+        { id: 'settings-visible', type: 'assert', timeoutMs: 10000, assertion: { kind: 'element_visible', selector: settingsSelector } }
+      ] })
+    assert.equal(journey.success, true, JSON.stringify(journey))
+    assert.equal(journey.steps[1].status, 'passed', 'The baseline Settings-owned UI element must remain semantically visible')
+    assert.equal(journey.evidence.trace_context.trace_id, start.trace_id)
+    assert.equal(journey.steps[0].result.evidence.trace_context.trace_id, start.trace_id)
+    assert.equal(journey.system_trace.coverage, 'covered')
+    const stop = await call('stop_system_trace', { traceId: start.trace_id })
+    if (stop.artifact) artifacts.push(stop.artifact.path)
+    assert.equal(stop.state, 'completed', JSON.stringify(stop)); assert.equal(stop.cleanup.status, 'complete')
+    assert.deepEqual(stop.correlation_ids, [journey.evidence.correlation_id])
+    const content = inspectPerfetto(await fs.readFile(stop.artifact.path), 30000)
+    assert.equal((await call('stop_system_trace', { traceId: start.trace_id })).artifact.path, stop.artifact.path)
+    const rejected = await call('run_journey', { ...target, systemTraceId: start.trace_id,
+      steps: [{ id: 'must-not-launch', type: 'start_app', appId: 'com.invalid.trace.smoke' }] })
+    assert.equal(rejected.error.code, 'TRACE_NOT_FOUND')
+    const cancel = await call('start_system_trace', { ...target, durationMs: 30000 })
+    owned.push(cancel.trace_id)
+    const cancelled = await call('cancel_system_trace', { traceId: cancel.trace_id })
+    assert.equal(cancelled.state, 'cancelled', JSON.stringify(cancelled))
+    assert.equal((await call('get_system_trace_status', { traceId: cancel.trace_id })).artifact, null)
+    const short = await call('start_system_trace', { ...target, durationMs: 1001 })
+    owned.push(short.trace_id)
+    assert.equal(short.state, 'recording', JSON.stringify(short))
+    let ended = short
+    for (let i = 0; i < 30 && ended.state === 'recording'; i++) {
+      await new Promise(resolve => setTimeout(resolve, 200))
+      ended = await call('get_system_trace_status', { traceId: short.trace_id })
+    }
+    if (ended.artifact) artifacts.push(ended.artifact.path)
+    assert.equal(ended.state, 'completed', JSON.stringify(ended)); assert.equal(ended.completion_reason, 'duration_limit')
+    const durationContent = inspectPerfetto(await fs.readFile(ended.artifact.path), 1001)
+    const shutdownClient = new Client({ name: 'system-trace-shutdown-smoke', version: '1.0.0' })
+    const shutdownTransport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
+    let shutdownTrace: any
+    let shutdownDiagnostics = ''
+    try {
+      await shutdownClient.connect(shutdownTransport)
+      shutdownTransport.stderr?.on('data', data => { shutdownDiagnostics += String(data) })
+      shutdownTrace = parse(await shutdownClient.callTool({ name: 'start_system_trace', arguments: { ...target, durationMs: 30000 } }, undefined, { timeout: 120000 }))
+      assert.equal(shutdownTrace.state, 'recording')
+    } finally { await shutdownClient.close() }
+    const remote = shutdownTrace.cleanup.remaining_resources.find((r: string) => r.startsWith('/data/misc/perfetto-traces/mcp-'))
+    assert.ok(remote)
+    const absent = await execCmd(getAdbCmd(), ['-s', device.id, 'shell', 'test', '!', '-e', remote], { timeout: 10000 })
+    assert.equal(absent.exitCode, 0, `Shutdown must stop and remove its owned device capture: ${shutdownTrace.trace_id}; ${shutdownDiagnostics}; ${absent.stderr}`)
+    const buildHash = createHash('sha256')
+    for (const file of ['dist/server.js', 'dist/observe/system-trace.js', 'dist/observe/system-trace-android.js', 'dist/server/tool-handlers.js', 'dist/observe/evidence.js']) buildHash.update(await fs.readFile(file))
+    const report = { status: 'PASS', build_sha256: buildHash.digest('hex'), runtime: process.version, server: client.getServerVersion(), device: device.id, osVersion: device.osVersion,
+      starting_state: 'System Settings fixture', journey: 'start Settings, assert baseline Settings-owned resource visible in UI tree; explicit trace association',
+      trace_id: start.trace_id, correlation_id: journey.evidence.correlation_id, phases: {
+        capture_started_at_ms: stop.capture_started_at_ms, capture_completed_at_ms: stop.capture_completed_at_ms },
+      artifact_bytes: stop.artifact.size_bytes, content, durationContent, cancel: 'PASS', expired_journey: 'PASS', active_shutdown: 'PASS',
+      cleanup: 'Device capture files removed; test host artifacts removed in finally. No settings or app data changed. Settings remains foreground.' }
+    console.log(JSON.stringify(report))
+    if (process.env.SYSTEM_TRACE_EVIDENCE_PATH) await fs.writeFile(process.env.SYSTEM_TRACE_EVIDENCE_PATH, JSON.stringify(report, null, 2) + '\n')
+  } finally {
+    const cleanupErrors: string[] = []
+    for (const traceId of owned) {
+      try { const r = await call('cancel_system_trace', { traceId }); if (r.artifact && !artifacts.includes(r.artifact.path)) artifacts.push(r.artifact.path); if (r.cleanup?.status !== 'complete') cleanupErrors.push(traceId) } catch { cleanupErrors.push(traceId) }
+    }
+    await client.close()
+    for (const file of artifacts) await fs.rm(path.dirname(file), { recursive: true, force: true })
+    assert.deepEqual(cleanupErrors, [], 'Owned trace cleanup failed')
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

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

@@ -0,0 +1,46 @@
+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);
+    setContentView(layout);
+  }
+  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/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,13 @@
+# Isolated Android debugger fixture
+
+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).

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

@@ -0,0 +1,29 @@
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, 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() {
+  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
+  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 }
+}

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

@@ -0,0 +1,46 @@
+import assert from 'node:assert/strict'
+import { debuggerSessions } from '../../../src/debugger/sessions.js'
+import { withDebuggerGuard, checkDebuggerGuard } from '../../../src/debugger/guard.js'
+import { handleToolCall } from '../../../src/server-core.js'
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { getAppReadiness } from '../../../src/observe/readiness-service.js'
+const originalPause = debuggerSessions.paused
+const originalActive = debuggerSessions.hasActiveSessions
+const originalTree = ToolsObserve.getUITreeHandler
+const originalWait = ToolsInteract.waitForUIHandler
+let paused = true
+const pause: any = { debug_session_id: 'session', target: { app_id: 'test.app', pid: 10 }, state: 'paused', captured_at_ms: 1000 }
+debuggerSessions.paused = device => paused && device === 'fixture' ? pause : null
+debuggerSessions.hasActiveSessions = () => true
+_setDeviceListersForTests({ listAndroidDevices: async () => [{ id: 'fixture', platform: 'android' } as any] })
+const payload = (response: any) => JSON.parse(response.content.find((c: any) => c.type === 'text').text)
+try {
+  ToolsObserve.getUITreeHandler = async () => { throw new Error('Paused readiness must not acquire a UI tree') }
+  const readiness = await getAppReadiness({ platform: 'android', deviceId: 'fixture' })
+  assert.equal(readiness.readiness.state, 'debugger_paused')
+  const wait = await getAppReadiness({ platform: 'android', deviceId: 'fixture' }, true)
+  assert.equal(wait.failure_code, 'DEBUGGER_PAUSED')
+  const blocked = payload(await handleToolCall('tap', { platform: 'android', deviceId: 'fixture', x: 1, y: 1 }))
+  assert.equal(blocked.delivery_status, 'not_delivered')
+  await withDebuggerGuard('android', 'other', async () => checkDebuggerGuard(true))
+  await assert.rejects(withDebuggerGuard('android', 'fixture', async () => checkDebuggerGuard()), /DEBUGGER_PAUSED/)
+  paused = false
+  let calls = 0
+  ToolsInteract.waitForUIHandler = async () => { calls++; if (calls === 2) paused = true; return { status: 'success' } as any }
+  const journey = payload(await handleToolCall('run_journey', { platform: 'android', deviceId: 'fixture', responseMode: 'compact', steps: [
+    { id: 'first', type: 'wait', selector: { text: 'First' } },
+    { id: 'second', type: 'wait', selector: { text: 'Second' } },
+    { id: 'third', type: 'wait', selector: { text: 'Third' } }
+  ] }))
+  assert.equal(journey.steps[0].status, 'passed', 'completed steps survive a later pause')
+  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')
+  console.log('PASS debugger readiness without UI acquisition, device scoping, dispatch guard, mid-journey pause preservation')
+} finally {
+  debuggerSessions.paused = originalPause; debuggerSessions.hasActiveSessions = originalActive
+  ToolsObserve.getUITreeHandler = originalTree; ToolsInteract.waitForUIHandler = originalWait
+  _resetDeviceListersForTests()
+}

package/test/unit/debugger/native.test.ts

@@ -0,0 +1,33 @@
+import assert from 'node:assert/strict'
+import { AndroidDebugNative } from '../../../src/debugger/android.js'
+import { DebuggerError, debuggerRemaining, withDebuggerBudget } from '../../../src/debugger/worker.js'
+class Native extends AndroidDebugNative {
+  calls: string[][] = []
+  forwards = 'device tcp:1234 jdwp:10\nother tcp:3456 jdwp:20'
+  async adb(_device: string, args: string[]) {
+    this.calls.push(args)
+    if (args[0] === 'forward' && args[1] === '--list') return this.forwards
+    if (args.at(-1)?.endsWith('/stat')) return '10 (complex process name) S ' + Array(18).fill('0').join(' ') + ' 999 0'
+    if (args.at(-1)?.endsWith('/status')) return 'Name:\ttest\nUid:\t42\t42\t42\t42'
+    if (args.at(-1)?.endsWith('/cmdline')) return 'test.app\0'
+    return ''
+  }
+}
+const native = new Native()
+await native.removeForward('device', 1234, 10)
+assert.deepEqual(native.calls.at(-1), ['forward', '--remove', 'tcp:1234'])
+await assert.rejects(native.removeForward('device', 3456, 10), /DEBUGGER_CLEANUP_FAILED/)
+const before = native.calls.length
+await native.removeForward('device', 9999, 10)
+assert.equal(native.calls.length, before + 1, 'absent owned forward requires no removal')
+const target = { app_id: 'test.app', pid: 10, process_name: 'test.app', start_identity: '', uid: 42 }
+assert.equal((await native.identity('device', target)).start_identity, '999')
+await assert.rejects(native.identity('device', { ...target, start_identity: 'old' }), /PROCESS_CHANGED/)
+await assert.rejects(native.identity('device', { ...target, uid: 44 }), /PROCESS_CHANGED/)
+await assert.rejects(native.candidates('device', 'test.app;evil'), /INVALID_ARGUMENT/)
+const aborted = new AbortController(); aborted.abort()
+await assert.rejects(withDebuggerBudget(100, aborted.signal, async () => debuggerRemaining(10)), /DEBUGGER_CANCELLED/)
+await assert.rejects(withDebuggerBudget(-1, undefined, async () => debuggerRemaining(10)), /DEBUGGER_TIMEOUT/)
+assert.equal(await withDebuggerBudget(100, undefined, async () => debuggerRemaining(10)), 10)
+assert.equal(new DebuggerError('DEBUGGER_TIMEOUT').code, 'DEBUGGER_TIMEOUT')
+console.log('PASS debugger native identity, PID reuse, forward ownership, deadlines and cancellation')

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

@@ -0,0 +1,83 @@
+import assert from 'node:assert/strict'
+import { DebuggerSessions, debuggerExpiry } from '../../../src/debugger/sessions.js'
+import { DebuggerError, type WorkerEvent } from '../../../src/debugger/worker.js'
+import type { DebugNative, DebugTarget } from '../../../src/debugger/android.js'
+import { debuggerContracts, debuggerTools } from '../../../src/server/debugger-schema.js'
+assert.equal(debuggerExpiry(0, 0, 0, 59999), null)
+assert.equal(debuggerExpiry(0, 60000, 0, 60000), 'pause_limit', 'polling cannot extend pause expiry')
+assert.equal(debuggerExpiry(0, 0, undefined, 300000), 'idle_limit')
+assert.equal(debuggerExpiry(0, 1800000, undefined, 1800000), 'session_limit', 'activity cannot extend lifetime')
+const target: DebugTarget = { app_id: 'test.app', pid: 123, uid: 456, process_name: 'test.app', start_identity: '100' }
+let candidates = [target]
+let removed = 0
+let emit: (event: WorkerEvent) => void = () => {}
+let close = 0
+let failCleanup = false
+let failCommand = ''
+const native: DebugNative = {
+  candidates: async () => candidates, identity: async () => target, forward: async () => 12345,
+  removeForward: async () => { if (failCleanup) throw new Error('offline'); removed++ }
+}
+const sessions = new DebuggerSessions(native, async event => {
+  emit = event
+  return { call: async (command: string) => { if (command === failCommand) throw new DebuggerError('DEBUGGER_TIMEOUT'); return { state: 'running', breakpoints: [] } }, close: async () => { close++ } }
+}, async () => ({ java: 'java', directory: '/unused' }))
+try {
+  candidates = [target, { ...target, pid: 124 }]
+  const ambiguous = await sessions.attach('emulator', 'test.app')
+  assert.equal(ambiguous.error.code, 'PROCESS_AMBIGUOUS')
+  assert.equal(removed, 0)
+  candidates = [target]
+  const first = await sessions.attach('emulator', 'test.app')
+  const id = first.debug_session_id
+  assert.equal(first.state, 'running')
+  await assert.rejects(sessions.attach('emulator', 'test.app'), /DEBUGGER_BUSY/)
+  emit({ event: 'stopped', stop_id: 'stop-1', thread_id: 't1', stops: [] })
+  assert.equal(sessions.paused('emulator')?.stop.stop_id, 'stop-1')
+  assert.equal(sessions.paused('other'), null)
+  assert.throws(() => sessions.assertRunning('emulator'), /DEBUGGER_PAUSED/)
+  const pendingWait = sessions.command(id, 'events', { afterSequence: 1 }, 500)
+  await sessions.command(id, 'resume', { stopId: 'stop-1' })
+  assert.equal(sessions.paused('emulator'), null)
+  await assert.rejects(sessions.command(id, 'locals', { stopId: 'stop-1', frameId: 'old' }), /DEBUGGER_STALE_REFERENCE/)
+  emit({ event: 'stopped', stop_id: 'stop-2', thread_id: 't2' })
+  assert.equal((await pendingWait).events[0].stop_id, 'stop-2', 'event wait cannot block resume')
+  for (let i = 0; i < 260; i++) emit({ event: 'breakpoint', i })
+  const events = await sessions.command(id, 'events', { afterSequence: 0 }, 100)
+  assert.equal(events.overflow, true); assert.equal(events.events.length, 100)
+  await assert.rejects(sessions.command(id, 'events', { afterSequence: 9999 }, 100), /INVALID_ARGUMENT/)
+  const controller = new AbortController(); controller.abort()
+  await assert.rejects(sessions.command(id, 'events', { afterSequence: 262, signal: controller.signal }, 100), /DEBUGGER_CANCELLED/)
+  failCommand = 'locals'
+  await assert.rejects(sessions.command(id, 'locals', { stopId: 'stop-2' }, 100), /DEBUGGER_TIMEOUT/)
+  assert.equal(sessions.paused('emulator')?.state, 'paused', 'inspection timeout preserves known suspension')
+  failCommand = 'step'
+  await assert.rejects(sessions.command(id, 'step', { stopId: 'stop-2', threadId: 't2' }, 100), /DEBUGGER_TIMEOUT/)
+  assert.equal((await sessions.command(id, 'state')).cleanup.status, 'complete')
+  assert.equal(close, 1); assert.equal(removed, 1)
+  failCommand = ''
+  const second = await sessions.attach('emulator', 'test.app')
+  failCleanup = true
+  const partial = await sessions.command(second.debug_session_id, 'detach')
+  assert.equal(partial.success, false); assert.equal(partial.cleanup.status, 'failed')
+  await assert.rejects(sessions.attach('emulator', 'test.app'), /DEBUGGER_BUSY/)
+  failCleanup = false
+  const retry = await sessions.command(second.debug_session_id, 'detach')
+  assert.equal(retry.cleanup.status, 'complete'); assert.equal(close, 2)
+  assert.equal((await sessions.command(second.debug_session_id, 'detach')).cleanup.status, 'complete')
+  const third = await sessions.attach('emulator', 'test.app')
+  emit({ event: 'worker_failed' })
+  const crashed = await sessions.command(third.debug_session_id, 'state')
+  assert.equal(crashed.state, 'failed')
+  assert.equal(crashed.cleanup.status, 'complete')
+  assert.equal(crashed.error.code, 'DEBUGGER_WORKER_FAILED')
+  assert.equal(sessions.paused('emulator'), null)
+  for (const tool of debuggerTools) {
+    const contract = debuggerContracts[tool.name]
+    assert.equal(tool.inputSchema.additionalProperties, false)
+    assert.equal(contract.schema.safeParse({ ...Object.fromEntries(tool.inputSchema.required.map(k => [k, 'x'])), unexpected: true }).success, false)
+  }
+  assert.equal(debuggerContracts.attach_debugger.schema.safeParse({ platform: 'android', appId: 'test.app' }).success, false)
+  assert.equal(debuggerContracts.set_debugger_breakpoint.schema.safeParse({ debugSessionId: 's', className: '$(bad)', line: 2 }).success, false)
+  console.log('PASS debugger session ownership, stop epochs, event concurrency/overflow, timeout recovery, cleanup retries, strict contracts')
+} finally { await sessions.shutdown() }

package/test/unit/observe/readiness.test.ts

@@ -32,8 +32,10 @@ for (const extra of [{ error: 'offline' }, { elements: [] }, { captured_at_ms: 9
 for (let index = 0; index < 20; index++) tracker.observe(sample(), 10000, 8000 + index)
 assert.equal(tracker.summary.evidence.length, 8)
 assert.equal(tracker.summary.capabilities.unresponsive, false)
-assert.equal(tracker.summary.capabilities.debugger_paused, false)
+assert.equal(tracker.summary.capabilities.debugger_paused, true)
 assert.ok(tracker.deadline().limitations.includes('DEADLINE_EXCEEDED'))
 assert.equal(new ReadinessTracker('android', 'fixture').observe(sample(), 10000, 9000).state, 'unknown', 'no cross-request history')
 assert.ok(!JSON.stringify(tracker.summary).includes('Ready'), 'evidence contains codes rather than private labels')
+assert.equal(new ReadinessTracker('ios', 'fixture').summary.capabilities.debugger_paused, false)
+assert.ok(tracker.summary.limitations.includes('MANAGED_DEBUGGER_ONLY'))
 console.log('Readiness classifier: PASS')

package/test/unit/observe/system-trace-android.test.ts

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict'
+import { AndroidTraceNative } from '../../../src/observe/system-trace-android.js'
+import type { execCmd } from '../../../src/utils/exec.js'
+
+async function run() {
+  const calls: Array<{ args: string[]; timeout: number | undefined }> = []
+  let failure = '', processes = ''
+  const execute: typeof execCmd = async (_cmd, args, options = {}) => {
+    calls.push({ args, timeout: options.timeout })
+    assert.equal(args[0], '-s'); assert.equal(args[1], 'serial with spaces')
+    if (failure && args.join(' ').includes(failure)) return { exitCode: null, stdout: '', stderr: 'ACTION_TIMEOUT' }
+    let out = ''
+    if (args.includes('--help')) return { exitCode: 1, stdout: '', stderr: 'Usage: perfetto --background-wait --config' }
+    if (args.includes('getprop')) out = '36'
+    if (args.includes('--list_categories')) out = ' sched - Scheduling\n input - Input\n gfx - Graphics'
+    if (args.join(' ').includes('YQ==')) out = 'a'
+    if (args.join(' ').includes('for pid')) out = processes
+    if (args.includes('stat')) out = '1024'
+    return { exitCode: 0, stdout: out, stderr: '' }
+  }
+  const native = new AndroidTraceNative(execute)
+  const remote = '/data/misc/perfetto-traces/mcp-62a51510-c303-4a1b-af0e-f97cc976d740.perfetto-trace'
+  assert.equal((await native.capabilities('serial with spaces')).supported, true)
+  for (const probe of ['--help', '--query', 'getprop', '--list_categories', 'test -w', 'YQ==']) {
+    failure = probe
+    assert.equal((await native.capabilities('serial with spaces')).supported, false, probe)
+  }
+  failure = ''
+  await native.start('serial with spaces', remote, 1001, ['sched', 'input'])
+  assert.equal(calls.at(-1)!.timeout, 35000)
+  assert.ok(calls.at(-1)!.args.join(' ').includes('--background-wait -c -'))
+  assert.equal(await native.find('serial with spaces', remote), null)
+  processes = '123 456'
+  assert.deepEqual(await native.find('serial with spaces', remote), { pid: 123, startTime: '456' })
+  assert.ok(calls.at(-1)!.args.join(' ').includes('stat=$(cat "$p/stat" 2>/dev/null) || { [ ! -d "$p" ] && continue; exit 1; }'), 'Unreadable process identity must fail closed')
+  processes = '123 456\n999 888'
+  await assert.rejects(() => native.find('serial with spaces', remote), /IDENTITY_UNAVAILABLE/)
+  const previous = calls.length
+  await assert.rejects(() => native.stop('serial with spaces', remote, { pid: 0, startTime: '4' }))
+  await assert.rejects(() => native.start('serial with spaces', '/tmp/other; killall perfetto', 1000, []))
+  assert.equal(calls.length, previous)
+  await native.stop('serial with spaces', remote, { pid: 123, startTime: '456' })
+  const signal = calls.at(-1)!.args.join(' ')
+  assert.ok(signal.indexOf('awk') < signal.indexOf('kill -TERM'))
+  assert.ok(signal.indexOf('grep -Fx') < signal.indexOf('kill -TERM'))
+  assert.ok(!signal.includes('killall'))
+  failure = 'pull'
+  await assert.rejects(() => native.pull('serial with spaces', remote, '/tmp/fixture'), /ACTION_TIMEOUT/)
+  assert.equal(calls.at(-1)!.timeout, 30000)
+  console.log('Android Perfetto adapter probes, targeting, guards and deadlines: PASS')
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })