mobile-debug-mcp 0.33.0 → 0.34.0

package/src/debugger/sessions.ts

@@ -0,0 +1,168 @@
+import { registerDebuggerPauseProvider } from './guard.js'
+import { randomUUID } from 'node:crypto'
+import { AndroidDebugNative, type DebugNative, type DebugTarget } from './android.js'
+import { createWorker, prepareWorker, DebuggerError, withDebuggerBudget, debuggerRemaining, type DebugWorker, type WorkerEvent } from './worker.js'
+
+type State = 'attaching' | 'running' | 'paused' | 'detaching' | 'detached' | 'disconnected' | 'failed'
+interface Session {
+  id: string; device: string; target: DebugTarget | null; state: State; stop: any; reason: string | null
+  worker?: DebugWorker; port?: number; queue: Promise<unknown>; events: any[]; sequence: number
+  cleanup: { status: 'pending' | 'complete' | 'failed'; remaining_resources: string[] }; terminalAt?: number
+  created: number; activity: number; pausedAt?: number; timer?: ReturnType<typeof setInterval>; cleaning?: Promise<void>
+}
+export const debuggerCapabilities = { attach: true, breakpoints: true, stacks: true, locals: true, step: true, resume: true,
+  evaluation: false, mutation: false, coroutines: false, native: false }
+const limitations = ['JAVA_KOTLIN_BYTECODE_ONLY', 'DEBUG_METADATA_REQUIRED', 'SHALLOW_LOCALS', 'ALL_THREADS_SUSPEND', 'DEVICE_WIDE_UI_GUARD']
+export function debuggerExpiry(created: number, activity: number, pausedAt: number | undefined, now: number) {
+  return pausedAt !== undefined && now - pausedAt >= 60000 ? 'pause_limit' : now - activity >= 300000 ? 'idle_limit' : now - created >= 1800000 ? 'session_limit' : null
+}
+export class DebuggerSessions {
+  private sessions = new Map<string, Session>()
+  private closing = false
+  constructor(private native: DebugNative = new AndroidDebugNative(), private workerFactory = createWorker, private prerequisite = prepareWorker) {}
+  private prune() {
+    const terminal = [...this.sessions.values()].filter(s => s.terminalAt !== undefined && s.cleanup.status === 'complete')
+    for (const s of terminal) if (Date.now() - s.terminalAt! >= 600000) this.sessions.delete(s.id)
+    const remaining = terminal.filter(s => this.sessions.has(s.id))
+    for (const s of remaining.slice(0, Math.max(0, remaining.length - 100))) this.sessions.delete(s.id)
+  }
+  private get(id: string) { this.prune(); const s = this.sessions.get(id); if (!s) throw new DebuggerError('DEBUGGER_NOT_FOUND'); s.activity = Date.now(); return s }
+  private serial<T>(s: Session, fn: () => Promise<T>) { const out = s.queue.then(fn); s.queue = out.catch(() => {}); return out }
+  private result(s: Session, payload: any = {}) {
+    const success = payload.success ?? (!['failed', 'disconnected'].includes(s.state) && s.cleanup.status !== 'failed')
+    const code = s.cleanup.status === 'failed' ? 'DEBUGGER_CLEANUP_FAILED' : s.state === 'disconnected' ? 'DEBUGGER_DISCONNECTED' : s.reason?.match(/^[A-Z_]+$/) ? s.reason : 'DEBUGGER_WORKER_FAILED'
+    return structuredClone({ success, ...(!success ? { error: { code, message: code, retryable: false } } : {}), debug_session_id: s.id,
+      device: { platform: 'android', id: s.device }, target: s.target, state: s.state, captured_at_ms: Date.now(),
+      capabilities: debuggerCapabilities, limitations, cleanup: s.cleanup, reason: s.reason, stop: s.stop, ...payload })
+  }
+  summary(id: string) { return this.result(this.get(id)) }
+  hasActiveSessions() { return [...this.sessions.values()].some(s => s.cleanup.status !== 'complete') }
+  paused(device: string) { const s = [...this.sessions.values()].find(s => s.device === device && s.state === 'paused'); return s ? this.result(s) : null }
+  assertRunning(device: string) { if (this.paused(device)) throw new DebuggerError('DEBUGGER_PAUSED') }
+  private event(s: Session, event: WorkerEvent) {
+    if (s.cleanup.status === 'complete') return
+    if (event.event === 'stopped' && !s.cleaning) { s.state = 'paused'; s.stop = event; s.pausedAt ??= Date.now() }
+    if (event.event === 'terminated' || event.event === 'worker_failed') {
+      if (!s.cleaning && s.state !== 'failed') s.reason = event.reason ?? 'worker_failed'
+      if (!s.cleaning) {
+        s.state = event.event === 'worker_failed' ? 'failed' : event.reason === 'process_exit' || event.reason === 'transport_lost' ? 'disconnected' : 'detached'
+        s.stop = null
+        // The worker has disposed or lost its transport. Cleanup remains pending until host resources are checked.
+        void this.serial(s, () => this.cleanup(s, false))
+      }
+    }
+    s.events.push({ ...event, sequence: ++s.sequence, received_at_ms: Date.now() })
+    if (s.events.length > 256) s.events.shift()
+  }
+  async capabilities(device: string, app: string, pid?: number) {
+    const prerequisites: Record<string, boolean> = { jdk: false, device: false, process: false }
+    let candidates: DebugTarget[] = []
+    const reasons: string[] = []
+    try { await this.prerequisite(); prerequisites.jdk = true } catch (e) { if (e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED'].includes(e.code)) throw e; reasons.push('DEBUGGER_UNSUPPORTED') }
+    try { candidates = await this.native.candidates(device, app); prerequisites.device = true; prerequisites.process = candidates.some(t => pid === undefined || pid === t.pid); if (!prerequisites.process) reasons.push('PROCESS_NOT_FOUND') }
+    catch (e) { if (e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED'].includes(e.code)) throw e; reasons.push(e instanceof DebuggerError ? e.code : 'DEVICE_UNAVAILABLE') }
+    return { success: true, debug_session_id: null, device: { platform: 'android', id: device }, target: null, state: null,
+      captured_at_ms: Date.now(), supported: Object.values(prerequisites).every(Boolean), prerequisites, candidates,
+      capabilities: debuggerCapabilities, reasons, limitations, cleanup: { status: 'complete', remaining_resources: [] } }
+  }
+  async attach(device: string, app: string, pid?: number, timeout = 10000) {
+    this.prune()
+    const owned = [...this.sessions.values()].filter(s => s.cleanup.status !== 'complete')
+    if (this.closing || owned.length >= 4 || owned.some(s => s.device === device)) throw new DebuggerError('DEBUGGER_BUSY')
+    const s: Session = { id: randomUUID(), device, target: null, state: 'attaching', stop: null, reason: null,
+      queue: Promise.resolve(), events: [], sequence: 0, cleanup: { status: 'pending', remaining_resources: [] }, created: Date.now(), activity: Date.now() }
+    this.sessions.set(s.id, s)
+    return this.serial(s, async () => {
+      const deadline = Date.now() + timeout
+      const remaining = () => { debuggerRemaining(timeout); const ms = deadline - Date.now(); if (ms <= 0) throw new DebuggerError('DEBUGGER_TIMEOUT'); return ms }
+      try {
+        await this.prerequisite(); remaining()
+        const candidates = (await this.native.candidates(device, app)).filter(t => pid === undefined || t.pid === pid); remaining()
+        if (!candidates.length) throw new DebuggerError('PROCESS_NOT_FOUND')
+        if (candidates.length > 1) throw new DebuggerError('PROCESS_AMBIGUOUS')
+        s.target = candidates[0]
+        s.port = await this.native.forward(device, s.target.pid); remaining()
+        s.cleanup.remaining_resources.push(`forward:tcp:${s.port}`)
+        s.worker = await this.workerFactory(event => this.event(s, event)); remaining()
+        s.cleanup.remaining_resources.push('jdi_worker')
+        await s.worker.call('attach', { port: s.port, timeoutMs: remaining() }, remaining())
+        await this.native.identity(device, s.target); remaining()
+        if (s.state === 'attaching') s.state = 'running'
+        if (['failed', 'disconnected', 'detached'].includes(s.state)) throw new DebuggerError('DEBUGGER_ATTACH_FAILED')
+        s.timer = setInterval(() => {
+          const now = Date.now()
+          const reason = debuggerExpiry(s.created, s.activity, s.pausedAt, now)
+          if (reason) { s.reason = reason; void this.serial(s, () => this.cleanup(s, true)) }
+        }, 1000); s.timer.unref()
+      } catch (e) {
+        s.state = 'failed'; s.reason = e instanceof DebuggerError ? e.code : 'DEBUGGER_ATTACH_FAILED'
+        await this.cleanup(s, true)
+        return this.result(s, { success: false, error: { code: s.reason, message: s.reason, retryable: false } })
+      }
+      return this.result(s)
+    })
+  }
+  private async cleanup(s: Session, requestDetach: boolean): Promise<void> {
+    if (s.cleaning) return s.cleaning
+    s.cleaning = withDebuggerBudget(10000, undefined, async () => {
+      if (s.timer) clearInterval(s.timer)
+      const terminal = ['failed', 'disconnected'].includes(s.state) ? s.state : 'detached'
+      s.state = 'detaching'; s.stop = null; s.pausedAt = undefined
+      const remaining: string[] = []
+      if (s.worker) {
+        if (requestDetach) { try { await s.worker.call('detach', {}, 3000) } catch { /* EOF/transport closure is the fallback; execution remains unknown. */ } }
+        try { await s.worker.close(); s.worker = undefined } catch { remaining.push('jdi_worker') }
+      }
+      if (s.port !== undefined && s.target) {
+        try { await this.native.removeForward(s.device, s.port, s.target.pid); s.port = undefined }
+        catch { remaining.push(`forward:tcp:${s.port}`) }
+      }
+      s.events = []; s.cleanup = { status: remaining.length ? 'failed' : 'complete', remaining_resources: remaining }
+      s.state = terminal; s.terminalAt = Date.now()
+    })
+    try { await s.cleaning } finally { s.cleaning = undefined }
+  }
+  async command(id: string, command: string, args: Record<string, any> = {}, timeout = 10000) {
+    const s = this.get(id)
+    if (command === 'events') {
+      const deadline = Date.now() + timeout
+      const after = args.afterSequence ?? 0
+      if (after > s.sequence) throw new DebuggerError('INVALID_ARGUMENT')
+      if (args.signal?.aborted) throw new DebuggerError('DEBUGGER_CANCELLED')
+      if (s.worker && ['running', 'paused'].includes(s.state)) await s.worker.call('heartbeat', {}, Math.min(timeout, 1000))
+      while (Date.now() < deadline && !s.events.some(e => e.sequence > after) && s.cleanup.status === 'pending') {
+        if (args.signal?.aborted) throw new DebuggerError('DEBUGGER_CANCELLED')
+        await new Promise(resolve => setTimeout(resolve, Math.min(50, deadline - Date.now())))
+      }
+      const events = s.events.filter(e => e.sequence > after).slice(0, 100)
+      return this.result(s, { events, next_cursor: events.at(-1)?.sequence ?? s.sequence, overflow: after < (s.events[0]?.sequence ?? s.sequence + 1) - 1, timed_out: events.length === 0 })
+    }
+    return this.serial(s, async () => {
+      if (command === 'detach') { if (s.cleanup.status !== 'complete') await this.cleanup(s, true); return this.result(s, { success: s.cleanup.status === 'complete', execution_state: 'unknown' }) }
+      if (command === 'state' && (s.cleanup.status === 'complete' || ['detaching', 'detached', 'disconnected', 'failed'].includes(s.state))) return this.result(s)
+      if (!s.worker || ['detaching', 'detached', 'disconnected', 'failed'].includes(s.state)) throw new DebuggerError('DEBUGGER_DISCONNECTED')
+      if (['stack', 'locals', 'step', 'resume'].includes(command)) {
+        if (args.stopId !== s.stop?.stop_id) throw new DebuggerError('DEBUGGER_STALE_REFERENCE')
+        if (s.state !== 'paused') throw new DebuggerError('DEBUGGER_NOT_PAUSED')
+      }
+      if (command === 'step' || command === 'resume') { s.state = 'running'; s.stop = null; s.pausedAt = undefined }
+      try {
+        const data = await s.worker.call(command, args, timeout)
+        return this.result(s, command === 'state' ? { breakpoints: data.breakpoints } : { result: data })
+      } catch (e) {
+        if (e instanceof DebuggerError && e.code === 'DEBUGGER_DISCONNECTED') {
+          s.state = 'disconnected'; s.reason = 'transport_lost'; await this.cleanup(s, false)
+          if (command === 'state') return this.result(s)
+        }
+        if ((command === 'step' || command === 'resume' || command === 'set' || command === 'remove') && e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED', 'DEBUGGER_WORKER_FAILED'].includes(e.code)) {
+          s.state = 'failed'; s.reason = e.code; await this.cleanup(s, true)
+        }
+        throw e
+      }
+    })
+  }
+  async shutdown() { this.closing = true; await Promise.allSettled([...this.sessions.values()].filter(s => s.cleanup.status !== 'complete').map(s => this.serial(s, () => this.cleanup(s, true)))); return [...this.sessions.values()].filter(s => s.cleanup.status !== 'complete').map(s => this.result(s)) }
+}
+export const debuggerSessions = new DebuggerSessions()
+
+registerDebuggerPauseProvider(device => debuggerSessions.paused(device))

package/src/debugger/worker.ts

@@ -0,0 +1,122 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { execFile, spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
+import { promisify } from 'node:util'
+import { readFile, mkdtemp, chmod, rm } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
+import path from 'node:path'
+import os from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { detectJavaHome } from '../utils/java.js'
+
+const exec = promisify(execFile)
+const operations = new AsyncLocalStorage<{ deadline: number; signal?: AbortSignal }>()
+export function withDebuggerBudget<T>(timeout: number, signal: AbortSignal | undefined, operation: () => Promise<T>) {
+  return operations.run({ deadline: performance.now() + timeout, signal }, operation)
+}
+export function debuggerRemaining(fallback: number) {
+  const context = operations.getStore()
+  if (context?.signal?.aborted) throw new DebuggerError('DEBUGGER_CANCELLED')
+  const remaining = Math.floor((context?.deadline ?? Infinity) - performance.now())
+  if (remaining <= 0) throw new DebuggerError('DEBUGGER_TIMEOUT')
+  return Math.min(fallback, remaining)
+}
+export function debuggerSignal() { return operations.getStore()?.signal }
+export function nativeError(error: any, fallback: string): DebuggerError {
+  if (error instanceof DebuggerError) return error
+  if (debuggerSignal()?.aborted) return new DebuggerError('DEBUGGER_CANCELLED')
+  if (error?.killed) return new DebuggerError('DEBUGGER_TIMEOUT')
+  return new DebuggerError(fallback)
+}
+export class DebuggerError extends Error { constructor(public code: string) { super(code) } }
+export const workerSource = fileURLToPath(new URL('../../worker/DebuggerWorker.java', import.meta.url))
+let compiled: Promise<{ java: string; directory: string }> | undefined
+export async function prepareWorker() {
+  compiled ??= (async () => {
+    const home = await detectJavaHome({ quiet: true })
+    const java = home ? path.join(home, 'bin', 'java') : 'java'
+    const javac = home ? path.join(home, 'bin', 'javac') : 'javac'
+    const version = await exec(java, ['-version'], { timeout: debuggerRemaining(5000), signal: debuggerSignal() })
+    const major = Number(/version "(\d+)/.exec(version.stderr)?.[1])
+    if (!(major >= 17)) throw new DebuggerError('DEBUGGER_UNSUPPORTED')
+    const source = await readFile(workerSource)
+    const key = createHash('sha256').update(source).update(version.stderr).digest('hex').slice(0, 16)
+    const directory = await mkdtemp(path.join(os.tmpdir(), `mobile-debug-jdi-${key}-`))
+    await chmod(directory, 0o700)
+    try { await exec(javac, ['--release', '17', '--add-modules', 'jdk.jdi', '-d', directory, workerSource], { timeout: debuggerRemaining(15000), signal: debuggerSignal(), maxBuffer: 1024 * 1024 }) }
+    catch (e) { await rm(directory, { recursive: true, force: true }); throw nativeError(e, 'DEBUGGER_UNSUPPORTED') }
+    return { java, directory }
+  })().catch(error => { compiled = undefined; throw error })
+  return compiled
+}
+export type WorkerEvent = Record<string, any>
+export interface DebugWorker {
+  call(command: string, args?: Record<string, unknown>, timeout?: number): Promise<any>
+  close(): Promise<void>
+}
+export class JdiWorker implements DebugWorker {
+  private child: ChildProcessWithoutNullStreams
+  private pending = new Map<number, { resolve(value: any): void; reject(error: Error): void; timer: ReturnType<typeof setTimeout> }>()
+  private sequence = 0
+  private dead = false
+  private exited: Promise<void>
+  constructor(java: string, directory: string, onEvent: (event: WorkerEvent) => void) {
+    this.child = spawn(java, ['-Xmx128m', '--add-modules', 'jdk.jdi', '-cp', directory, 'DebuggerWorker'], { stdio: ['pipe', 'pipe', 'pipe'] })
+    let buffer = ''
+    const fail = () => {
+      if (this.dead) return
+      this.dead = true
+      for (const request of this.pending.values()) { clearTimeout(request.timer); request.reject(new DebuggerError('DEBUGGER_WORKER_FAILED')) }
+      this.pending.clear()
+      onEvent({ event: 'worker_failed' })
+    }
+    this.exited = new Promise(resolve => { this.child.once('exit', () => { fail(); resolve() }); this.child.once('error', () => { fail(); resolve() }) })
+    this.child.stdin.on('error', fail)
+    this.child.stderr.resume() // Never copy worker data or VM diagnostics into MCP stdout/logs.
+    this.child.stdout.setEncoding('utf8')
+    this.child.stdout.on('data', (chunk: string) => {
+      buffer += chunk
+      if (Buffer.byteLength(buffer) > 2 * 1024 * 1024) { fail(); this.child.kill('SIGKILL'); return }
+      let end: number
+      while ((end = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, end); buffer = buffer.slice(end + 1)
+        try {
+          if (Buffer.byteLength(line) > 1024 * 1024) throw new Error('IPC_LIMIT')
+          const msg = JSON.parse(line)
+          if (msg.event) onEvent(msg)
+          else {
+            const request = this.pending.get(msg.id)
+            if (!request) continue
+            clearTimeout(request.timer); this.pending.delete(msg.id)
+            if (msg.error) request.reject(new DebuggerError(msg.error.code ?? 'DEBUGGER_WORKER_FAILED'))
+            else request.resolve(msg.result)
+          }
+        } catch { fail(); this.child.kill('SIGKILL'); return }
+      }
+    })
+  }
+  call(command: string, args: Record<string, unknown> = {}, timeout = 10000): Promise<any> {
+    if (this.dead) return Promise.reject(new DebuggerError('DEBUGGER_WORKER_FAILED'))
+    try { timeout = Math.min(timeout, debuggerRemaining(timeout)) } catch (e) { return Promise.reject(e) }
+    const id = ++this.sequence
+    const message = JSON.stringify({ ...args, command, id }) + '\n'
+    if (Buffer.byteLength(message) > 1024 * 1024) return Promise.reject(new DebuggerError('INVALID_ARGUMENT'))
+    return new Promise((resolve, reject) => {
+      const signal = debuggerSignal()
+      const abort = () => { this.pending.delete(id); clearTimeout(timer); reject(new DebuggerError('DEBUGGER_CANCELLED')) }
+      const done = () => signal?.removeEventListener('abort', abort)
+      const timer = setTimeout(() => { this.pending.delete(id); done(); reject(new DebuggerError('DEBUGGER_TIMEOUT')) }, timeout)
+      this.pending.set(id, { resolve: value => { done(); resolve(value) }, reject: error => { done(); reject(error) }, timer })
+      signal?.addEventListener('abort', abort, { once: true })
+      this.child.stdin.write(message)
+    })
+  }
+  async close() {
+    this.child.stdin.end()
+    const kill = setTimeout(() => this.child.kill('SIGKILL'), 2000)
+    try { await this.exited } finally { clearTimeout(kill) }
+  }
+}
+export async function createWorker(onEvent: (event: WorkerEvent) => void) {
+  const { java, directory } = await prepareWorker()
+  return new JdiWorker(java, directory, onEvent)
+}

package/src/interact/index.ts

@@ -1,3 +1,4 @@
+import { checkDebuggerGuard } from '../debugger/guard.js'
 import { currentReadinessWait, observeReadinessWait, isDeviceUnavailable } from '../observe/readiness.js'
 import { readinessDelay } from '../observe/readiness-service.js'
 import { isConditionBlocked } from './conditional-action.js'
@@ -2349,13 +2350,13 @@ export class ToolsInteract {
                   break
                 }
               }
-            } catch (e) { console.error('Error scoring element:', e) }
+            } catch (e) { checkDebuggerGuard(); console.error('Error scoring element:', e) }
           }
           if (iterationImprovedBest) {
             bestIterationCandidates = iterationCandidates.slice()
           }
         }
-      } catch (e) { console.error('Error fetching UI tree:', e) }
+      } catch (e) { checkDebuggerGuard(); console.error('Error fetching UI tree:', e) }
       if (shouldStop || Date.now() > deadline) break
       await new Promise(r => setTimeout(r, 100))
     }
