mobile-debug-mcp 0.32.4 → 0.34.0

package/src/interact/index.ts

@@ -1,3 +1,7 @@
+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'
 import { remainingBudget } from '../utils/operation-budget.js'
 import { createHash } from 'crypto'
 import { AndroidInteract } from './android.js';
@@ -605,6 +609,7 @@ export class ToolsInteract {
   }
 
   private static async _captureFingerprint(platform: 'android' | 'ios', deviceId?: string): Promise<string | null> {
+    if (isConditionBlocked()) return null
     try {
       const fingerprint = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null
       return fingerprint?.fingerprint ?? null
@@ -2345,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))
     }
@@ -2439,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' }
 
@@ -2491,7 +2496,8 @@ export class ToolsInteract {
     return { found: true, element: outEl, score: scoreVal, confidence: scoreVal, resolution }
   }
 
-  static async waitForUIHandler({ selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry = { max_attempts: 1, backoff_ms: 0 }, platform, deviceId, singleObservation = false, singleAttempt = false, rejectAmbiguous = false }: { selector?: { text?: string, resource_id?: string, accessibility_id?: string, contains?: boolean }, condition?: 'exists'|'not_exists'|'visible'|'clickable', timeout_ms?: number, poll_interval_ms?: number, match?: { index?: number }, retry?: { max_attempts?: number, backoff_ms?: number }, platform?: 'android'|'ios', deviceId?: string, singleObservation?: boolean, singleAttempt?: boolean, rejectAmbiguous?: boolean }) {
+  static async waitForUIHandler({ selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry = { max_attempts: 1, backoff_ms: 0 }, platform, deviceId, singleObservation = false, singleAttempt = false, rejectAmbiguous = false, resolveTapTarget = false }: { selector?: { text?: string, resource_id?: string, accessibility_id?: string, contains?: boolean }, condition?: 'exists'|'not_exists'|'visible'|'clickable', timeout_ms?: number, poll_interval_ms?: number, match?: { index?: number }, retry?: { max_attempts?: number, backoff_ms?: number }, platform?: 'android'|'ios', deviceId?: string, singleObservation?: boolean, singleAttempt?: boolean, rejectAmbiguous?: boolean, resolveTapTarget?: boolean }) {
+    const readinessTracker = currentReadinessWait()
     const overallStart = Date.now()
     const requestedIndex = typeof match?.index === 'number' ? match.index : null
     const requested = {
@@ -2559,7 +2565,11 @@ export class ToolsInteract {
           remainingBudget()
           totalPollCount++
           try {
+            const acquisitionStarted = Date.now()
             const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId }) as any
+            observeReadinessWait(tree, acquisitionStarted)
+            // A failed acquisition cannot establish that the requested tap target is absent.
+            if (resolveTapTarget && tree?.error && /ACTION_TIMEOUT|timed out/i.test(String(tree.error))) throw new Error('ACTION_TIMEOUT')
             const elements = (tree && Array.isArray(tree.elements)) ? tree.elements as any[] : []
 
             const matches: { el: any, idx: number }[] = []
@@ -2633,7 +2643,8 @@ export class ToolsInteract {
                 conditionMet = visibleFlag
               } else conditionMet = false
             } else if (condition === 'clickable') {
-              matchedElement = chosen ? (ToolsInteract._resolveActionableAncestor(elements, chosen as { el: UiElement, idx: number }) || chosen) : null
+              matchedElement = chosen ? (resolveTapTarget && (!ToolsInteract._isVisibleElement(chosen.el) || chosen.el.enabled === false)
+                ? chosen : ToolsInteract._resolveActionableAncestor(elements, chosen as { el: UiElement, idx: number }) || chosen) : null
               if (matchedElement) {
                 const b = matchedElement.el.bounds
                 const visibleFlag = !!matchedElement.el.visible && Array.isArray(b) && b.length >= 4 && (b[2] > b[0] && b[3] > b[1])
@@ -2643,6 +2654,13 @@ export class ToolsInteract {
               } else conditionMet = false
             }
 
+            // Waiting for a label to exist/be visible is distinct from resolving its
+            // executable control. Reuse the clickable-wait ancestor policy without
+            // promoting hidden or disabled labels into an unrelated enabled target.
+            if (resolveTapTarget && conditionMet && matchedElement &&
+                ToolsInteract._isVisibleElement(matchedElement.el) && matchedElement.el.enabled !== false) {
+              matchedElement = ToolsInteract._resolveActionableAncestor(elements, matchedElement) ?? matchedElement
+            }
             const resolvedPlatform = tree?.device?.platform === 'ios' ? 'ios' : (platform || 'android')
             const resolvedDeviceId = tree?.device?.id || deviceId
             lastMatchedCount = matchedCount
@@ -2656,7 +2674,7 @@ export class ToolsInteract {
             if (conditionMet && snapshotFresh) {
               if (matchedAt === null) matchedAt = now
               stableMatchCount++
-              if (stableMatchCount >= stableObservationCount) {
+              if (stableMatchCount >= stableObservationCount && (!readinessTracker || readinessTracker.summary.state === 'settled')) {
                 const latency_ms = now - overallStart
                 const outEl = lastMatchedElement
 
@@ -2680,20 +2698,23 @@ 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()
+            if (readinessTracker && isDeviceUnavailable(e)) throw e
             // Non-fatal per-poll error; record and continue
-            console.warn('waitForUI: poll error (non-fatal):', e instanceof Error ? e.message : String(e))
+            if (!readinessTracker) console.warn('waitForUI: poll error (non-fatal):', e instanceof Error ? e.message : String(e))
           }
 
           if (singleAttempt) break
           // Sleep until next poll
-          await new Promise(r => setTimeout(r, effectivePoll || 50))
+          await (readinessTracker ? readinessDelay(effectivePoll || 50) : new Promise(r => setTimeout(r, effectivePoll || 50)))
         }
 
         // Attempt timed out; if more attempts allowed, backoff then retry
         if (attempts < maxAttempts) {
-          if (backoff > 0) await new Promise(r => setTimeout(r, backoff))
+          if (backoff > 0) await (readinessTracker ? readinessDelay(backoff) : new Promise(r => setTimeout(r, backoff)))
           continue
         }
 
@@ -2710,24 +2731,25 @@ export class ToolsInteract {
           : ` observed ${lastMatchedCount} match(es)`
         return {
           status: 'timeout',
-          error: { code: 'ELEMENT_NOT_FOUND', message: `Condition ${condition} not satisfied within timeout;${matchNote}` },
+          error: { code: readinessTracker ? 'TIMEOUT' : 'ELEMENT_NOT_FOUND', message: `Condition ${condition} not satisfied within timeout;${matchNote}` },
           metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts },
           requested,
           observed
         }
       }
 
-    } catch (err) {
-      if (err instanceof Error && err.message === 'ACTION_TIMEOUT') throw 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
       return {
         status: 'timeout',
-        error: { code: 'INTERNAL_ERROR', message: err instanceof Error ? err.message : String(err) },
+        error: { code: readinessTracker && String(err).includes('ACTION_TIMEOUT') ? 'TIMEOUT' : 'INTERNAL_ERROR', message: readinessTracker ? 'Readiness predicate wait did not complete' : err instanceof Error ? err.message : String(err) },
         metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts },
         requested,
         observed: {
           matched_count: lastMatchedCount,
-          condition_satisfied: false,
+          condition_satisfied: readinessTracker ? lastConditionSatisfied : false,
           selected_index: lastMatchedElement?.index ?? null,
           last_matched_element: lastMatchedElement
         }
@@ -2784,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))
     }
@@ -2821,6 +2843,7 @@ export class ToolsInteract {
     scope?: 'screen' | 'subtree',
     target?: string | null
   }): Promise<WaitForUIChangeResponse> {
+    const readinessTracker = currentReadinessWait()
     const start = Date.now()
     const pollIntervalMs = 300
     const stabilityWindow = Math.max(0, typeof stability_window_ms === 'number' ? stability_window_ms : 300)
@@ -2844,7 +2867,10 @@ export class ToolsInteract {
 
     while (Date.now() - start < timeout_ms) {
       try {
+        if (readinessTracker) remainingBudget()
+        const acquisitionStarted = Date.now()
         const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId }) as any
+        observeReadinessWait(tree, acquisitionStarted)
         const scopedTree = ToolsInteract._resolveUiChangeScope(tree, scope, target)
         if (scopedTree.error) {
           lastScopeResolution = scopedTree.resolution
@@ -2892,7 +2918,7 @@ export class ToolsInteract {
             }
 
             const stableForMs = candidateSinceMs === null ? 0 : Date.now() - candidateSinceMs
-            if (stabilityWindow === 0 || stableForMs >= stabilityWindow) {
+            if ((stabilityWindow === 0 || stableForMs >= stabilityWindow) && (!readinessTracker || readinessTracker.summary.state === 'settled')) {
                 return {
                   success: true,
                   observed_change: candidateObservedChange ?? observedChange,
@@ -2915,11 +2941,14 @@ export class ToolsInteract {
             candidateSinceMs = null
           }
         }
-      } catch {
-        // Keep polling until timeout; the observable surface should be best-effort.
+      } 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 }
+        // Default waits retain best-effort polling.
       }
 
-      await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
+      await (readinessTracker ? readinessDelay(pollIntervalMs) : new Promise(resolve => setTimeout(resolve, pollIntervalMs)))
     }
 
     return {
@@ -3505,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 { }
     }
 
@@ -3555,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)
@@ -3586,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
@@ -3608,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
@@ -3627,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
@@ -3643,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/interact/ios.ts

