mobile-debug-mcp 0.32.2 → 0.33.0

package/src/observe/evidence.ts

@@ -0,0 +1,255 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { randomUUID } from 'node:crypto'
+
+export interface EvidenceDevice { platform: 'android' | 'ios'; id: string }
+export interface ActionRef { sessionId: string; actionId: string }
+type Kind = 'screenshot' | 'ui_tree' | 'fingerprint' | 'activity' | 'logs'
+type Freshness = 'fresh' | 'stale' | 'unknown' | 'not_applicable'
+interface Stamp { wall: number; mono: number }
+interface DeviceOrder { sequence: number; active: number; lastStarted: number }
+interface ActionRecord {
+  id: string; correlationId: string; device: EvidenceDevice | null
+  dispatchStart: Stamp | null; dispatchEnd: Stamp | null; verification: Stamp | null; completed: number | null
+}
+interface Component {
+  evidence_id: string; kind: Kind; status: 'captured' | 'failed' | 'omitted'
+  capture_started_at_ms: number | null; capture_completed_at_ms: number | null
+  source_captured_at_ms: number | null; age_ms: number | null
+  freshness: Freshness; freshness_reasons: string[]
+  device: EvidenceDevice | null; snapshot_session_id?: string; snapshot_revision?: number
+  error?: unknown; clock?: 'device_or_unknown'; event_time_comparable?: false
+  earliest_entry_at_ms?: number | null; latest_entry_at_ms?: number | null
+}
+interface Acquisition {
+  value: Component; start: Stamp; end: Stamp | null; order: DeviceOrder | null
+  startSequence: number; endSequence: number; overlapping: boolean; reused: boolean
+}
+interface EvidenceContext {
+  correlationId: string; action: ActionRecord | null; ref?: ActionRef
+  device: EvidenceDevice | null; start: Stamp; end: Stamp | null; verification: Stamp | null
+  observations: Acquisition[]; isAction: boolean; children: EvidenceContext[]
+}
+const sessionId = randomUUID()
+const context = new AsyncLocalStorage<EvidenceContext>()
+const history = new Map<string, ActionRecord>()
+const active = new Map<string, ActionRecord>()
+const orders = new Map<string, DeviceOrder>()
+const stamp = (): Stamp => ({ wall: Date.now(), mono: performance.now() })
+const deviceKey = (d: EvidenceDevice) => `${d.platform}:${d.id}`
+const sameDevice = (a: EvidenceDevice | null, b: EvidenceDevice | null) => !!a && !!b && deviceKey(a) === deviceKey(b)
+function validDevice(d: any): EvidenceDevice | null {
+  return d && ['android', 'ios'].includes(d.platform) && typeof d.id === 'string' && d.id && !['default', 'booted'].includes(d.id)
+    ? { platform: d.platform, id: d.id } : null
+}
+function orderFor(device: EvidenceDevice | null) {
+  if (!device) return null
+  const key = deviceKey(device)
+  let order = orders.get(key)
+  if (!order) {
+    order = { sequence: 0, active: 0, lastStarted: -Infinity }
+    orders.set(key, order)
+    if (orders.size > 1000) {
+      for (const [oldKey, oldOrder] of orders) {
+        if (oldKey !== key && oldOrder.active === 0) orders.delete(oldKey)
+        if (orders.size <= 1000) break
+      }
+    }
+  }
+  return order
+}
+function prune() {
+  const now = performance.now()
+  for (const [key, record] of history) {
+    if (record.completed !== null && now - record.completed >= 600000) history.delete(key)
+  }
+  while (history.size > 1000) history.delete(history.keys().next().value!)
+}
+export function validateActionRef(value: unknown): ActionRef | undefined {
+  if (value === undefined) return undefined
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+      Object.keys(value).some(key => !['sessionId', 'actionId'].includes(key))) throw new Error('INVALID_ARGUMENT: invalid actionRef')
+  const ref = value as ActionRef
+  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 currentEvidenceActionId() { return context.getStore()?.action?.id }
+export function bindEvidenceDevice(device: { platform: string; id: string }) {
+  const current = context.getStore()
+  const target = validDevice(device)
+  if (!current || !target) return
+  current.device ??= target
+  if (current.isAction && current.action) current.action.device ??= target
+}
+export function markEvidenceVerification() {
+  const current = context.getStore()
+  if (current) {
+    current.verification = stamp()
+    if (current.isAction && current.action) current.action.verification = current.verification
+  }
+}
+export async function evidenceDispatch<T>(device: EvidenceDevice, operation: () => Promise<T>): Promise<T> {
+  const current = context.getStore()
+  if (!current?.isAction || !current.action) return operation()
+  bindEvidenceDevice(device)
+  const record = current.action
+  const start = stamp()
+  record.dispatchStart ??= start
+  record.dispatchEnd = null
+  const order = orderFor(validDevice(device))
+  if (order) { order.sequence++; order.active++; order.lastStarted = start.mono }
+  try { return await operation() }
+  finally {
+    record.dispatchEnd = stamp()
+    if (order) order.active--
+  }
+}
+export function omitEvidence(kind: Kind) {
+  const current = context.getStore()
+  if (!current) return
+  const start = stamp()
+  current.observations.push({ value: {
+    evidence_id: randomUUID(), kind, status: 'omitted', capture_started_at_ms: null,
+    capture_completed_at_ms: null, source_captured_at_ms: null, age_ms: null,
+    freshness: kind === 'logs' ? 'not_applicable' : 'unknown', freshness_reasons: [], device: current.device
+  }, start, end: null, order: null, startSequence: 0, endSequence: 0, overlapping: false, reused: false })
+}
+export async function captureEvidence<T>(kind: Kind, device: EvidenceDevice | null, operation: () => Promise<T>): Promise<T> {
+  const current = context.getStore()
+  if (!current) return operation()
+  const target = validDevice(device)
+  if (target) bindEvidenceDevice(target)
+  const order = orderFor(target)
+  const start = stamp()
+  const acquisition: Acquisition = { value: {
+    evidence_id: randomUUID(), kind, status: 'failed', capture_started_at_ms: start.wall,
+    capture_completed_at_ms: null, source_captured_at_ms: null, age_ms: null,
+    freshness: 'unknown', freshness_reasons: [], device: target
+  }, start, end: null, order, startSequence: order?.sequence ?? 0,
+  endSequence: 0, overlapping: !!order?.active, reused: false }
+  current.observations.push(acquisition)
+  try {
+    const result = await operation() as any
+    const value = acquisition.value
+    const resolved = validDevice(result?.device) ?? target
+    value.device = resolved
+    if (resolved) bindEvidenceDevice(resolved)
+    const failure = result?.error ?? result?.meta?.error
+    value.status = failure || result?.success === false || (kind === 'fingerprint' && !result?.fingerprint) ? 'failed' : 'captured'
+    if (failure) value.error = failure
+    const source = result?.captured_at_ms
+    if (Number.isFinite(source) && source > 0) {
+      value.source_captured_at_ms = source
+      acquisition.reused = source < start.wall
+    }
+    if (kind === 'ui_tree') {
+      value.snapshot_session_id = result?.snapshot_session_id
+      value.snapshot_revision = result?.snapshot_revision
+    }
+    if (kind === 'logs') {
+      const entries = result?.logs ?? result?.entries ?? []
+      const times = entries.map((e: any) => {
+        const t = e?.timestamp ?? e?._iso
+        return typeof t === 'number' ? t : typeof t === 'string' ? Date.parse(t) : NaN
+      }).filter((t: number) => Number.isFinite(t)) as number[]
+      value.clock = 'device_or_unknown'; value.event_time_comparable = false
+      value.earliest_entry_at_ms = times.length ? times.reduce((a, b) => Math.min(a, b)) : null
+      value.latest_entry_at_ms = times.length ? times.reduce((a, b) => Math.max(a, b)) : null
+    }
+    return result
+  } catch (error) {
+    acquisition.value.error = error instanceof Error ? error.message : String(error)
+    throw error
+  } finally {
+    acquisition.end = stamp()
+    acquisition.value.capture_completed_at_ms = acquisition.end.wall
+    acquisition.endSequence = order?.sequence ?? 0
+    acquisition.overlapping ||= !!order?.active || acquisition.startSequence !== acquisition.endSequence
+    if (acquisition.value.status === 'captured' && acquisition.value.source_captured_at_ms === null && kind !== 'logs') {
+      acquisition.value.source_captured_at_ms = acquisition.end.wall
+    }
+  }
+}
+function association(current: EvidenceContext) {
+  if (current.isAction) return { association: 'self', association_reason: null }
+  if (!current.ref) return { association: 'none', association_reason: null }
+  const reason = current.ref.sessionId !== sessionId ? 'SESSION_MISMATCH' : !current.action ? 'ACTION_UNAVAILABLE' :
+    !sameDevice(current.device, current.action.device) ? 'DEVICE_MISMATCH' : null
+  return { association: reason ? 'unavailable' : 'explicit', association_reason: reason }
+}
+function assemble(current: EvidenceContext) {
+  const end = stamp()
+  const link = association(current)
+  const action = link.association === 'unavailable' ? null : current.action
+  const clockChanged = end.wall < current.start.wall
+  const observations = current.observations.map(a => {
+    const v = { ...a.value, freshness_reasons: [] as string[] }
+    if (v.status === 'omitted') return v
+    const componentAction = sameDevice(v.device, action?.device ?? null) ? action : null
+    const sourceMono = a.end && v.source_captured_at_ms !== null ? a.end.mono + v.source_captured_at_ms - a.end.wall : a.end?.mono
+    const reason = (freshness: Freshness, code: string) => { v.freshness = freshness; v.freshness_reasons.push(code) }
+    if (v.kind === 'logs') reason('unknown', 'DEVICE_CLOCK_UNVERIFIED')
+    else if (clockChanged || (a.end && a.end.wall < a.start.wall)) reason('unknown', 'CLOCK_DISCONTINUITY')
+    else if (v.source_captured_at_ms !== null && a.end && v.source_captured_at_ms > a.end.wall) reason('unknown', 'CLOCK_DISCONTINUITY')
+    else if (!v.device || !a.order || orders.get(deviceKey(v.device)) !== a.order || v.status !== 'captured' || !a.end) reason('unknown', 'CAPTURE_TIME_UNKNOWN')
+    else if (componentAction?.dispatchStart && sourceMono !== undefined && sourceMono < componentAction.dispatchStart.mono) reason('stale', 'BEFORE_ACTION')
+    else if (a.order && (a.order.sequence > a.endSequence || (a.reused && sourceMono !== undefined && sourceMono < a.order.lastStarted))) reason('stale', 'SUPERSEDED_BY_ACTION')
+    else if (a.overlapping) reason('unknown', 'OVERLAPPING_ACTION')
+    else if (a.reused) reason('unknown', 'REUSED_OBSERVATION')
+    else { v.freshness = 'fresh' }
+    if (!clockChanged && a.end && a.end.wall >= a.start.wall && v.source_captured_at_ms !== null && v.source_captured_at_ms <= end.wall) {
+      v.age_ms = Math.max(0, end.mono - a.end.mono + a.end.wall - v.source_captured_at_ms)
+    }
+    return { ...v, session_id: sessionId, correlation_id: componentAction?.correlationId ?? current.correlationId,
+      action_id: componentAction?.id ?? null, association: componentAction ? 'internal' : link.association }
+  })
+  return {
+    session_id: sessionId, correlation_id: action?.correlationId ?? current.correlationId,
+    action_id: action?.id ?? null, device: current.device, ...link,
+    ...(current.ref ? { requested_action_ref: current.ref } : {}),
+    operation_started_at_ms: current.start.wall, operation_completed_at_ms: current.end?.wall ?? end.wall,
+    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: [] }
+  }
+}
+export async function withEvidence<T>(options: { action?: boolean; journey?: boolean; ref?: ActionRef }, operation: () => Promise<T>): Promise<{ result: T; evidence: ReturnType<typeof assemble> }> {
+  prune()
+  const parent = context.getStore()
+  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(),
+    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)
+  try {
+    return await context.run(current, async () => {
+      const result = await operation()
+      current.end = stamp()
+      return { result, evidence: assemble(current) }
+    })
+  } finally {
+    if (options.action && record) {
+      active.delete(id); record.completed = performance.now(); history.set(id, record); prune()
+    }
+  }
+}
+
+export function refreshJourneyEvidence(steps: Array<{ result?: { evidence?: unknown } }>) {
+  const current = context.getStore()
+  if (!current) return
+  for (const step of steps) {
+    const previous = step.result?.evidence as { action_id?: string } | undefined
+    const child = current.children.find(c => c.action?.id === previous?.action_id)
+    if (child && step.result) step.result.evidence = assemble(child)
+  }
+}
+
+export function completeJourneyVerification(actionId: string) {
+  const child = context.getStore()?.children.find(c => c.action?.id === actionId)
+  if (child?.action) {
+    child.verification = stamp()
+    child.action.verification = child.verification
+  }
+}