@@ -2443,7 +2444,7 @@ export class ToolsInteract {
           }
         }
       }
-    } catch (e) { console.error('Error resolving ancestor:', e) }
+    } catch (e) { checkDebuggerGuard(); console.error('Error resolving ancestor:', e) }
 
     if (!best) return { found: false, error: 'Element not found' }
 
@@ -2697,7 +2698,7 @@ export class ToolsInteract {
               matchedAt = null
             }
 
-          } catch (e) {
+          } catch (e) { checkDebuggerGuard();
             // Deadline expiry does not invalidate the last successfully observed state.
             if (e instanceof Error && e.message === 'ACTION_TIMEOUT') throw e
             if (readinessTracker && !String(e).includes('READINESS_')) readinessTracker.unavailable()
@@ -2737,7 +2738,7 @@ export class ToolsInteract {
         }
       }
 
-    } catch (err) {
+    } catch (err) { checkDebuggerGuard();
       if (!readinessTracker && err instanceof Error && err.message === 'ACTION_TIMEOUT') throw err
       if (readinessTracker && isDeviceUnavailable(err)) throw err
       const elapsed = Date.now() - overallStart
@@ -2805,9 +2806,9 @@ export class ToolsInteract {
             }
             lastFingerprint = confirmFp
             continue
-          } catch (e) { console.error('Error confirming fingerprint:', e); continue }
+          } catch (e) { checkDebuggerGuard(); console.error('Error confirming fingerprint:', e); continue }
         }
