mobile-debug-mcp 0.32.4 → 0.34.0

package/src/types.ts

@@ -218,6 +218,7 @@ export interface UIElement {
 }
 
 export interface GetUITreeResponse {
+  readiness?: ReadinessSummary;
   device: DeviceInfo;
   screen: string;
   resolution: {
@@ -226,12 +227,27 @@ export interface GetUITreeResponse {
   };
   elements: UIElement[];
   snapshot_revision: number;
+  snapshot_session_id?: string;
   captured_at_ms: number;
   snapshot_delta?: SnapshotDelta | null;
   loading_state?: LoadingState | null;
   error?: string;
 }
 
+export interface ReadinessSummary {
+  state: 'loading' | 'transitioning' | 'settled' | 'unknown' | 'unresponsive' | 'debugger_paused';
+  scope: 'device_ui';
+  basis: 'observed' | 'heuristic' | 'insufficient';
+  captured_at_ms: number | null;
+  sample_count: number;
+  stable_for_ms: number;
+  snapshot_session_id: string | null;
+  snapshot_revision: number | null;
+  evidence: Array<{ code: string; source: string; captured_at_ms: number | null; snapshot_revision: number | null }>;
+  limitations: string[];
+  capabilities: { loading: boolean; transitioning: boolean; settled: boolean; unresponsive: boolean; debugger_paused: boolean };
+}
+
 export interface GetCurrentScreenResponse {
   device: DeviceInfo;
   package: string;
@@ -289,6 +305,8 @@ export interface TapResponse {
 }
 
 export type ActionFailureCode =
+  | 'PRECONDITION_FAILED'
+  | 'PRECONDITION_UNAVAILABLE'
   | 'ELEMENT_NOT_FOUND'
   | 'ELEMENT_NOT_INTERACTABLE'
   | 'TIMEOUT'
@@ -417,6 +435,15 @@ export interface TimingBreakdown {
   serialization_ms?: number;
 }
 
+export interface ActionConditionResult {
+  status: 'matched' | 'mismatch' | 'unavailable' | 'not_checked';
+  expected: { snapshot_session_id: string; snapshot_revision: number };
+  observed: GetUITreeResponse | null;
+  elapsed_ms: number;
+  reason?: 'BASELINE_UNAVAILABLE' | 'SESSION_MISMATCH' | 'DEVICE_MISMATCH' |
+    'OBSERVATION_FAILED' | 'OBSERVATION_INVALID' | 'CONDITION_TIMEOUT' | 'ACTION_NOT_REACHED';
+}
+
 export interface ActionExecutionResult {
   action_id: string;
   timestamp: string;
@@ -435,6 +462,7 @@ export interface ActionExecutionResult {
   dispatch_started?: boolean;
   verification?: { mode: 'none' | 'light' | 'full'; status: 'not_requested' | 'observed' | 'verified' | 'unavailable' | 'failed' };
   state_delta?: StateDelta;
+  condition?: ActionConditionResult;
   timing?: TimingBreakdown;
   recovery?: RecoveryState;
   trace: ActionTrace;
@@ -535,6 +563,7 @@ export interface AdjustControlResponse extends ActionExecutionResult {
 }
 
 export interface WaitForUIChangeResponse {
+  readiness?: ReadinessSummary;
   success: boolean;
   observed_change: 'hierarchy_diff' | 'text_change' | 'state_change' | null;
   snapshot_revision?: number;
@@ -554,7 +583,7 @@ export interface WaitForUIChangeResponse {
   reason?: string;
   loading_state?: LoadingState | null;
   error?: {
-    code: 'INVALID_SCOPE' | 'ELEMENT_NOT_FOUND';
+    code: 'INVALID_SCOPE' | 'ELEMENT_NOT_FOUND' | 'TIMEOUT' | 'DEVICE_UNAVAILABLE';
     message: string;
   };
 }

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/ios/utils.ts

@@ -62,7 +62,7 @@ export async function isIDBInstalled(): Promise<boolean> {
   const cmd = getIdbCmd()
   if (!cmd) return false
   try {
-    execSync(`${cmd} list-targets --json`, { stdio: ['ignore','pipe','pipe'], timeout: 5000 })
+    execSync(`${cmd} list-targets --json`, { stdio: ['ignore','pipe','pipe'], timeout: remainingBudget(5000), killSignal: 'SIGKILL' })
     return true
   } catch (e: unknown) {
     console.debug(`[isIDBInstalled] idb probe failed for '${cmd}': ${e instanceof Error ? e.message : String(e)}`)
@@ -200,7 +200,7 @@ export async function findAppBundle(dir: string): Promise<string | undefined> {
 export async function getIOSDeviceMetadata(deviceId: string = "booted"): Promise<DeviceInfo> {
   return new Promise((resolve) => {
     // If deviceId is provided (and not "booted"), attempt to find that device among booted simulators.
-    execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], (err, stdout) => {
+    execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], { timeout: remainingBudget(), killSignal: 'SIGKILL' }, (err, stdout) => {
       const fallback: DeviceInfo = {
         platform: "ios",
         id: deviceId,
@@ -247,7 +247,7 @@ export async function getIOSDeviceMetadata(deviceId: string = "booted"): Promise
 export async function listIOSDevices(appId?: string): Promise<DeviceInfo[]> {
   return new Promise((resolve) => {
     // Query all devices and separately query booted devices to mark them
-    execFile(getXcrunCmd(), ['simctl', 'list', 'devices', '--json'], (err, stdout) => {
+    execFile(getXcrunCmd(), ['simctl', 'list', 'devices', '--json'], { timeout: remainingBudget(), killSignal: 'SIGKILL' }, (err, stdout) => {
       if (err || !stdout) return resolve([])
       try {
         const data = JSON.parse(stdout)
@@ -256,7 +256,7 @@ export async function listIOSDevices(appId?: string): Promise<DeviceInfo[]> {
         const checks: Promise<void>[] = []
 
         // Get booted devices set
-        execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], (err2, stdout2) => {
+        execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], { timeout: remainingBudget(), killSignal: 'SIGKILL' }, (err2, stdout2) => {
           const bootedSet = new Set<string>()
           if (!err2 && stdout2) {
             try {

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 }
@@ -10,12 +11,33 @@ export function runWithBudget<T>(timeoutMs: number, operation: (budget: Operatio
 }
 export function remainingBudget(fallback = 0): number {
   const budget = budgets.getStore()
-  if (!budget || !Number.isFinite(budget.deadline)) return fallback
-  const remaining = Math.floor(budget.deadline - performance.now())
+  let deadline = budget?.deadline ?? Infinity
+  for (let ancestor = budget?.parent; ancestor; ancestor = ancestor.parent) deadline = Math.min(deadline, ancestor.deadline)
+  if (!Number.isFinite(deadline)) return fallback
+  const remaining = Math.floor(deadline - performance.now())
   if (remaining <= 0) throw new Error('ACTION_TIMEOUT')
   return fallback > 0 ? Math.min(fallback, remaining) : remaining
 }
+
+// Pause only this action's budget. Any enclosing operation still bounds the read.
+export async function runWithSeparateBudget<T>(timeoutMs: number, operation: () => Promise<T>): Promise<T> {
+  remainingBudget()
+  const action = budgets.getStore()
+  const started = performance.now()
+  const parent = action?.parent
+  const budget: OperationBudget = { deadline: Math.min(parent?.deadline ?? Infinity, started + timeoutMs), dispatchStarted: false, parent }
+  try {
+    return await budgets.run(budget, async () => {
+      const result = await operation()
+      remainingBudget()
+      return result
+    })
+  } finally {
+    if (action) action.deadline += performance.now() - started
+  }
+}
 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,5 @@
+import { checkDebuggerGuard } from '../debugger/guard.js'
+import { bindEvidenceDevice } from '../observe/evidence.js'
 import { retainConnectedDeviceSnapshots } from '../observe/snapshot-metadata.js'
 import { measure } from './timing.js'
 import { AsyncLocalStorage } from 'node:async_hooks'
@@ -50,10 +52,18 @@ export async function listDevices(platform?: "android" | "ios", appId?: string):
 const deviceContext = new AsyncLocalStorage<DeviceInfo>()
 
 export function withResolvedDevice<T>(device: DeviceInfo, operation: () => Promise<T>): Promise<T> {
+  bindEvidenceDevice(device)
   return deviceContext.run(device, operation)
 }
 
 export async function resolveTargetDevice(opts: ResolveOptions): Promise<DeviceInfo> {
+  checkDebuggerGuard()
+  const device = await resolveDevice(opts)
+  bindEvidenceDevice(device)
+  return device
+}
+
+async function resolveDevice(opts: ResolveOptions): Promise<DeviceInfo> {
   const { platform, appId, prefer, deviceId } = opts
   const current = deviceContext.getStore()
   if (current && current.platform === platform && (!deviceId || current.id === deviceId)) return current

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 })
+  }
+}

package/test/device/automated/observe/correlated-evidence.smoke.ts

@@ -0,0 +1,70 @@
+import assert from 'node:assert/strict'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+
+// Exercises the rebuilt stdio server, not the connected/published MCP instance.
+async function run() {
+  if (process.env.SKIP_DEVICE_TESTS === '1') {
+    console.log('Correlated evidence device smoke: SKIPPED (SKIP_DEVICE_TESTS=1)')
+    return
+  }
+  const client = new Client({ name: 'correlated-evidence-smoke', version: '1.0.0' })
+  const transport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
+  const parse = (response: any) => JSON.parse(response.content.find((item: any) => item.type === 'text').text)
+  const call = (name: string, args: Record<string, unknown> = {}) => client.callTool({ name, arguments: args }, undefined, { timeout: 120000 })
+  try {
+    await client.connect(transport)
+    const discovery = parse(await call('list_devices'))
+    for (const platform of ['android', 'ios'] as const) {
+      const device = discovery.devices.find((d: any) => d.platform === platform && d.simulator &&
+        (platform === 'android' || d.booted === true))
+      assert.ok(device, `A running ${platform} emulator/simulator is required`)
+      const target = { platform, deviceId: device.id }
+      const appId = platform === 'android' ? 'com.android.settings' : 'com.apple.Preferences'
+      const action = parse(await call('start_app', { ...target, appId, verificationMode: 'none', responseMode: 'compact' }))
+      assert.equal(action.success, true, JSON.stringify(action))
+      assert.equal(action.action_id, action.evidence.action_id)
+      assert.ok(action.evidence.dispatch_started_at_ms)
+      assert.ok(action.evidence.dispatch_completed_at_ms >= action.evidence.dispatch_started_at_ms)
+      assert.equal(action.evidence.verification_completed_at_ms, null)
+      const actionRef = { sessionId: action.evidence.session_id, actionId: action.evidence.action_id }
+      const screenResponse: any = await call('capture_screenshot', { ...target, actionRef })
+      const screen = parse(screenResponse)
+      assert.equal(screen.evidence.action_id, action.action_id)
+      assert.equal(screen.evidence.correlation_id, action.evidence.correlation_id)
+      assert.equal(screen.evidence.association, 'explicit')
+      assert.ok(screenResponse.content.some((item: any) => item.type === 'image' && item.data.length > 0))
+      const screenshot = screen.evidence.observations.find((v: any) => v.kind === 'screenshot')
+      assert.equal(screenshot.status, 'captured')
+      assert.equal(screenshot.freshness, 'fresh')
+      assert.ok(screenshot.capture_started_at_ms >= action.evidence.dispatch_completed_at_ms)
+      const logsResponse: any = await call('get_logs', { ...target, appId, limit: 5, actionRef })
+      const logs = parse(logsResponse)
+      assert.equal(logs.evidence.action_id, action.action_id)
+      assert.ok(Array.isArray(JSON.parse(logsResponse.content[1].text).logs))
+      const log = logs.evidence.observations.find((v: any) => v.kind === 'logs')
+      assert.equal(log.status, 'captured', log.error)
+      assert.equal(log.event_time_comparable, false)
+      assert.equal(log.freshness, 'unknown')
+      const snapshot = parse(await call('capture_debug_snapshot', { ...target, actionRef, includeScreenshot: false, includeLogs: false }))
+      assert.equal(snapshot.evidence.action_id, action.action_id)
+      assert.equal(snapshot.raw.screenshot, null)
+      assert.equal(snapshot.evidence.observations.find((v: any) => v.kind === 'screenshot').status, 'omitted')
+      assert.equal(snapshot.evidence.observations.find((v: any) => v.kind === 'logs').status, 'omitted')
+      assert.ok(snapshot.evidence.observations.every((v: any) => !v.device || v.device.id === device.id))
+      const tree = snapshot.evidence.observations.find((v: any) => v.kind === 'ui_tree')
+      assert.equal(tree.status, 'captured', tree.error)
+      const unassociated = parse(await call('get_ui_tree', { ...target, responseMode: 'compact', actionRef: { ...actionRef, sessionId: 'previous-process' } }))
+      assert.equal(unassociated.evidence.association_reason, 'SESSION_MISMATCH')
+      assert.equal(unassociated.evidence.action_id, null)
+      console.log(JSON.stringify({ status: 'PASS', server: client.getServerVersion(), platform, device: device.id,
+        osVersion: device.osVersion, startingApp: appId, actionId: action.action_id,
+        phases: { dispatchStarted: action.evidence.dispatch_started_at_ms, dispatchCompleted: action.evidence.dispatch_completed_at_ms,
+          screenshotStarted: screenshot.capture_started_at_ms, screenshotCompleted: screenshot.capture_completed_at_ms },
+        screenshot: screenshot.status, logs: log.status, uiTree: tree.status,
+        disabledComponents: 'omitted', foreignReference: 'unavailable',
+        cleanup: 'No settings, app data or streams changed; Settings remains foreground. No content artifacts saved.' }))
+    }
+  } finally { await client.close() }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })