mobile-debug-mcp 0.33.0 → 0.34.0

package/src/server/tool-handlers.ts

@@ -1,4 +1,10 @@
-import { withEvidence, currentEvidenceActionId, validateActionRef, markEvidenceVerification, refreshJourneyEvidence, completeJourneyVerification } from '../observe/evidence.js'
+import { handleDebugger } from './debugger-handlers.js'
+import { debuggerContracts } from './debugger-schema.js'
+import { debuggerSessions } from '../debugger/sessions.js'
+import { withDebuggerGuard, guardDispatched } from '../debugger/guard.js'
+import { systemTraces, TraceError } from '../observe/system-trace.js'
+import { systemTraceTools, traceTargetSchema, traceStartSchema, traceControlSchema } from './system-trace-schema.js'
+import { currentEvidenceCorrelationId, bindSystemTrace, withEvidence, currentEvidenceActionId, validateActionRef, markEvidenceVerification, refreshJourneyEvidence, completeJourneyVerification } from '../observe/evidence.js'
 import { measure, withTiming } from '../utils/timing.js'
 import { randomUUID } from 'node:crypto'
 import { runWithBudget } from '../utils/operation-budget.js'
@@ -41,6 +47,8 @@ import {
   wrapToolError
 } from './common.js'
 
+const systemTraceToolNames = new Set(systemTraceTools.map(tool => tool.name))
+
 type PlatformArg = 'android' | 'ios'
 type ProjectTypeArg = 'native' | 'kmp' | 'react-native' | 'flutter'
 type ExpectElementSelectorArg = { text?: string, resource_id?: string, accessibility_id?: string, contains?: boolean }