-      } catch (e) { console.error('Error getting screen fingerprint:', e) }
+      } catch (e) { checkDebuggerGuard(); console.error('Error getting screen fingerprint:', e) }
 
       await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
     }
@@ -2940,7 +2941,7 @@ export class ToolsInteract {
             candidateSinceMs = null
           }
         }
-      } catch (error) {
+      } catch (error) { checkDebuggerGuard();
         if (readinessTracker && !String(error).includes('READINESS_')) readinessTracker.unavailable()
         if (readinessTracker && isDeviceUnavailable(error)) throw error
         if (readinessTracker && String(error).includes('ACTION_TIMEOUT')) { readinessTracker.deadline(); break }
@@ -3533,7 +3534,7 @@ export class ToolsInteract {
         const msgs = ToolsInteract._logsToMessages(logsArr)
         baselineLastLine = msgs.length ? msgs[msgs.length - 1] : null
       }
-    } catch (err) {
+    } catch (err) { checkDebuggerGuard();
       try { console.warn('waitForUI: failed to get baseline data (non-fatal):', err instanceof Error ? err.message : String(err)) } catch { }
     }
 
@@ -3583,8 +3584,8 @@ export class ToolsInteract {
                   stableDuration = 0
                   lastObservedState = false
                 }
-              } catch (err) { console.error('waitForUI(ui) find error:', err) }
-            } catch (err) { console.error('waitForUI(ui) outer error:', err) }
+              } catch (err) { checkDebuggerGuard(); console.error('waitForUI(ui) find error:', err) }
+            } catch (err) { checkDebuggerGuard(); console.error('waitForUI(ui) outer error:', err) }
         } else if (type === 'log') {
           try {
             // Logs: presence semantics only (match 'present'). Stability not applicable (immediate)
@@ -3614,7 +3615,7 @@ export class ToolsInteract {
                 return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: 0, matchedLog: { message: line }, matchSource: 'log-snapshot', timestamp: now2, type: 'log', observed_state: true }
               }
             }