package/src/observe/index.ts

@@ -1,4 +1,7 @@
+import { omitEvidence } from './evidence.js'
+import { withResolvedDevice } from '../utils/resolve-device.js'
 import { measure } from '../utils/timing.js'
+import { ReadinessTracker } from './readiness.js'
 import { resolveTargetDevice } from '../utils/resolve-device.js'
 import { AndroidObserve } from './android.js'
 import { iOSObserve } from './ios.js'
@@ -176,15 +179,20 @@ export class ToolsObserve {
 
   static async getUITreeHandler({ platform, deviceId, responseMode = 'debug', sinceSnapshotRevision }: { platform?: 'android' | 'ios', deviceId?: string, responseMode?: 'compact' | 'debug', sinceSnapshotRevision?: number }) {
     const { observe, resolved } = await ToolsObserve.resolveObserve(platform, deviceId)
+    const acquisitionStarted = Date.now()
     const tree = await observe.getUITree(resolved.id) as any
+    tree.readiness = new ReadinessTracker(resolved.platform, resolved.id).observe(tree, acquisitionStarted)
     if (responseMode !== 'compact') return tree
     const revision = tree?.snapshot_revision ?? null
+    const session = { snapshot_session_id: tree?.snapshot_session_id, readiness: tree.readiness }
+    if (tree?.error) return { ...session, delta_available: false, snapshot_revision: revision, error: tree.error }
     const baseRevision = sinceSnapshotRevision
     if (!Number.isInteger(baseRevision) || revision === null) {
-      return { delta_available: false, snapshot_revision: revision }
+      return { ...session, delta_available: false, snapshot_revision: revision }
     }
     const delta = getStateDelta(`${resolved.platform}:${resolved.id}`, baseRevision as number, revision)
-    return delta ? { delta_available: true, state_delta: delta, snapshot_revision: revision } : {
+    return delta ? { ...session, delta_available: true, state_delta: delta, snapshot_revision: revision } : {
+      ...session,
       delta_available: false,
       snapshot_revision: revision,
       reason: 'BASE_REVISION_UNAVAILABLE'
@@ -233,16 +241,24 @@ export class ToolsObserve {
     }
   }
 
-  static async readLogStreamHandler({ platform, sessionId, limit, since }: { platform?: 'android' | 'ios', sessionId?: string, limit?: number, since?: string }) {
+  static async readLogStreamHandler({ platform, sessionId, limit, since, deviceId }: { deviceId?: string, platform?: 'android' | 'ios', sessionId?: string, limit?: number, since?: string }) {
     const sid = sessionId || 'default'
-    const { observe } = await ToolsObserve.resolveObserve(platform)
-    return await (observe as any).readLogStream(sid, limit ?? 100, since)
+    const android = new AndroidObserve()
+    const ios = new iOSObserve()
+    const observe = platform === 'android' ? android : platform === 'ios' ? ios :
+      ios.getLogStreamDevice(sid) && !android.getLogStreamDevice(sid) ? ios : android
+    const streamDevice = observe.getLogStreamDevice(sid)
+    if (deviceId && streamDevice && streamDevice.id !== deviceId) throw new Error('LOG_STREAM_DEVICE_MISMATCH')
+    return await observe.readLogStream(sid, limit ?? 100, since)
   }
 
   static async stopLogStreamHandler({ platform, sessionId }: { platform?: 'android' | 'ios', sessionId?: string }) {
     const sid = sessionId || 'default'
-    const { observe } = await ToolsObserve.resolveObserve(platform)
-    return await (observe as any).stopLogStream(sid)
+    const android = new AndroidObserve()
+    const ios = new iOSObserve()
+    const observe = platform === 'android' ? android : platform === 'ios' ? ios :
+      ios.getLogStreamDevice(sid) && !android.getLogStreamDevice(sid) ? ios : android
+    return await observe.stopLogStream(sid)
   }
 
   static async captureScreenshotHandler({ platform, deviceId }: { platform?: 'android' | 'ios', deviceId?: string }) {
@@ -261,6 +277,14 @@ export class ToolsObserve {
   }
 
   static async captureDebugSnapshotHandler({ reason, includeLogs = true, includeScreenshot = true, logLines = 200, platform, appId, deviceId, sessionId }: { reason?: string; includeLogs?: boolean; includeScreenshot?: boolean; logLines?: number; platform?: 'android' | 'ios'; appId?: string; deviceId?: string; sessionId?: string } = {}) {
+    const { resolved } = await ToolsObserve.resolveObserve(platform, deviceId, appId)
+    return withResolvedDevice(resolved, () => ToolsObserve.collectDebugSnapshot({ reason, includeLogs, includeScreenshot, logLines,
+      platform: resolved.platform as 'android' | 'ios', appId, deviceId: resolved.id, sessionId }))
+  }
+
+  private static async collectDebugSnapshot({ reason, includeLogs = true, includeScreenshot = true, logLines = 200, platform, appId, deviceId, sessionId }: { reason?: string; includeLogs?: boolean; includeScreenshot?: boolean; logLines?: number; platform?: 'android' | 'ios'; appId?: string; deviceId?: string; sessionId?: string } = {}) {
+    if (!includeScreenshot) omitEvidence('screenshot')
+    if (!includeLogs) omitEvidence('logs')
     const timestamp = Date.now()
     const raw: CaptureDebugSnapshotRawResponse = {
       timestamp,
@@ -281,7 +305,7 @@ export class ToolsObserve {
       currentScreen: (!platform || platform === 'android') ? ToolsObserve.getCurrentScreenHandler({ deviceId }) : Promise.resolve(null),
       fingerprint: ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }),
       uiTree: ToolsObserve.getUITreeHandler({ platform, deviceId }),
-      readLogStream: includeLogs ? ToolsObserve.readLogStreamHandler({ platform, sessionId: sid, limit: logLines }) : Promise.resolve({ entries: [] }),
+      readLogStream: includeLogs ? ToolsObserve.readLogStreamHandler({ platform, deviceId, sessionId: sid, limit: logLines }) : Promise.resolve({ entries: [] }),
     }
 
     const results = await Promise.allSettled(Object.values(tasks))

package/src/observe/ios.ts

@@ -1,3 +1,5 @@
+import { randomUUID } from 'node:crypto'
+import { captureEvidence } from './evidence.js'
 import { spawn } from "child_process"
 import { remainingBudget } from '../utils/operation-budget.js'
 import { execCmd } from '../utils/exec.js'
@@ -283,10 +285,10 @@ export function traverseIDBNode(node: IDBElement, elements: UIElement[], parentI
   return currentIndex;
 }
 
-const iosActiveLogStreams: Map<string, { proc: ReturnType<typeof import('child_process').spawn>, file: string }> = new Map()
+const iosActiveLogStreams: Map<string, { proc: ReturnType<typeof import('child_process').spawn>, file: string, device?: { platform: 'android' | 'ios'; id: string } }> = new Map()
 
-export function _setIOSActiveLogStream(sessionId: string, file: string) {
-  iosActiveLogStreams.set(sessionId, { proc: {} as any, file })
+export function _setIOSActiveLogStream(sessionId: string, file: string, device?: { platform: 'android' | 'ios'; id: string }) {
+  iosActiveLogStreams.set(sessionId, { proc: {} as any, file, device })
 }
 
 export function _clearIOSActiveLogStream(sessionId: string) {
@@ -294,11 +296,17 @@ export function _clearIOSActiveLogStream(sessionId: string) {
 }
 
 export class iOSObserve {
+  getLogStreamDevice(sessionId: string = 'default') { return iosActiveLogStreams.get(sessionId)?.device ?? null }
+
   async getDeviceMetadata(deviceId: string = "booted"): Promise<DeviceInfo> {
     return getIOSDeviceMetadata(deviceId);
   }
 
   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: 'ios', 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 = 'booted', pid, tag, level, contains, since_seconds, limit } = filters
     const args: string[] = ['simctl', 'spawn', deviceId, 'log', 'show', '--style', 'syslog']
 
@@ -454,8 +462,12 @@ export class iOSObserve {
   }
 
   async captureScreenshot(deviceId: string = "booted"): Promise<CaptureIOSScreenshotResponse> {
+    return captureEvidence('screenshot', { platform: 'ios', id: deviceId ?? '' }, () => this.collectCaptureScreenshot(deviceId))
+  }
+
+  private async collectCaptureScreenshot(deviceId: string = "booted"): Promise<CaptureIOSScreenshotResponse> {
     const device = await getIOSDeviceMetadata(deviceId)
-    const tmpFile = `/tmp/mcp-ios-screenshot-${Date.now()}.png`
+    const tmpFile = `/tmp/mcp-ios-screenshot-${randomUUID()}.png`
 
     try {
       await iosExecCommand(['simctl', 'io', deviceId, 'screenshot', tmpFile], deviceId)
@@ -527,6 +539,10 @@ export class iOSObserve {
   }
 
   async getUITree(deviceId: string = "booted"): Promise<GetUITreeResponse> {
+    return captureEvidence('ui_tree', { platform: 'ios', id: deviceId ?? '' }, () => this.collectGetUITree(deviceId))
+  }
+
+  private async collectGetUITree(deviceId: string = "booted"): Promise<GetUITreeResponse> {
     const measurement = createObservationMeasurement('ios')
     let device
     try {
@@ -653,12 +669,16 @@ export class iOSObserve {
     }
   }
 
-  async getScreenFingerprint(deviceId: string = 'booted'): Promise<{ fingerprint: string | null; activity?: string; error?: string }> {
+  async getScreenFingerprint(deviceId: string = 'booted'): Promise<{ fingerprint: string | null; activity?: string; error?: string; captured_at_ms?: number }> {
+    return captureEvidence('fingerprint', { platform: 'ios', id: deviceId ?? '' }, () => this.collectGetScreenFingerprint(deviceId))
+  }
+
+  private async collectGetScreenFingerprint(deviceId: string = 'booted'): Promise<{ fingerprint: string | null; activity?: string; error?: string; captured_at_ms?: number }> {
     try {
       const tree = await this.getUITree(deviceId)
       if (!tree || tree.error) return { fingerprint: null, error: tree && (tree as any).error }
 
-      return computeScreenFingerprint(tree, null, 'ios', 50)
+      return { ...computeScreenFingerprint(tree, null, 'ios', 50), captured_at_ms: tree.captured_at_ms }
     } catch (e) {
       return { fingerprint: null, error: e instanceof Error ? e.message : String(e) }
     }
@@ -701,10 +721,10 @@ export class iOSObserve {
 
       proc.on('close', () => {
         stream.end()
-        iosActiveLogStreams.delete(sessionId)
+        if (iosActiveLogStreams.get(sessionId)?.proc === proc) iosActiveLogStreams.delete(sessionId)
       })
 
-      iosActiveLogStreams.set(sessionId, { proc, file })
+      iosActiveLogStreams.set(sessionId, { proc, file, device: { platform: 'ios', id: deviceId ?? '' } })
       return { success: true, stream_started: true }
     } catch {
       return { success: false, error: 'log_stream_start_failed' }
@@ -720,6 +740,10 @@ export class iOSObserve {
   }
 
   async readLogStream(sessionId: string = 'default', limit: number = 100, since?: string): Promise<{ entries: any[], crash_summary?: { crash_detected: boolean, exception?: string, sample?: string } }> {
+    return captureEvidence('logs', this.getLogStreamDevice(sessionId), () => this.collectReadLogStream(sessionId, limit, since))
+  }
+
+  private async collectReadLogStream(sessionId: string = 'default', limit: number = 100, since?: string): Promise<{ entries: any[], crash_summary?: { crash_detected: boolean, exception?: string, sample?: string } }> {
     const entry = iosActiveLogStreams.get(sessionId)
     if (!entry) return { entries: [] }
     try {

package/src/observe/readiness-service.ts

@@ -0,0 +1,89 @@
+import type { DeviceInfo } from '../types.js'
+import { resolveTargetDevice, withResolvedDevice } from '../utils/resolve-device.js'
+import { remainingBudget, runWithBudget } from '../utils/operation-budget.js'
+import { ToolsObserve } from './index.js'
+import { isDeviceUnavailable, ReadinessTracker, withReadinessTracker } from './readiness.js'
+
+type Target = { platform?: 'android' | 'ios'; deviceId?: string }
+function budgetExpired(error: unknown) {
+  if (/ACTION_TIMEOUT/.test(String(error))) return true
+  try { remainingBudget(); return false } catch { return true }
+}
+async function resolve(target: Target) {
+  if (target.platform) return resolveTargetDevice({ ...target, platform: target.platform })
+  try { return await resolveTargetDevice({ ...target, platform: 'android' }) }
+  catch { return resolveTargetDevice({ ...target, platform: 'ios' }) }
+}
+export async function readinessDelay(ms: number) {
+  await new Promise(resolve => setTimeout(resolve, Math.min(ms, remainingBudget(ms))))
+  remainingBudget()
+}
+
+export async function getAppReadiness(args: Target & { timeoutMs?: number; stabilityMs?: number; pollIntervalMs?: number }, wait = false) {
+  const started = performance.now()
+  let device: DeviceInfo | null = null
+  let tracker = new ReadinessTracker(args.platform ?? 'android', args.deviceId ?? '')
+  let failureCode: string | undefined
+  await runWithBudget(args.timeoutMs ?? (wait ? 30000 : 15000), async () => {
+    try {
+      device = await resolve(args)
+      remainingBudget()
+      tracker = new ReadinessTracker(device.platform, device.id, args.stabilityMs ?? 500)
+      await withResolvedDevice(device, async () => {
+        let count = 0
+        while (wait || count < 2) {
+          remainingBudget()
+          const captureStarted = Date.now()
+          try {
+            const tree = await ToolsObserve.getUITreeHandler({ platform: device!.platform as 'android' | 'ios', deviceId: device!.id })
+            remainingBudget()
+            tracker.observe(tree, captureStarted)
+            if (isDeviceUnavailable((tree as any)?.error)) { failureCode = 'DEVICE_UNAVAILABLE'; return }
+          } catch (error) {
+            if (/ACTION_TIMEOUT/.test(String(error))) throw error
+            tracker.unavailable()
+            if (isDeviceUnavailable(error)) { failureCode = 'DEVICE_UNAVAILABLE'; return }
+          }
+          count++
+          if (tracker.summary.state === 'settled' || (!wait && tracker.summary.state === 'loading')) return
+          if (!wait && count === 2) return
+          await readinessDelay(wait ? args.pollIntervalMs ?? 500 : args.stabilityMs ?? 500)
+        }
+      })
+    } catch (error) {
+      const expired = budgetExpired(error)
+      if (expired) tracker.deadline()
+      else tracker.unavailable()
+      failureCode = !expired && (!device || isDeviceUnavailable(error)) ? 'DEVICE_UNAVAILABLE' : wait ? 'READINESS_TIMEOUT' : 'READINESS_UNAVAILABLE'
+    }
+  })
+  const state = tracker.summary.state
+  const success = !failureCode && (wait ? state === 'settled' : state !== 'unknown')
+  return { success, device, readiness: tracker.summary, elapsed_ms: performance.now() - started,
+    ...(!success ? { failure_code: failureCode ?? (wait ? 'READINESS_TIMEOUT' : 'READINESS_UNAVAILABLE') } : {}) }
+}
+
+export async function withReadyWait<T extends object | undefined, F extends object>(target: Target, timeoutMs: number, operation: (device: DeviceInfo) => Promise<T>, failure: (code: string, elapsedMs: number, samples: number) => F) {
+  const started = performance.now()
+  let tracker = new ReadinessTracker(target.platform ?? 'android', target.deviceId ?? '')
+  let resolved = false
+  return runWithBudget(timeoutMs, async () => {
+    try {
+      const device = await resolve(target)
+      resolved = true
+      remainingBudget()
+      tracker = new ReadinessTracker(device.platform, device.id)
+      const result = await withResolvedDevice(device, () => withReadinessTracker(tracker, () => operation(device)))
+      try { remainingBudget() } catch {
+        const alreadyFailed = result && (('status' in result && result.status !== 'success') || ('success' in result && result.success === false))
+        return { ...(alreadyFailed ? result : failure('TIMEOUT', performance.now() - started, tracker.summary.sample_count)), readiness: tracker.deadline() }
+      }
+      return { ...result, readiness: tracker.summary }
+    } catch (error) {
+      const expired = budgetExpired(error)
+      if (expired) tracker.deadline()
+      else tracker.unavailable()
+      return { ...failure(!expired && (!resolved || isDeviceUnavailable(error)) ? 'DEVICE_UNAVAILABLE' : 'TIMEOUT', performance.now() - started, tracker.summary.sample_count), readiness: tracker.summary }
+    }
+  })
+}

package/src/observe/readiness.ts

@@ -0,0 +1,78 @@
+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 capabilities = { loading: true, transitioning: true, settled: true, unresponsive: false, debugger_paused: false }
+
+export function isDeviceUnavailable(error: unknown) {
+  return /device.*(?:not found|offline|disconnected)|no devices found|READINESS_DEVICE_UNAVAILABLE/i.test(String(error))
+}
+
+export class ReadinessTracker {
+  private signature: string | null = null
+  private stableSince = 0
+  summary: ReadinessSummary = {
+    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 }
+  }
+
+  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],
+      evidence: [...this.summary.evidence, { code, source: 'ui_tree', captured_at_ms: null, snapshot_revision: null }].slice(-8) }
+    return this.summary
+  }
+
+  deadline(): ReadinessSummary {
+    this.summary = { ...this.summary, limitations: [...new Set([...this.summary.limitations, 'DEADLINE_EXCEEDED'])] }
+    return this.summary
+  }
+
+  observe(tree: any, acquisitionStartedAtMs: number, now = performance.now()): ReadinessSummary {
+    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 ||
+        !Number.isFinite(tree.captured_at_ms) || tree.captured_at_ms < acquisitionStartedAtMs || tree.captured_at_ms <= 0 ||
+        !Array.isArray(tree.elements) || !tree.elements.length || tree.elements.some((element: unknown) => !element || typeof element !== 'object') ||
+        !Number.isFinite(tree.resolution?.width) || !Number.isFinite(tree.resolution?.height) || tree.resolution.width <= 0 || tree.resolution.height <= 0) return this.unavailable('OBSERVATION_INVALID')
+    const signature = computeSnapshotSignature(tree)
+    if (!signature) return this.unavailable('OBSERVATION_INVALID')
+    const nativeLoading = tree.elements.some((element: any) => element.visible === true && ['android.widget.ProgressBar', 'ActivityIndicator', 'ProgressIndicator'].includes(element.type))
+    const textLoading = tree.elements.some((element: any) => element.visible === true && [element.text, element.contentDescription].some(label =>
+      typeof label === 'string' && /^(loading|please\s+wait)[.\s…]*$/i.test(label.trim())))
+    const previous = this.signature
+    const unchanged = previous === signature
+    if (!unchanged || nativeLoading || textLoading) this.stableSince = now
+    this.signature = signature
+    const stableFor = unchanged && !nativeLoading && !textLoading ? Math.max(0, now - this.stableSince) : 0
+    const state = nativeLoading || textLoading ? 'loading' : !previous ? 'unknown' : !unchanged ? 'transitioning' : stableFor >= this.stabilityMs ? 'settled' : 'unknown'
+    const code = nativeLoading ? 'NATIVE_LOADING_INDICATOR' : textLoading ? 'LOADING_LABEL' : state === 'transitioning' ? 'SNAPSHOT_CHANGED' : state === 'settled' ? 'SNAPSHOT_STABLE' : 'INSUFFICIENT_SAMPLES'
+    this.summary = {
+      state, scope: 'device_ui', basis: textLoading && !nativeLoading ? 'heuristic' : state === 'unknown' ? 'insufficient' : 'observed',
+      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 }
+    }
+    return this.summary
+  }
+}
+
+const waits = new AsyncLocalStorage<ReadinessTracker>()
+export function currentReadinessWait() { return waits.getStore() }
+export function withReadinessTracker<T>(tracker: ReadinessTracker, operation: () => Promise<T>) { return waits.run(tracker, operation) }
+
+export function observeReadinessWait(tree: unknown, startedAtMs: number) {
+  const tracker = waits.getStore()
+  if (!tracker) return
+  remainingBudget()
+  const summary = tracker.observe(tree, startedAtMs)
+  if (isDeviceUnavailable((tree as any)?.error)) throw new Error('READINESS_DEVICE_UNAVAILABLE')
+  if (summary.limitations.some(code => ['OBSERVATION_INVALID', 'OBSERVATION_FAILED'].includes(code))) throw new Error('READINESS_SAMPLE_INVALID')
+}

package/src/observe/snapshot-metadata.ts

@@ -14,8 +14,18 @@ interface SnapshotState {
 }
 
 let nextRevision = 1
+const snapshotSessionId = crypto.randomUUID()
 const snapshotStateByDevice = new Map<string, SnapshotState>()
 
+export function getSnapshotSessionId() { return snapshotSessionId }
+
+export function hasSnapshotBaseline(deviceKey: string, revision: number) {
+  const state = snapshotStateByDevice.get(deviceKey)
+  const capturedAt = state?.historyTimes.get(revision)
+  return !!state && capturedAt !== undefined && state.history.has(revision) &&
+    Date.now() - capturedAt <= 10 * 60 * 1000 && Date.now() - state.updatedAt <= 10 * 60 * 1000
+}
+
 function normalize(value: unknown): string {
   if (value === null || value === undefined) return ''
   return String(value).trim().toLowerCase()
@@ -163,7 +173,7 @@ export function deriveSnapshotMetadata(
   const oversized = previous?.oversized ?? new Map<number, number>()
   if (hasValidTree) {
     history.set(revision, currentElements)
-    if (!historyTimes.has(revision)) historyTimes.set(revision, Date.now())
+    historyTimes.set(revision, Date.now())
     if ((tree.elements?.length ?? 0) > 500) oversized.set(revision, (tree.elements?.length ?? 0) - 500)
   }
   for (const [id, timestamp] of historyTimes) {
@@ -191,6 +201,7 @@ export function deriveSnapshotMetadata(
   })
 
   return {
+    snapshot_session_id: snapshotSessionId,
     snapshot_revision: revision,
     captured_at_ms: Date.now(),
     snapshot_delta: hasValidTree ? summarizeSnapshotDelta(previous, currentElementSignatures) : null,