@@ -86,7 +94,7 @@ function correlatedHandler(name: string, handler: ToolHandler, action = false, j
     const ref = validateActionRef(args.actionRef)
     const { result, evidence } = await withEvidence({ action, journey, ref }, async () => {
       try { return await handler(args) }
-      catch (error) { return wrapToolError(name, error) }
+      catch (error) { return error instanceof TraceError ? { ...wrapResponse({ error: { tool: name, code: error.code, message: error.message } }), isError: true } : wrapToolError(name, error) }
     })
     const item = result.content.find(item => item.type === 'text')
     if (item?.text) {
@@ -612,13 +620,22 @@ async function handleRunJourney(args: ToolCallArgs) {
   const steps = parsed.data.steps as Array<Record<string, any>>
   const device = await resolveTargetDevice({ platform, deviceId: parsed.data.deviceId })
   const deviceId = device.id
-  return withResolvedDevice(device, async () => {
+  const finishTrace = parsed.data.systemTraceId
+    ? await systemTraces.link(parsed.data.systemTraceId, device, currentEvidenceCorrelationId()!) : undefined
+  if (parsed.data.systemTraceId) bindSystemTrace(parsed.data.systemTraceId)
+  try {
+  return await withResolvedDevice(device, async () => {
   const started = performance.now()
   const results: any[] = []
   let stoppedAt: string | null = null
   let pendingLightStep: number | null = null
   for (let index = 0; index < steps.length; index++) {
     const step = steps[index]
+    if (platform === 'android' && debuggerSessions.paused(deviceId)) {
+      results.push({ id: step.id, type: step.type, status: 'failed', success: false, result: { success: false, failure_code: 'DEBUGGER_PAUSED', dispatch_started: false, delivery_status: 'not_delivered' } })
+      stoppedAt = step.id as string
+      break
+    }
     const requestedVerification = step.verificationMode ?? defaults?.verificationMode ?? 'full'
     const next = steps[index + 1]
     const lightCoveredByAssertion = step.type === 'tap' && responseMode === 'compact' && requestedVerification === 'light' && next?.type === 'assert' &&
@@ -653,6 +670,7 @@ async function handleRunJourney(args: ToolCallArgs) {
     } catch (error) {
       result = { success: false, failure_code: step.type === 'assert' ? 'ASSERTION_TIMEOUT' : 'STEP_FAILED', error: error instanceof Error ? error.message : String(error) }
     }
+    if (platform === 'android' && debuggerSessions.paused(deviceId)) { result.success = false; result.failure_code = 'DEBUGGER_PAUSED'; result.retryable = false }
     if (step.type === 'assert' && !result?.success && /TIMEOUT/.test(result?.failure_code ?? '')) result.failure_code = 'ASSERTION_TIMEOUT'
     const success = !!result?.success
     if (lightCoveredByAssertion) {
@@ -691,8 +709,9 @@ async function handleRunJourney(args: ToolCallArgs) {
     if (key !== 'total_ms' && typeof value === 'number') componentTiming[key] = (componentTiming[key] ?? 0) + value
   }
   refreshJourneyEvidence(results)
-  return wrapResponse({ success: stoppedAt === null, stopped_at_step_id: stoppedAt, steps: results, ...(failureSnapshot ? { failure_snapshot: failureSnapshot } : {}), timing: responseMode === 'compact' ? { total_ms: performance.now() - started } : { ...componentTiming, total_ms: performance.now() - started } }, responseMode === 'debug')
+  return wrapResponse({ ...(finishTrace ? { system_trace: await finishTrace() } : {}), success: stoppedAt === null, stopped_at_step_id: stoppedAt, steps: results, ...(failureSnapshot ? { failure_snapshot: failureSnapshot } : {}), timing: responseMode === 'compact' ? { total_ms: performance.now() - started } : { ...componentTiming, total_ms: performance.now() - started } }, responseMode === 'debug')
   })
+  } finally { await finishTrace?.() }
 }
 
 async function executeSwipe(args: ToolCallArgs) {
@@ -841,7 +860,33 @@ async function handleGetNetworkActivity(args: ToolCallArgs) {
   return wrapResponse(result)
 }
 
+async function handleSystemTrace(name: string, args: ToolCallArgs) {
+  const schema = name === 'start_system_trace' ? traceStartSchema : name === 'get_system_trace_capabilities' ? traceTargetSchema : traceControlSchema
+  const parsed = schema.safeParse(args)
+  if (!parsed.success) throw new TraceError('INVALID_ARGUMENT')
+  if (name === 'get_system_trace_capabilities' || name === 'start_system_trace') {
+    const target = parsed.data as { platform: PlatformArg; deviceId?: string; durationMs?: number }
+    if (target.platform !== 'android') {
+      if (name === 'start_system_trace') throw new TraceError('UNSUPPORTED_PLATFORM')
+      return wrapResponse({ supported: false, backend: 'perfetto', device: null, prerequisites: {}, reasons: ['UNSUPPORTED_PLATFORM'], enabled_sources: [], unavailable_categories: [], limitations: ['Android only'] })
+    }
+    let device
+    try { device = await resolveTargetDevice(target) }
+    catch {
+      if (name === 'start_system_trace') throw new TraceError('TRACE_UNSUPPORTED')
+      return wrapResponse({ supported: false, backend: 'perfetto', device: null, prerequisites: { device: false }, reasons: ['DEVICE_UNAVAILABLE'], enabled_sources: [], unavailable_categories: [], limitations: ['An authorised Android device is required'] })
+    }
+    if (name === 'get_system_trace_capabilities') return wrapResponse(await systemTraces.capabilities(device.id))
+    const result = await systemTraces.start(device.id, target.durationMs)
+    return { ...wrapResponse(result), ...(result.state === 'failed' ? { isError: true } : {}) }
+  }
+  const operation = name === 'stop_system_trace' ? 'stop' : name === 'cancel_system_trace' ? 'cancel' : 'status'
+  const result = await systemTraces.control((parsed.data as { traceId: string }).traceId, operation)
+  return { ...wrapResponse(result), ...(['failed', 'cancelled'].includes(result.state) ? { isError: true } : {}) }
+}
+
 export const toolHandlers: Record<string, ToolHandler> = {
+  ...Object.fromEntries(systemTraceTools.map(({ name }) => [name, (args: ToolCallArgs) => handleSystemTrace(name, args)])),
   get_app_readiness: async args => {
     const parsed = readinessSchema.safeParse(args)
     if (!parsed.success) throw new Error('INVALID_ARGUMENT: invalid readiness arguments')
@@ -893,7 +938,8 @@ for (const name of ['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint
   toolHandlers[name] = correlatedHandler(name, toolHandlers[name], name === 'adjust_control', name === 'run_journey')
 }
 
-export async function handleToolCall(name: string, args: ToolCallArgs = {}) {
+export async function handleToolCall(name: string, args: ToolCallArgs = {}, signal?: AbortSignal) {
+  if (Object.hasOwn(debuggerContracts, name)) return handleDebugger(name, args, signal)
   const handler = toolHandlers[name]
   if (!handler) throw new Error(`Unknown tool: ${name}`)
 
@@ -913,9 +959,48 @@ export async function handleToolCall(name: string, args: ToolCallArgs = {}) {
   }
   return withTiming(measured, async () => {
     try {
-      validateExpectedState(name, args)
-      return addTiming(await handler(args))
+      if (!systemTraceToolNames.has(name)) validateExpectedState(name, args)
+      const guarded = ['start_app', 'terminate_app', 'restart_app', 'reset_app_data', 'install_app', 'build_and_install', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back', 'adjust_control', 'run_journey', 'wait_for_ui', 'wait_for_ui_change', 'wait_for_screen_change', 'expect_screen', 'expect_element_visible', 'expect_state'].includes(name)
+      if (guarded && args.platform !== 'ios' && debuggerSessions.hasActiveSessions()) {
+        const device = await resolveTargetDevice({ platform: 'android', deviceId: args.deviceId as string | undefined })
+        return withResolvedDevice(device, () => withDebuggerGuard('android', device.id, async () => {
+          const before = debuggerSessions.paused(device.id)
+          if (before) return wrapResponse({ success: false, failure_code: 'DEBUGGER_PAUSED', delivery_status: 'not_delivered', dispatch_started: false, debugger: before })
+          let response: ToolCallResult
+          try { response = await handler(args) } catch (error) {
+            if (!debuggerSessions.paused(device.id)) throw error
+            response = wrapResponse({ success: false })
+          }
+          const pause = debuggerSessions.paused(device.id)
+          if (pause) {
+            const item = response.content.find(item => item.type === 'text')
+            if (item?.text) {
+              const payload = JSON.parse(item.text)
+              Object.assign(payload, { success: false, failure_code: 'DEBUGGER_PAUSED', retryable: false,
+                dispatch_started: guardDispatched(), delivery_status: payload.success ? 'delivered' : guardDispatched() ? 'unknown' : 'not_delivered',
+                verification: { status: 'blocked', reason: 'DEBUGGER_PAUSED' }, debugger: pause })
+              item.text = JSON.stringify(payload)
+            }
+          }
+          return addTiming(response)
+        }))
+      }
+      const response = await handler(args)
+      if (['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'get_current_screen', 'read_log_stream'].includes(name) && args.platform !== 'ios') {
+        const item = response.content.find(item => item.type === 'text')
+        if (item?.text) {
+          try {
+            const payload = JSON.parse(item.text)
+            const device = payload.device ?? payload.evidence?.device
+            const id = device?.id ?? args.deviceId
+            const pause = id && device?.platform !== 'ios' ? debuggerSessions.paused(String(id)) : null
+            if (pause) item.text = JSON.stringify({ ...payload, debugger: pause })
+          } catch { /* Non-JSON observation */ }
+        }
+      }
+      return addTiming(response)
     } catch (error) {
+      if (error instanceof TraceError) return { ...wrapResponse({ error: { tool: name, code: error.code, message: error.message } }), isError: true }
       console.error(`Error executing tool ${name}:`, error)
       return addTiming(wrapToolError(name, error))
     }

package/src/server-core.ts

@@ -16,7 +16,7 @@ export { wrapResponse, toolDefinitions, handleToolCall }
 
 export const serverInfo = {
   name: 'mobile-debug-mcp',
-  version: '0.33.0'
+  version: '0.34.0'
 }
 
 export function createServer() {
@@ -46,9 +46,9 @@ export function createServer() {
     tools: toolDefinitions
   }))
 
-  server.setRequestHandler(CallToolRequestSchema, async (request: SchemaOutput<typeof CallToolRequestSchema>) => {
+  server.setRequestHandler(CallToolRequestSchema, async (request: SchemaOutput<typeof CallToolRequestSchema>, extra) => {
     const { name, arguments: args } = request.params
-    return handleToolCall(name, args as Record<string, unknown>)
+    return handleToolCall(name, args as Record<string, unknown>, extra.signal)
   })
 
   return server

package/src/server.ts

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { debuggerSessions } from './debugger/sessions.js'
+import { systemTraces } from './observe/system-trace.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { createServer } from './server-core.js'
 import { getSystemStatus } from './system/index.js'
@@ -13,6 +15,28 @@ if (process.env.MOBILE_DEBUG_MCP_STARTUP_HEALTHCHECK === '1') {
 
 const transport = new StdioServerTransport()
 
+let shuttingDown = false
+async function shutdown() {
+  if (shuttingDown) return
+  shuttingDown = true
+  const deadline = setTimeout(() => { console.error('System trace shutdown cleanup timed out; owned device captures remain duration-bounded.'); process.exit(1) }, 10000)
+  let exitCode = 0
+  try {
+    const [remaining, debuggers] = await Promise.all([systemTraces.shutdown(), debuggerSessions.shutdown()])
+    if (debuggers.length) { exitCode = 1; console.error('Debugger shutdown cleanup incomplete', debuggers.map(s => s.cleanup)) }
+    if (remaining.length) {
+      exitCode = 1
+      console.error('System trace shutdown cleanup incomplete:', remaining.map(s => ({ trace_id: s.trace_id, device: s.device, cleanup: s.cleanup })))
+    }
+    await server.close()
+  } catch { exitCode = 1; console.error('Server shutdown cleanup failed.') }
+  finally { clearTimeout(deadline); process.exit(exitCode) }
+}
+server.onclose = () => { void shutdown() }
+process.stdin.on('end', () => { void shutdown() })
+process.on('SIGINT', () => { void shutdown() })
+process.on('SIGTERM', () => { void shutdown() })
+
 async function main() {
   await (server as any).connect(transport)
 }

package/src/system/index.ts

@@ -33,6 +33,7 @@ interface ToolEntry {
 }
 
 interface CapabilityEntry {
+  probeRequired?: string
   availability: boolean
   selectedProvider: string | null
   blockingFailure: DiagnosticFailure | null
@@ -41,7 +42,7 @@ interface CapabilityEntry {
 interface PlatformEntry {
   status: PlatformStatus
   tools: Record<string, ToolEntry>
-  providers: Record<string, { available: boolean; selected: boolean; tool: string | null }>
+  providers: Record<string, { available: boolean; selected: boolean; tool: string | null; probeRequired?: string }>
   capabilities: Record<string, CapabilityEntry>
   devices: Array<Record<string, unknown>>
   failures: DiagnosticFailure[]
@@ -289,7 +290,7 @@ function buildAndroidPlatform(android: Awaited<ReturnType<typeof checkAndroid>>,
     },
     providers: {
       adb: { available: adbAvailable, selected: true, tool: 'adb' },
-      jdwp: { available: adbAvailable && android.devices > 0, selected: false, tool: 'adb' }
+      jdwp: { available: false, selected: false, tool: 'adb', probeRequired: 'get_debugger_capabilities' }
     },
     capabilities: {
       device_discovery: {
@@ -323,9 +324,10 @@ function buildAndroidPlatform(android: Awaited<ReturnType<typeof checkAndroid>>,
         blockingFailure: logAvailable ? null : adbFailure ?? envFailure
       },
       debug: {
-        availability: adbAvailable && android.devices > 0,
-        selectedProvider: adbAvailable && android.devices > 0 ? 'JDWP' : null,
-        blockingFailure: adbAvailable && android.devices > 0 ? null : deviceFailure ?? adbFailure ?? envFailure
+        probeRequired: 'get_debugger_capabilities',
+        availability: false,
+        selectedProvider: null,
+        blockingFailure: deviceFailure ?? adbFailure ?? envFailure
       }
     },
     devices: deviceEntries,

package/src/utils/exec.ts

@@ -1,3 +1,4 @@
+import { checkDebuggerGuard } from '../debugger/guard.js'
 import { remainingBudget } from './operation-budget.js'
 import { spawn } from 'child_process'
 
@@ -7,6 +8,7 @@ export async function execCmd(cmd: string, args: string[], opts: ExecOptions = {
   const { env, cwd, shell } = opts
   const timeout = remainingBudget(opts.timeout ?? 0)
   return new Promise((resolve, reject) => {
+    checkDebuggerGuard()
     const child = spawn(cmd, args, { env: { ...process.env, ...(env || {}) }, cwd, shell })
     let stdout = ''
     let stderr = ''

package/src/utils/java.ts

@@ -21,17 +21,18 @@ function javaVersionOf(javaBin: string): string | undefined {
   } catch (e: unknown) { console.debug('[javaVersionOf] java -version failed: ' + String(e)); return undefined }
 }
 
-export async function detectJavaHome(): Promise<string | undefined> {
+export async function detectJavaHome(options: { quiet?: boolean } = {}): Promise<string | undefined> {
+  const debug = (...args: unknown[]) => { if (!options.quiet) console.debug(...args) }
   try {
     // 1) Honor explicit ANDROID_STUDIO_JDK env (highest priority)
     const envStudio = process.env.ANDROID_STUDIO_JDK || process.env.ANDROID_STUDIO_JBR
     if (envStudio && existsSync(path.join(envStudio, 'bin', 'java'))) {
       const v = javaVersionOf(path.join(envStudio, 'bin', 'java'))
       if (isJavaVersionAcceptable(v)) {
-        console.debug('[java.detect] Using ANDROID_STUDIO_JDK from env:', envStudio)
+        debug('[java.detect] Using ANDROID_STUDIO_JDK from env:', envStudio)
         return envStudio
       }
-      console.debug('[java.detect] ANDROID_STUDIO_JDK present but java -version did not match expected versions')
+      debug('[java.detect] ANDROID_STUDIO_JDK present but java -version did not match expected versions')
     }
 
     // 2) Android Studio JBR candidates (prefer these over JAVA_HOME)
@@ -50,7 +51,7 @@ export async function detectJavaHome(): Promise<string | undefined> {
       if (existsSync(javaBin)) {
         const v = javaVersionOf(javaBin)
         if (isJavaVersionAcceptable(v)) {
-          console.debug('[java.detect] Found Android Studio JBR at:', p)
+          debug('[java.detect] Found Android Studio JBR at:', p)
           return p
         }
       }
@@ -62,12 +63,12 @@ export async function detectJavaHome(): Promise<string | undefined> {
         const javaBin = path.join(process.env.JAVA_HOME, 'bin', 'java')
         const v = javaVersionOf(javaBin)
         if (isJavaVersionAcceptable(v)) {
-          console.debug('[java.detect] Using JAVA_HOME from env:', process.env.JAVA_HOME)
+          debug('[java.detect] Using JAVA_HOME from env:', process.env.JAVA_HOME)
           return process.env.JAVA_HOME
         }
-        console.debug('[java.detect] Existing JAVA_HOME does not appear to be acceptable Java (17/21), will search')
+        debug('[java.detect] Existing JAVA_HOME does not appear to be acceptable Java (17/21), will search')
       } catch {
-        console.debug('[java.detect] Failed to validate existing JAVA_HOME, searching for JDK')
+        debug('[java.detect] Failed to validate existing JAVA_HOME, searching for JDK')
       }
     }
 
@@ -79,11 +80,11 @@ export async function detectJavaHome(): Promise<string | undefined> {
     try {
       const out17 = execSync('/usr/libexec/java_home -v 17', { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim()
       if (out17) return out17
-    } catch (e: unknown) { console.debug('[java.detect] /usr/libexec/java_home -v 17 failed: ' + String(e)) }
+    } catch (e: unknown) { debug('[java.detect] /usr/libexec/java_home -v 17 failed: ' + String(e)) }
     try {
       const out21 = execSync('/usr/libexec/java_home -v 21', { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim()
       if (out21) return out21
-    } catch (e: unknown) { console.debug('[java.detect] /usr/libexec/java_home -v 21 failed: ' + String(e)) }
+    } catch (e: unknown) { debug('[java.detect] /usr/libexec/java_home -v 21 failed: ' + String(e)) }
 
     // 6) macOS common JDK locations
     try {
@@ -94,7 +95,7 @@ export async function detectJavaHome(): Promise<string | undefined> {
           return candidate
         }
       }
-    } catch (e: unknown) { console.debug('[java.detect] listing /Library/Java/JavaVirtualMachines failed: ' + String(e)) }
+    } catch (e: unknown) { debug('[java.detect] listing /Library/Java/JavaVirtualMachines failed: ' + String(e)) }
 
     // 7) Linux locations
     const linuxCandidates = [
@@ -106,10 +107,10 @@ export async function detectJavaHome(): Promise<string | undefined> {
       '/usr/lib/jvm/java-21-openjdk-amd64'
     ]
     for (const p of linuxCandidates) {
-      try { if (existsSync(p)) return p } catch (e: unknown) { console.debug(`[java.detect] checking linux candidate ${p} failed: ${String(e)}`) }
+      try { if (existsSync(p)) return p } catch (e: unknown) { debug(`[java.detect] checking linux candidate ${p} failed: ${String(e)}`) }
     }
   } catch (e: unknown) {
-    console.debug('[java.detect] error detecting java home:', e instanceof Error ? e.message : String(e))
+    debug('[java.detect] error detecting java home:', e instanceof Error ? e.message : String(e))
   }
   return undefined
 }

package/src/utils/operation-budget.ts

@@ -1,3 +1,4 @@
+import { checkDebuggerGuard } from '../debugger/guard.js'
 import { AsyncLocalStorage } from 'node:async_hooks'
 
 export interface OperationBudget { deadline: number; dispatchStarted: boolean; parent?: OperationBudget }
@@ -36,6 +37,7 @@ export async function runWithSeparateBudget<T>(timeoutMs: number, operation: ()
   }
 }
 export function markDispatchStarted() {
+  checkDebuggerGuard(true)
   remainingBudget()
   let budget = budgets.getStore()
   while (budget) { budget.dispatchStarted = true; budget = budget.parent }

package/src/utils/resolve-device.ts

@@ -1,3 +1,4 @@
+import { checkDebuggerGuard } from '../debugger/guard.js'
 import { bindEvidenceDevice } from '../observe/evidence.js'
 import { retainConnectedDeviceSnapshots } from '../observe/snapshot-metadata.js'
 import { measure } from './timing.js'
@@ -56,6 +57,7 @@ export function withResolvedDevice<T>(device: DeviceInfo, operation: () => Promi
 }
 
 export async function resolveTargetDevice(opts: ResolveOptions): Promise<DeviceInfo> {
+  checkDebuggerGuard()
   const device = await resolveDevice(opts)
   bindEvidenceDevice(device)
   return device

package/test/device/automated/debugger/runtime.android.test.ts

@@ -0,0 +1,203 @@
+import assert from 'node:assert/strict'
+import { execFileSync, spawn } from 'node:child_process'
+import { readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { createHash } from 'node:crypto'
+import { buildDebuggerFixture, debuggerAppId } from '../../../fixtures/debugger-app/build.js'
+
+// Explicit opt-in: installs/removes only this isolated fixture on the selected device.
+if (!process.env.MCP_DEBUGGER_DEVICE) {
+  console.log('UNRUN Android debugger fixture: set MCP_DEBUGGER_DEVICE to an authorized emulator serial')
+} else {
+  const deviceId = process.env.MCP_DEBUGGER_DEVICE
+  const adb = (...args: string[]) => execFileSync(process.env.ADB_PATH || 'adb', ['-s', deviceId, ...args], { encoding: 'utf8', timeout: 15000 })
+  const client = new Client({ name: 'android-debugger-smoke', version: '1.0.0' })
+  const transport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
+  const call = async (name: string, args: Record<string, unknown>) => {
+    const response = await client.callTool({ name, arguments: args }, undefined, { timeout: 45000 })
+    const text = (response.content as any[]).find(c => c.type === 'text')!.text!
+    return JSON.parse(text)
+  }
+  const hash = createHash('sha256')
+  const fingerprint = async (directory: string): Promise<void> => {
+    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      const file = directory + '/' + entry.name
+      if (entry.isDirectory()) await fingerprint(file)
+      else hash.update(file).update(await readFile(file))
+    }
+  }
+  await fingerprint('dist'); await fingerprint('worker')
+  const buildHash = hash.digest('hex')
+  const fixture = buildDebuggerFixture()
+  const source = await readFile(new URL('../../../fixtures/debugger-app/MainActivity.java', import.meta.url), 'utf8')
+  const line = (marker: string) => source.split('\n').findIndex(l => l.includes(marker)) + 1
+  let debugSessionId = ''
+  let cursor = 0
+  const eventsUntilStop = async () => {
+    for (let i = 0; i < 10; i++) {
+      const result = await call('wait_for_debugger_event', { debugSessionId, afterSequence: cursor, timeoutMs: 1000 })
+      cursor = result.next_cursor
+      if (result.events.length) console.log('Debug events', JSON.stringify(result.events))
+      const event = result.events.find((e: any) => e.event === 'stopped')
+      if (event) return event
+    }
+    throw new Error('No debugger stop observed')
+  }
+  const forwardsBefore = adb('forward', '--list').trim()
+  try {
+    await client.connect(transport)
+    const listed = await client.listTools()
+    assert.ok(listed.tools.some(tool => tool.name === 'attach_debugger'))
+    adb('install', '-r', fixture.artifact)
+    adb('shell', 'am', 'start', '-W', '-n', `${debuggerAppId}/.MainActivity`)
+    const cap = await call('get_debugger_capabilities', { platform: 'android', deviceId, appId: debuggerAppId })
+    assert.equal(cap.supported, true, JSON.stringify(cap))
+    const timeout = await call('get_debugger_capabilities', { platform: 'android', deviceId, appId: debuggerAppId, timeoutMs: 100 })
+    assert.equal(timeout.error.code, 'DEBUGGER_TIMEOUT')
+    const unsupported = await call('get_debugger_capabilities', { platform: 'android', deviceId, appId: 'com.missing.debugfixture' })
+    assert.equal(unsupported.supported, false)
+    assert.ok(unsupported.reasons.includes('PROCESS_NOT_FOUND'))
+    const attached = await call('attach_debugger', { platform: 'android', deviceId, appId: debuggerAppId, timeoutMs: 30000 })
+    assert.equal(attached.success, true, JSON.stringify(attached)); debugSessionId = attached.debug_session_id
+    const bp = await call('set_debugger_breakpoint', { debugSessionId, className: `${debuggerAppId}.MainActivity`, line: line('BREAK_CALCULATE') })
+    assert.equal(bp.result.status, 'verified', JSON.stringify(bp))
+    const pending = await call('set_debugger_breakpoint', { debugSessionId, className: `${debuggerAppId}.LateWork`, line: line('BREAK_LATE') })
+    assert.equal(pending.result.status, 'pending', JSON.stringify(pending))
+    const unavailable = await call('set_debugger_breakpoint', { debugSessionId, className: `${debuggerAppId}.MainActivity`, line: 9999 })
+    assert.equal(unavailable.result.status, 'rejected')
+    // Fixture button placement is obtained from real UI semantics, not fixed coordinates.
+    const tree = await call('get_ui_tree', { platform: 'android', deviceId })
+    const button = tree.elements.find((e: any) => /^calculate$/i.test(e.text ?? ''))
+    assert.ok(button, 'Calculate button visible in real UI tree: ' + JSON.stringify(tree))
+    console.log('Fixture target', JSON.stringify({ bounds: button.bounds, device: tree.device, resolution: tree.resolution }))
+    const [left, top, right, bottom] = button.bounds
+    // Shell input is asynchronous so suspension cannot block the test's next debugger call.
+    await writeFile(fixture.directory + '/fixture.png', execFileSync(process.env.ADB_PATH || 'adb', ['-s', deviceId, 'exec-out', 'screencap', '-p']))
+    const tap = spawn(process.env.ADB_PATH || 'adb', ['-s', deviceId, 'shell', 'input', 'tap', String(Math.floor((left + right) / 2)), String(Math.floor((top + bottom) / 2))], { stdio: 'ignore' })
+    tap.on('error', error => { throw error })
+    const stop = await eventsUntilStop()
+    assert.equal(stop.stops[0].location.line, line('BREAK_CALCULATE'))
+    const stack = await call('get_debugger_stack', { debugSessionId, stopId: stop.stop_id, threadId: stop.thread_id })
+    assert.equal(stack.result.frames[0].location.method, 'calculate')
+    const frameId = stack.result.frames[0].frame_id
+    const locals = await call('get_debugger_locals', { debugSessionId, stopId: stop.stop_id, frameId })
+    assert.equal(locals.result.locals.find((v: any) => v.name === 'known')?.value, '42', JSON.stringify(locals))
+    const longText = locals.result.locals.find((v: any) => v.name === 'longText')
+    assert.equal(longText.value.length, 256); assert.equal(longText.truncated, true)
+    const object = locals.result.locals.find((v: any) => v.name === 'object')
+    assert.equal(object.value.type, 'java.lang.Object'); assert.equal(typeof object.value.object_id, 'string')
+    const readiness = await call('get_app_readiness', { platform: 'android', deviceId })
+    assert.equal(readiness.readiness.state, 'debugger_paused')
+    for (const name of ['tap', 'wait_for_ui', 'terminate_app', 'run_journey']) {
+      const blocked = await call(name, { platform: 'android', deviceId, x: 5, y: 5, appId: debuggerAppId })
+      assert.equal(blocked.failure_code, 'DEBUGGER_PAUSED', name)
+      assert.equal(blocked.dispatch_started, false)
+    }
+    await call('remove_debugger_breakpoint', { debugSessionId, breakpointId: bp.result.breakpoint_id })
+    const step = await call('step_debugger', { debugSessionId, stopId: stop.stop_id, threadId: stop.thread_id, kind: 'into' })
+    assert.equal(step.success, true, JSON.stringify(step))
+    const stale = await call('get_debugger_locals', { debugSessionId, stopId: stop.stop_id, frameId })
+    assert.equal(stale.error.code, 'DEBUGGER_STALE_REFERENCE')
+    const into = await eventsUntilStop()
+    assert.equal(into.stops[0].location.method, 'increment')
+    assert.equal((await call('step_debugger', { debugSessionId, stopId: into.stop_id, threadId: into.thread_id, kind: 'over' })).success, true)
+    const over = await eventsUntilStop()
+    assert.equal(over.stops[0].location.method, 'increment')
+    assert.equal((await call('step_debugger', { debugSessionId, stopId: over.stop_id, threadId: over.thread_id, kind: 'out' })).success, true)
+    const out = await eventsUntilStop()
+    assert.equal(out.stops[0].location.method, 'calculate')
+    assert.equal((await call('resume_debugger', { debugSessionId, stopId: out.stop_id })).success, true)
+    let resultVisible = false
+    for (let i = 0; i < 10; i++) {
+      const observed = await call('get_ui_tree', { platform: 'android', deviceId })
+      if (observed.elements.some((e: any) => e.text === 'Result 43')) { resultVisible = true; break }
+    }
+    assert.ok(resultVisible, 'UI tree independently establishes resumed execution: Result 43')
+    const noLocalsSource = await readFile(new URL('../../../fixtures/debugger-app/NoLocals.java', import.meta.url), 'utf8')
+    const noLocalsLine = noLocalsSource.split('\n').findIndex(line => line.includes('BREAK_NO_LOCALS')) + 1
+    const removedPending = await call('set_debugger_breakpoint', { debugSessionId, className: `${debuggerAppId}.NoLocals`, line: noLocalsLine })
+    await call('remove_debugger_breakpoint', { debugSessionId, breakpointId: removedPending.result.breakpoint_id })
+    await call('set_debugger_breakpoint', { debugSessionId, className: `${debuggerAppId}.NoLocals`, line: noLocalsLine })
+    const metadataTree = await call('get_ui_tree', { platform: 'android', deviceId })
+    const mb = metadataTree.elements.find((e: any) => /^no locals$/i.test(e.text ?? '')).bounds
+    spawn(process.env.ADB_PATH || 'adb', ['-s', deviceId, 'shell', 'input', 'tap', String(Math.floor((mb[0] + mb[2]) / 2)), String(Math.floor((mb[1] + mb[3]) / 2))], { stdio: 'ignore' })
+    const metadataStop = await eventsUntilStop()
+    assert.ok(metadataStop.stops.every((stop: any) => stop.breakpoint_id !== removedPending.result.breakpoint_id), 'removed pending breakpoint never rebinds')
+    const metadataStack = await call('get_debugger_stack', { debugSessionId, stopId: metadataStop.stop_id, threadId: metadataStop.thread_id })
+    const metadataLocals = await call('get_debugger_locals', { debugSessionId, stopId: metadataStop.stop_id, frameId: metadataStack.result.frames[0].frame_id })
+    assert.equal(metadataLocals.result.availability, 'unknown')
+    assert.equal(metadataLocals.result.reason, 'EMPTY_OR_UNAVAILABLE_VARIABLE_METADATA')
+    await call('resume_debugger', { debugSessionId, stopId: metadataStop.stop_id })
+    const lateTree = await call('get_ui_tree', { platform: 'android', deviceId })
+    const lateButton = lateTree.elements.find((e: any) => /^late class$/i.test(e.text ?? ''))
+    assert.ok(lateButton)
+    const bounds = lateButton.bounds
+    spawn(process.env.ADB_PATH || 'adb', ['-s', deviceId, 'shell', 'input', 'tap', String(Math.floor((bounds[0] + bounds[2]) / 2)), String(Math.floor((bounds[1] + bounds[3]) / 2))], { stdio: 'ignore' })
+    const lateStop = await eventsUntilStop()
+    assert.equal(lateStop.stops[0].location.class_name, `${debuggerAppId}.LateWork`)
+    assert.equal(lateStop.stops[0].location.line, line('BREAK_LATE'))
+    const aborted = new AbortController()
+    const cancelled = client.callTool({ name: 'wait_for_debugger_event', arguments: { debugSessionId, afterSequence: cursor, timeoutMs: 1000 } }, undefined, { signal: aborted.signal, timeout: 5000 })
+    const cancelTimer = setTimeout(() => aborted.abort(), 100)
+    try { await assert.rejects(cancelled) } finally { clearTimeout(cancelTimer) }
+    assert.equal((await call('get_debugger_state', { debugSessionId })).state, 'paused')
+    if (process.env.MCP_DEBUGGER_EXTENDED === '1') {
+      console.log('Checking real 60-second pause expiry while polling state')
+      const deadline = Date.now() + 65000
+      let state: any
+      do {
+        await new Promise(resolve => setTimeout(resolve, 1000))
+        state = await call('get_debugger_state', { debugSessionId })
+      } while (state.state === 'paused' && Date.now() < deadline)
+      assert.equal(state.state, 'detached', JSON.stringify(state))
+      assert.equal(state.reason, 'pause_limit')
+      assert.equal(state.cleanup.status, 'complete')
+      console.log('PASS real pause expiry despite active client polling')
+    }
+    const detach = await call('detach_debugger', { debugSessionId })
+    assert.equal(detach.cleanup.status, 'complete', JSON.stringify(detach))
+    assert.equal((await call('detach_debugger', { debugSessionId })).cleanup.status, 'complete')
+    assert.equal(adb('forward', '--list').trim(), forwardsBefore, 'unrelated forwards preserved')
+    const reattached = await call('attach_debugger', { platform: 'android', deviceId, appId: debuggerAppId, timeoutMs: 30000 })
+    assert.equal(reattached.success, true, JSON.stringify(reattached))
+    debugSessionId = reattached.debug_session_id
+    adb('shell', 'am', 'force-stop', debuggerAppId)
+    let disconnected: any
+    for (let i = 0; i < 20; i++) {
+      disconnected = await call('get_debugger_state', { debugSessionId })
+      if (disconnected.cleanup.status === 'complete') break
+      await new Promise(resolve => setTimeout(resolve, 100))
+    }
+    assert.equal(disconnected.state, 'disconnected', JSON.stringify(disconnected))
+    assert.equal(disconnected.cleanup.status, 'complete')
+    assert.equal(adb('forward', '--list').trim(), forwardsBefore)
+    // Disconnect the MCP client with an actively paused session; shutdown owns resume/dispose.
+    adb('shell', 'am', 'start', '-W', '-n', `${debuggerAppId}/.MainActivity`)
+    const shutdownSession = await call('attach_debugger', { platform: 'android', deviceId, appId: debuggerAppId, timeoutMs: 30000 })
+    assert.equal(shutdownSession.success, true, JSON.stringify(shutdownSession))
+    debugSessionId = shutdownSession.debug_session_id; cursor = 0
+    await call('set_debugger_breakpoint', { debugSessionId, className: `${debuggerAppId}.MainActivity`, line: line('BREAK_CALCULATE') })
+    const shutdownTree = await call('get_ui_tree', { platform: 'android', deviceId })
+    const shutdownButton = shutdownTree.elements.find((e: any) => /^calculate$/i.test(e.text ?? ''))
+    const sb = shutdownButton.bounds
+    spawn(process.env.ADB_PATH || 'adb', ['-s', deviceId, 'shell', 'input', 'tap', String(Math.floor((sb[0] + sb[2]) / 2)), String(Math.floor((sb[1] + sb[3]) / 2))], { stdio: 'ignore' })
+    await eventsUntilStop()
+    await client.close(); debugSessionId = ''
+    assert.equal(adb('forward', '--list').trim(), forwardsBefore, 'MCP disconnect cleans active owned forward')
+    const verifier = new Client({ name: 'debugger-shutdown-verifier', version: '1.0.0' })
+    try {
+      await verifier.connect(new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' }))
+      const result = await verifier.callTool({ name: 'get_ui_tree', arguments: { platform: 'android', deviceId } })
+      const treeAfterShutdown = JSON.parse((result.content as any[]).find(c => c.type === 'text').text)
+      assert.ok(treeAfterShutdown.elements.some((e: any) => e.text === 'Result 43'), 'fresh UI proves paused fixture resumed after server shutdown')
+    } finally { await verifier.close() }
+    console.log(JSON.stringify({ status: 'PASS', build_sha256: buildHash, device: deviceId, api: adb('shell', 'getprop', 'ro.build.version.sdk').trim(), runtime: process.version, transport: 'MCP stdio', extended: process.env.MCP_DEBUGGER_EXTENDED === '1' }))
+    console.log('PASS Android debugger: explicit attach, source stop, stack/known locals, pause guards, into/over/out, stale frame, resume UI, detach/forward ownership')
+  } finally {
+    if (debugSessionId) await call('detach_debugger', { debugSessionId }).catch(() => {})
+    await client.close()
+    adb('uninstall', debuggerAppId)
+    await rm(fixture.directory, { recursive: true, force: true })
+  }
+}