-          } catch (err) { console.error('waitForUI(log) error:', err) }
+          } catch (err) { checkDebuggerGuard(); console.error('waitForUI(log) error:', err) }
         } else if (type === 'screen') {
           try {
             const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null
@@ -3636,7 +3637,7 @@ export class ToolsInteract {
                 lastObservedState = false
               }
             }
-          } catch (err) { console.error('waitForUI(screen) error:', err) }
+          } catch (err) { checkDebuggerGuard(); console.error('waitForUI(screen) error:', err) }
         } else if (type === 'idle') {
           try {
             const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null
@@ -3655,7 +3656,7 @@ export class ToolsInteract {
                 return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: idleMs, matchSource: 'idle-stable', timestamp: now2, type: 'idle', observed_state: lastObservedState ?? null }
               }
             }
-          } catch (err) { console.error('waitForUI(idle) error:', err) }
+          } catch (err) { checkDebuggerGuard(); console.error('waitForUI(idle) error:', err) }
         }
 
       // Respect poll interval and avoid tight loop
@@ -3671,7 +3672,7 @@ export class ToolsInteract {
         // time ensures the latest exported ToolsObserve object is used.
         const Obs = await import('../observe/index.js')
         snapshot = await (Obs as any).ToolsObserve.captureDebugSnapshotHandler({ reason: `wait_for_ui timeout for ${type}`, includeLogs: true, platform, deviceId })
-      } catch (err) {
+      } catch (err) { checkDebuggerGuard();
         snapshot = { error: err instanceof Error ? err.message : String(err) }
       }
     }