@@ -1,3 +1,5 @@
+import { evidenceDispatch } from '../observe/evidence.js'
+import { beforeInputDispatch } from './conditional-action.js'
 import { remainingBudget, markDispatchStarted } from '../utils/operation-budget.js'
 import { spawn } from "child_process"
 import { TapResponse, SwipeResponse } from "../types.js"
@@ -31,9 +33,11 @@ export class iOSInteract {
         args.push('--udid', targetUdid);
       }
 
-      await new Promise<void>((resolve, reject) => {
-        markDispatchStarted()
-        const proc = spawn(getIdbCmd(), args, { timeout: remainingBudget() || undefined });
+      await beforeInputDispatch('ios', device.id)
+      const timeout = remainingBudget() || undefined
+      markDispatchStarted()
+      await evidenceDispatch({ platform: 'ios', id: device.id }, () => new Promise<void>((resolve, reject) => {
+        const proc = spawn(getIdbCmd(), args, { timeout });
         let stderr = '';
         proc.stderr.on('data', d => stderr += d.toString());
         proc.on('close', code => {
@@ -41,7 +45,7 @@ export class iOSInteract {
             else reject(new Error(`idb ui tap failed: ${stderr}`));
         });
         proc.on('error', err => reject(err));
-      });
+      }));
 
       return { device, success: true, x, y };
     } catch (e) {
@@ -73,9 +77,11 @@ export class iOSInteract {
         args.push('--udid', targetUdid);
       }
 
-      await new Promise<void>((resolve, reject) => {
-        markDispatchStarted()
-        const proc = spawn(getIdbCmd(), args, { timeout: remainingBudget() || undefined });
+      await beforeInputDispatch('ios', device.id)
+      const timeout = remainingBudget() || undefined
+      markDispatchStarted()
+      await evidenceDispatch({ platform: 'ios', id: device.id }, () => new Promise<void>((resolve, reject) => {
+        const proc = spawn(getIdbCmd(), args, { timeout });
         let stderr = '';
         proc.stderr.on('data', d => stderr += d.toString());
         proc.on('close', code => {
@@ -83,7 +89,7 @@ export class iOSInteract {
           else reject(new Error(`idb ui swipe failed: ${stderr}`));
         });
         proc.on('error', err => reject(err));
-      });
+      }));
 
       return { device, success: true, start: [x1, y1], end: [x2, y2], duration };
     } catch (e) {

package/src/manage/android.ts

@@ -1,3 +1,4 @@
+import { evidenceDispatch } from '../observe/evidence.js'
 import { hasFiniteBudget, markDispatchStarted, remainingBudget, runWithBudget } from '../utils/operation-budget.js'
 import { promises as fs } from 'fs'
 import { spawn } from 'child_process'
@@ -156,7 +157,7 @@ export class AndroidManage {
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
     try {
       markDispatchStarted()
-      const output = await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId, { timeout: timeoutMs })
+      const output = await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId, { timeout: timeoutMs }))
       const current = await new AndroidObserve().getCurrentScreen(deviceId).catch(() => null)
       return {
         device: deviceInfo,
@@ -182,7 +183,7 @@ export class AndroidManage {
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
     try {
       markDispatchStarted()
-      await execAdb(['shell', 'am', 'force-stop', appId], deviceId)
+      await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'am', 'force-stop', appId], deviceId))
       return { device: deviceInfo, appTerminated: true }
     } catch (e: unknown) {
       const diagnostics = hasFiniteBudget() ? undefined : execAdbWithDiagnostics(['shell', 'am', 'force-stop', appId], deviceId)
@@ -215,7 +216,7 @@ export class AndroidManage {
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
     try {
       markDispatchStarted()
-      const output = await execAdb(['shell', 'pm', 'clear', appId], deviceId)
+      const output = await evidenceDispatch({ platform: 'android', id: deviceInfo.id }, () => execAdb(['shell', 'pm', 'clear', appId], deviceId))
       return { device: deviceInfo, dataCleared: output === 'Success' }
     } catch (e: unknown) {
       const diag = execAdbWithDiagnostics(['shell', 'pm', 'clear', appId], deviceId)

package/src/manage/ios.ts

@@ -1,3 +1,4 @@
+import { evidenceDispatch } from '../observe/evidence.js'
 import { hasFiniteBudget, markDispatchStarted, remainingBudget, runWithBudget } from '../utils/operation-budget.js'
 import { promises as fs } from "fs"
 import { spawn, spawnSync } from "child_process"
@@ -316,7 +317,7 @@ export class iOSManage {
     validateBundleId(bundleId)
     try {
       markDispatchStarted()
-      const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId)
+      const result = await evidenceDispatch({ platform: 'ios', id: deviceId }, () => execCommand(['simctl', 'launch', deviceId, bundleId], deviceId))
       const device = await getIOSDeviceMetadata(deviceId)
       const fingerprint = observe ? await new iOSObserve().getScreenFingerprint(deviceId).catch(() => null) : null
       const pidMatch = result.output.match(/:\s*(\d+)\s*$/)
@@ -343,7 +344,7 @@ export class iOSManage {
     validateBundleId(bundleId)
     try {
       markDispatchStarted()
-      await execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId)
+      await evidenceDispatch({ platform: 'ios', id: deviceId }, () => execCommand(['simctl', 'terminate', deviceId, bundleId], deviceId))
       const device = await getIOSDeviceMetadata(deviceId)
       return { device, appTerminated: true }
     } catch (e: unknown) {

package/src/observe/android.ts

@@ -1,3 +1,4 @@
+import { captureEvidence } from './evidence.js'
 import { spawn } from "child_process"
 import { XMLParser } from "fast-xml-parser"
 import { GetLogsResponse, CaptureAndroidScreenResponse, GetUITreeResponse, GetCurrentScreenResponse, UIElement, DeviceInfo } from "../types.js"
@@ -11,14 +12,20 @@ import { deriveSnapshotMetadata } from "./snapshot-metadata.js"
 import { remainingBudget } from '../utils/operation-budget.js'
 import { createObservationMeasurement } from './performance-metrics.js'
 
-const activeLogStreams: Map<string, { proc: any, file: string }> = new Map()
+const activeLogStreams: Map<string, { proc: any, file: string, device?: { platform: 'android' | 'ios'; id: string } }> = new Map()
 
 export class AndroidObserve {
+  getLogStreamDevice(sessionId: string = 'default') { return activeLogStreams.get(sessionId)?.device ?? null }
+
   async getDeviceMetadata(appId: string, deviceId?: string): Promise<DeviceInfo> {
     return getAndroidDeviceMetadata(appId, deviceId);
   }
 
   async getUITree(deviceId?: string): Promise<GetUITreeResponse> {
+    return captureEvidence('ui_tree', { platform: 'android', id: deviceId ?? '' }, () => this.collectGetUITree(deviceId))
+  }
+
+  private async collectGetUITree(deviceId?: string): Promise<GetUITreeResponse> {
     const measurement = createObservationMeasurement('android')
     let metadata
     try {
@@ -122,6 +129,10 @@ export class AndroidObserve {
   }
 
   async getLogs(filters: { appId?: string, deviceId?: string, pid?: number, tag?: string, level?: string, contains?: string, since_seconds?: number, limit?: number } = {}): Promise<GetLogsResponse> {
+    return captureEvidence('logs', { platform: 'android', id: filters.deviceId ?? '' }, () => this.collectGetLogs(filters))
+  }
+
+  private async collectGetLogs(filters: { appId?: string, deviceId?: string, pid?: number, tag?: string, level?: string, contains?: string, since_seconds?: number, limit?: number } = {}): Promise<GetLogsResponse> {
     const { appId, deviceId, pid, tag, level, contains, since_seconds, limit } = filters
     const metadata = await getAndroidDeviceMetadata(appId || "", deviceId)
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
@@ -221,6 +232,10 @@ export class AndroidObserve {
   }
 
   async captureScreen(deviceId?: string): Promise<CaptureAndroidScreenResponse> {
+    return captureEvidence('screenshot', { platform: 'android', id: deviceId ?? '' }, () => this.collectCaptureScreen(deviceId))
+  }
+
+  private async collectCaptureScreen(deviceId?: string): Promise<CaptureAndroidScreenResponse> {
     const metadata = await getAndroidDeviceMetadata("", deviceId)
     const deviceInfo: DeviceInfo = getDeviceInfo(deviceId || 'default', metadata)
 
@@ -349,6 +364,10 @@ export class AndroidObserve {
   }
 
   async getCurrentScreen(deviceId?: string): Promise<GetCurrentScreenResponse> {
+    return captureEvidence('activity', { platform: 'android', id: deviceId ?? '' }, () => this.collectGetCurrentScreen(deviceId))
+  }
+
+  private async collectGetCurrentScreen(deviceId?: string): Promise<GetCurrentScreenResponse> {
     const metadata = await getAndroidDeviceMetadata("", deviceId)
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
 
@@ -410,13 +429,17 @@ export class AndroidObserve {
     }
   }
 
-  async getScreenFingerprint(deviceId?: string): Promise<{ fingerprint: string | null; activity?: string; error?: string }> {
+  async getScreenFingerprint(deviceId?: string): Promise<{ fingerprint: string | null; activity?: string; error?: string; captured_at_ms?: number }> {
+    return captureEvidence('fingerprint', { platform: 'android', id: deviceId ?? '' }, () => this.collectGetScreenFingerprint(deviceId))
+  }
+
+  private async collectGetScreenFingerprint(deviceId?: string): Promise<{ fingerprint: string | null; activity?: string; error?: string; captured_at_ms?: number }> {
     try {
       const tree = await this.getUITree(deviceId)
       if (!tree || (tree as any).error) return { fingerprint: null, error: (tree as any).error }
 
       const current = await this.getCurrentScreen(deviceId).catch(() => null)
-      return computeScreenFingerprint(tree, current, 'android', 50)
+      return { ...computeScreenFingerprint(tree, current, 'android', 50), captured_at_ms: tree.captured_at_ms }
     } catch (e) {
       return { fingerprint: null, error: e instanceof Error ? e.message : String(e) }
     }
@@ -436,7 +459,7 @@ export class AndroidObserve {
         activeLogStreams.delete(sessionId)
       }
 
-      const args = ['logcat', `--pid=${pid}`, filter]
+      const args = [...(deviceId ? ['-s', deviceId] : []), 'logcat', `--pid=${pid}`, filter]
       const proc = spawn(getAdbCmd(), args)
 
       const tmpDir = process.env.TMPDIR || '/tmp'
@@ -463,10 +486,10 @@ export class AndroidObserve {
 
       proc.on('close', () => {
         stream.end()
-        activeLogStreams.delete(sessionId)
+        if (activeLogStreams.get(sessionId)?.proc === proc) activeLogStreams.delete(sessionId)
       })
 
-      activeLogStreams.set(sessionId, { proc, file })
+      activeLogStreams.set(sessionId, { proc, file, device: { platform: 'android', id: deviceId ?? '' } })
       return { success: true, stream_started: true }
     } catch (e) {
       return { success: false, error: e instanceof Error ? e.message : String(e) }
@@ -482,6 +505,10 @@ export class AndroidObserve {
   }
 
   async readLogStream(sessionId: string = 'default', limit: number = 100, since?: string) {
+    return captureEvidence('logs', this.getLogStreamDevice(sessionId), () => this.collectReadLogStream(sessionId, limit, since))
+  }
+
+  private async collectReadLogStream(sessionId: string = 'default', limit: number = 100, since?: string) {
     const entry = activeLogStreams.get(sessionId)
     let file: string | undefined
     if (entry && entry.file) file = entry.file