package/src/observe/evidence.ts

@@ -25,6 +25,7 @@ interface Acquisition {
   startSequence: number; endSequence: number; overlapping: boolean; reused: boolean
 }
 interface EvidenceContext {
+  systemTraceId?: string
   correlationId: string; action: ActionRecord | null; ref?: ActionRef
   device: EvidenceDevice | null; start: Stamp; end: Stamp | null; verification: Stamp | null
   observations: Acquisition[]; isAction: boolean; children: EvidenceContext[]
@@ -72,6 +73,12 @@ export function validateActionRef(value: unknown): ActionRef | undefined {
   for (const v of [ref.sessionId, ref.actionId]) if (typeof v !== 'string' || v.length < 1 || v.length > 128) throw new Error('INVALID_ARGUMENT: invalid actionRef')
   return { sessionId: ref.sessionId, actionId: ref.actionId }
 }
+export function evidenceSessionId() { return sessionId }
+export function currentEvidenceCorrelationId() { return context.getStore()?.correlationId }
+export function bindSystemTrace(traceId: string) {
+  const current = context.getStore()
+  if (current) current.systemTraceId = traceId
+}
 export function currentEvidenceActionId() { return context.getStore()?.action?.id }
 export function bindEvidenceDevice(device: { platform: string; id: string }) {
   const current = context.getStore()
@@ -210,7 +217,7 @@ function assemble(current: EvidenceContext) {
     dispatch_started_at_ms: action?.dispatchStart?.wall ?? null,
     dispatch_completed_at_ms: action?.dispatchEnd?.wall ?? null,
     verification_completed_at_ms: current.verification?.wall ?? action?.verification?.wall ?? null,
-    observations, trace_context: { supported: false, trace_id: null, markers: [] }
+    observations, trace_context: { supported: !!current.systemTraceId, trace_id: current.systemTraceId ?? null, markers: [] }
   }
 }
 export async function withEvidence<T>(options: { action?: boolean; journey?: boolean; ref?: ActionRef }, operation: () => Promise<T>): Promise<{ result: T; evidence: ReturnType<typeof assemble> }> {
@@ -219,7 +226,7 @@ export async function withEvidence<T>(options: { action?: boolean; journey?: boo
   const id = randomUUID()
   const record: ActionRecord | null = options.action ? { id, correlationId: parent?.correlationId ?? id, device: null,
     dispatchStart: null, dispatchEnd: null, verification: null, completed: null } : options.ref?.sessionId === sessionId ? active.get(options.ref.actionId) ?? history.get(options.ref.actionId) ?? null : null
-  const current: EvidenceContext = { correlationId: options.action ? record!.correlationId : options.journey ? id : randomUUID(),
+  const current: EvidenceContext = { systemTraceId: parent?.systemTraceId, correlationId: options.action ? record!.correlationId : options.journey ? id : randomUUID(),
     action: record, ref: options.ref, device: null, start: stamp(), end: null, verification: null, observations: [], children: [], isAction: !!options.action }
   if (options.action && record) active.set(id, record)
   if (parent && options.action) parent.children.push(current)

package/src/observe/readiness-service.ts

@@ -1,3 +1,4 @@
+import { pausedReadiness } from '../debugger/guard.js'
 import type { DeviceInfo } from '../types.js'
 import { resolveTargetDevice, withResolvedDevice } from '../utils/resolve-device.js'
 import { remainingBudget, runWithBudget } from '../utils/operation-budget.js'
@@ -24,6 +25,7 @@ export async function getAppReadiness(args: Target & { timeoutMs?: number; stabi
   let device: DeviceInfo | null = null
   let tracker = new ReadinessTracker(args.platform ?? 'android', args.deviceId ?? '')
   let failureCode: string | undefined
+  let debugPause: ReturnType<typeof pausedReadiness> = null
   await runWithBudget(args.timeoutMs ?? (wait ? 30000 : 15000), async () => {
     try {
       device = await resolve(args)
@@ -33,6 +35,8 @@ export async function getAppReadiness(args: Target & { timeoutMs?: number; stabi
         let count = 0
         while (wait || count < 2) {
           remainingBudget()
+          debugPause = device!.platform === 'android' ? pausedReadiness(device!.id) : null
+          if (debugPause) { failureCode = wait ? 'DEBUGGER_PAUSED' : undefined; return }
           const captureStarted = Date.now()
           try {
             const tree = await ToolsObserve.getUITreeHandler({ platform: device!.platform as 'android' | 'ios', deviceId: device!.id })
@@ -57,6 +61,7 @@ export async function getAppReadiness(args: Target & { timeoutMs?: number; stabi
       failureCode = !expired && (!device || isDeviceUnavailable(error)) ? 'DEVICE_UNAVAILABLE' : wait ? 'READINESS_TIMEOUT' : 'READINESS_UNAVAILABLE'
     }
   })
+  if (debugPause) return { success: !wait, device, readiness: debugPause, elapsed_ms: performance.now() - started, ...(wait ? { failure_code: 'DEBUGGER_PAUSED' } : {}) }
   const state = tracker.summary.state
   const success = !failureCode && (wait ? state === 'settled' : state !== 'unknown')
   return { success, device, readiness: tracker.summary, elapsed_ms: performance.now() - started,

package/src/observe/readiness.ts

@@ -1,9 +1,10 @@
+import { pausedReadiness } from '../debugger/guard.js'
 import { AsyncLocalStorage } from 'node:async_hooks'
 import type { ReadinessSummary } from '../types.js'
 import { remainingBudget } from '../utils/operation-budget.js'
 import { computeSnapshotSignature, getSnapshotSessionId } from './snapshot-metadata.js'
 
-const baselineLimitations = ['NORMALIZED_UI_ONLY', 'FOREGROUND_APP_UNVERIFIED', 'UNRESPONSIVE_SIGNAL_UNSUPPORTED', 'DEBUGGER_SIGNAL_UNSUPPORTED']
+const baselineLimitations = ['NORMALIZED_UI_ONLY', 'FOREGROUND_APP_UNVERIFIED', 'UNRESPONSIVE_SIGNAL_UNSUPPORTED']
 const capabilities = { loading: true, transitioning: true, settled: true, unresponsive: false, debugger_paused: false }
 
 export function isDeviceUnavailable(error: unknown) {
@@ -13,18 +14,21 @@ export function isDeviceUnavailable(error: unknown) {
 export class ReadinessTracker {
   private signature: string | null = null
   private stableSince = 0
-  summary: ReadinessSummary = {
+  summary: ReadinessSummary
+
+  constructor(private platform: string, private deviceId: string, private stabilityMs = 500) {
+  this.summary = {
     state: 'unknown', scope: 'device_ui', basis: 'insufficient', captured_at_ms: null,
     sample_count: 0, stable_for_ms: 0, snapshot_session_id: null, snapshot_revision: null,
-    evidence: [], limitations: [...baselineLimitations, 'INSUFFICIENT_SAMPLES'], capabilities: { ...capabilities }
+    evidence: [], limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', 'INSUFFICIENT_SAMPLES'], capabilities: { ...capabilities, debugger_paused: this.platform === 'android' }
   }
 
-  constructor(private platform: string, private deviceId: string, private stabilityMs = 500) {}
+  }
 
   unavailable(code = 'OBSERVATION_FAILED'): ReadinessSummary {
     this.signature = null
     this.summary = { ...this.summary, state: 'unknown', basis: 'insufficient', stable_for_ms: 0,
-      sample_count: this.summary.sample_count + 1, limitations: [...baselineLimitations, code],
+      sample_count: this.summary.sample_count + 1, limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', code],
       evidence: [...this.summary.evidence, { code, source: 'ui_tree', captured_at_ms: null, snapshot_revision: null }].slice(-8) }
     return this.summary
   }
@@ -35,6 +39,8 @@ export class ReadinessTracker {
   }
 
   observe(tree: any, acquisitionStartedAtMs: number, now = performance.now()): ReadinessSummary {
+    const paused = this.platform === 'android' ? pausedReadiness(this.deviceId) : null
+    if (paused) { this.summary = paused; return this.summary }
     if (tree?.error) return this.unavailable('OBSERVATION_FAILED')
     if (!tree || tree.device?.platform !== this.platform || tree.device?.id !== this.deviceId ||
         tree.snapshot_session_id !== getSnapshotSessionId() || !Number.isSafeInteger(tree.snapshot_revision) || tree.snapshot_revision <= 0 ||
@@ -58,7 +64,7 @@ export class ReadinessTracker {
       captured_at_ms: tree.captured_at_ms, snapshot_session_id: tree.snapshot_session_id, snapshot_revision: tree.snapshot_revision,
       sample_count: this.summary.sample_count + 1, stable_for_ms: stableFor,
       evidence: [...this.summary.evidence, { code, source: 'ui_tree', captured_at_ms: tree.captured_at_ms, snapshot_revision: tree.snapshot_revision }].slice(-8),
-      limitations: [...baselineLimitations, ...(state === 'unknown' ? ['INSUFFICIENT_SAMPLES'] : [])], capabilities: { ...capabilities }
+      limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', ...(state === 'unknown' ? ['INSUFFICIENT_SAMPLES'] : [])], capabilities: { ...capabilities, debugger_paused: this.platform === 'android' }
     }
     return this.summary
   }