mobile-debug-mcp 0.32.4 → 0.34.0

package/test/helpers/perfetto.ts

@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict'
+
+// Minimal local protobuf reader for format/content evidence, not trace analysis.
+// Field numbers: google/perfetto protos/perfetto/trace/{trace,trace_packet}.proto
+// and trace/ftrace/{ftrace_event_bundle,ftrace_event}.proto. Unknown fields skipped.
+export function protobufFields(bytes: Buffer): Array<{ field: number; wire: number; value: Buffer | bigint }> {
+  let offset = 0
+  const result: Array<{ field: number; wire: number; value: Buffer | bigint }> = []
+  function varint() {
+    let value = 0n
+    for (let shift = 0n; shift < 70n; shift += 7n) {
+      assert.ok(offset < bytes.length, 'Truncated protobuf varint')
+      const byte = bytes[offset++]
+      value |= BigInt(byte & 127) << shift
+      if (!(byte & 128)) return value
+    }
+    throw new Error('Oversized protobuf varint')
+  }
+  while (offset < bytes.length) {
+    const key = Number(varint()), field = Math.floor(key / 8), wire = key % 8
+    assert.ok(field > 0)
+    let value: Buffer | bigint
+    if (wire === 0) value = varint()
+    else {
+      const length = wire === 2 ? Number(varint()) : wire === 1 ? 8 : wire === 5 ? 4 : -1
+      assert.ok(Number.isSafeInteger(length) && length >= 0 && length <= bytes.length - offset, 'Invalid protobuf length/wire')
+      value = bytes.subarray(offset, offset + length); offset += length
+    }
+    result.push({ field, wire, value })
+  }
+  return result
+}
+export function inspectPerfetto(bytes: Buffer, duration: number) {
+  const root = protobufFields(bytes)
+  assert.ok(root.length > 0)
+  assert.ok(root.every(f => f.field === 1 && f.wire === 2), 'Trace.packet must be repeated length-delimited messages')
+  const packets = root.map(f => protobufFields(f.value as Buffer))
+  const config = packets.flat().find(f => f.field === 33 && f.wire === 2)
+  assert.ok(config, 'Missing TracePacket.trace_config')
+  assert.equal(protobufFields(config.value as Buffer).find(f => f.field === 3)?.value, BigInt(duration))
+  const bundles = packets.flat().filter(f => f.field === 1 && f.wire === 2).map(f => protobufFields(f.value as Buffer))
+  let events = 0, compactBundles = 0
+  for (const bundle of bundles) {
+    for (const f of bundle) {
+      if (f.field === 2 && f.wire === 2) {
+        const event = protobufFields(f.value as Buffer)
+        assert.ok(event.some(e => e.field === 1 && e.wire === 0), 'FtraceEvent timestamp missing')
+        events++
+      }
+      if (f.field === 4 && f.wire === 2) {
+        assert.ok(protobufFields(f.value as Buffer).some(e => [1, 7].includes(e.field) && e.wire === 2))
+        compactBundles++
+      }
+    }
+  }
+  assert.ok(events + compactBundles > 0, 'No captured kernel/scheduler events')
+  return { packets: packets.length, ftrace_bundles: bundles.length, events, compact_sched_bundles: compactBundles,
+    validation: 'local protobuf structure, trace config duration and timestamped ftrace/compact scheduler content; not full Perfetto analysis' }
+}

package/test/unit/debugger/guards.test.ts

@@ -0,0 +1,46 @@
+import assert from 'node:assert/strict'
+import { debuggerSessions } from '../../../src/debugger/sessions.js'
+import { withDebuggerGuard, checkDebuggerGuard } from '../../../src/debugger/guard.js'
+import { handleToolCall } from '../../../src/server-core.js'
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { getAppReadiness } from '../../../src/observe/readiness-service.js'
+const originalPause = debuggerSessions.paused
+const originalActive = debuggerSessions.hasActiveSessions
+const originalTree = ToolsObserve.getUITreeHandler
+const originalWait = ToolsInteract.waitForUIHandler
+let paused = true
+const pause: any = { debug_session_id: 'session', target: { app_id: 'test.app', pid: 10 }, state: 'paused', captured_at_ms: 1000 }
+debuggerSessions.paused = device => paused && device === 'fixture' ? pause : null
+debuggerSessions.hasActiveSessions = () => true
+_setDeviceListersForTests({ listAndroidDevices: async () => [{ id: 'fixture', platform: 'android' } as any] })
+const payload = (response: any) => JSON.parse(response.content.find((c: any) => c.type === 'text').text)
+try {
+  ToolsObserve.getUITreeHandler = async () => { throw new Error('Paused readiness must not acquire a UI tree') }
+  const readiness = await getAppReadiness({ platform: 'android', deviceId: 'fixture' })
+  assert.equal(readiness.readiness.state, 'debugger_paused')
+  const wait = await getAppReadiness({ platform: 'android', deviceId: 'fixture' }, true)
+  assert.equal(wait.failure_code, 'DEBUGGER_PAUSED')
+  const blocked = payload(await handleToolCall('tap', { platform: 'android', deviceId: 'fixture', x: 1, y: 1 }))
+  assert.equal(blocked.delivery_status, 'not_delivered')
+  await withDebuggerGuard('android', 'other', async () => checkDebuggerGuard(true))
+  await assert.rejects(withDebuggerGuard('android', 'fixture', async () => checkDebuggerGuard()), /DEBUGGER_PAUSED/)
+  paused = false
+  let calls = 0
+  ToolsInteract.waitForUIHandler = async () => { calls++; if (calls === 2) paused = true; return { status: 'success' } as any }
+  const journey = payload(await handleToolCall('run_journey', { platform: 'android', deviceId: 'fixture', responseMode: 'compact', steps: [
+    { id: 'first', type: 'wait', selector: { text: 'First' } },
+    { id: 'second', type: 'wait', selector: { text: 'Second' } },
+    { id: 'third', type: 'wait', selector: { text: 'Third' } }
+  ] }))
+  assert.equal(journey.steps[0].status, 'passed', 'completed steps survive a later pause')
+  assert.equal(journey.steps[1].success, false)
+  assert.equal(journey.steps[1].result.failure_code, 'DEBUGGER_PAUSED')
+  assert.equal(calls, 2, 'no action queued or retried after pause')
+  console.log('PASS debugger readiness without UI acquisition, device scoping, dispatch guard, mid-journey pause preservation')
+} finally {
+  debuggerSessions.paused = originalPause; debuggerSessions.hasActiveSessions = originalActive
+  ToolsObserve.getUITreeHandler = originalTree; ToolsInteract.waitForUIHandler = originalWait
+  _resetDeviceListersForTests()
+}

package/test/unit/debugger/native.test.ts

@@ -0,0 +1,33 @@
+import assert from 'node:assert/strict'
+import { AndroidDebugNative } from '../../../src/debugger/android.js'
+import { DebuggerError, debuggerRemaining, withDebuggerBudget } from '../../../src/debugger/worker.js'
+class Native extends AndroidDebugNative {
+  calls: string[][] = []
+  forwards = 'device tcp:1234 jdwp:10\nother tcp:3456 jdwp:20'
+  async adb(_device: string, args: string[]) {
+    this.calls.push(args)
+    if (args[0] === 'forward' && args[1] === '--list') return this.forwards
+    if (args.at(-1)?.endsWith('/stat')) return '10 (complex process name) S ' + Array(18).fill('0').join(' ') + ' 999 0'
+    if (args.at(-1)?.endsWith('/status')) return 'Name:\ttest\nUid:\t42\t42\t42\t42'
+    if (args.at(-1)?.endsWith('/cmdline')) return 'test.app\0'
+    return ''
+  }
+}
+const native = new Native()
+await native.removeForward('device', 1234, 10)
+assert.deepEqual(native.calls.at(-1), ['forward', '--remove', 'tcp:1234'])
+await assert.rejects(native.removeForward('device', 3456, 10), /DEBUGGER_CLEANUP_FAILED/)
+const before = native.calls.length
+await native.removeForward('device', 9999, 10)
+assert.equal(native.calls.length, before + 1, 'absent owned forward requires no removal')
+const target = { app_id: 'test.app', pid: 10, process_name: 'test.app', start_identity: '', uid: 42 }
+assert.equal((await native.identity('device', target)).start_identity, '999')
+await assert.rejects(native.identity('device', { ...target, start_identity: 'old' }), /PROCESS_CHANGED/)
+await assert.rejects(native.identity('device', { ...target, uid: 44 }), /PROCESS_CHANGED/)
+await assert.rejects(native.candidates('device', 'test.app;evil'), /INVALID_ARGUMENT/)
+const aborted = new AbortController(); aborted.abort()
+await assert.rejects(withDebuggerBudget(100, aborted.signal, async () => debuggerRemaining(10)), /DEBUGGER_CANCELLED/)
+await assert.rejects(withDebuggerBudget(-1, undefined, async () => debuggerRemaining(10)), /DEBUGGER_TIMEOUT/)
+assert.equal(await withDebuggerBudget(100, undefined, async () => debuggerRemaining(10)), 10)
+assert.equal(new DebuggerError('DEBUGGER_TIMEOUT').code, 'DEBUGGER_TIMEOUT')
+console.log('PASS debugger native identity, PID reuse, forward ownership, deadlines and cancellation')

package/test/unit/debugger/sessions.test.ts

@@ -0,0 +1,83 @@
+import assert from 'node:assert/strict'
+import { DebuggerSessions, debuggerExpiry } from '../../../src/debugger/sessions.js'
+import { DebuggerError, type WorkerEvent } from '../../../src/debugger/worker.js'
+import type { DebugNative, DebugTarget } from '../../../src/debugger/android.js'
+import { debuggerContracts, debuggerTools } from '../../../src/server/debugger-schema.js'
+assert.equal(debuggerExpiry(0, 0, 0, 59999), null)
+assert.equal(debuggerExpiry(0, 60000, 0, 60000), 'pause_limit', 'polling cannot extend pause expiry')
+assert.equal(debuggerExpiry(0, 0, undefined, 300000), 'idle_limit')
+assert.equal(debuggerExpiry(0, 1800000, undefined, 1800000), 'session_limit', 'activity cannot extend lifetime')
+const target: DebugTarget = { app_id: 'test.app', pid: 123, uid: 456, process_name: 'test.app', start_identity: '100' }
+let candidates = [target]
+let removed = 0
+let emit: (event: WorkerEvent) => void = () => {}
+let close = 0
+let failCleanup = false
+let failCommand = ''
+const native: DebugNative = {
+  candidates: async () => candidates, identity: async () => target, forward: async () => 12345,
+  removeForward: async () => { if (failCleanup) throw new Error('offline'); removed++ }
+}
+const sessions = new DebuggerSessions(native, async event => {
+  emit = event
+  return { call: async (command: string) => { if (command === failCommand) throw new DebuggerError('DEBUGGER_TIMEOUT'); return { state: 'running', breakpoints: [] } }, close: async () => { close++ } }
+}, async () => ({ java: 'java', directory: '/unused' }))
+try {
+  candidates = [target, { ...target, pid: 124 }]
+  const ambiguous = await sessions.attach('emulator', 'test.app')
+  assert.equal(ambiguous.error.code, 'PROCESS_AMBIGUOUS')
+  assert.equal(removed, 0)
+  candidates = [target]
+  const first = await sessions.attach('emulator', 'test.app')
+  const id = first.debug_session_id
+  assert.equal(first.state, 'running')
+  await assert.rejects(sessions.attach('emulator', 'test.app'), /DEBUGGER_BUSY/)
+  emit({ event: 'stopped', stop_id: 'stop-1', thread_id: 't1', stops: [] })
+  assert.equal(sessions.paused('emulator')?.stop.stop_id, 'stop-1')
+  assert.equal(sessions.paused('other'), null)
+  assert.throws(() => sessions.assertRunning('emulator'), /DEBUGGER_PAUSED/)
+  const pendingWait = sessions.command(id, 'events', { afterSequence: 1 }, 500)
+  await sessions.command(id, 'resume', { stopId: 'stop-1' })
+  assert.equal(sessions.paused('emulator'), null)
+  await assert.rejects(sessions.command(id, 'locals', { stopId: 'stop-1', frameId: 'old' }), /DEBUGGER_STALE_REFERENCE/)
+  emit({ event: 'stopped', stop_id: 'stop-2', thread_id: 't2' })
+  assert.equal((await pendingWait).events[0].stop_id, 'stop-2', 'event wait cannot block resume')
+  for (let i = 0; i < 260; i++) emit({ event: 'breakpoint', i })
+  const events = await sessions.command(id, 'events', { afterSequence: 0 }, 100)
+  assert.equal(events.overflow, true); assert.equal(events.events.length, 100)
+  await assert.rejects(sessions.command(id, 'events', { afterSequence: 9999 }, 100), /INVALID_ARGUMENT/)
+  const controller = new AbortController(); controller.abort()
+  await assert.rejects(sessions.command(id, 'events', { afterSequence: 262, signal: controller.signal }, 100), /DEBUGGER_CANCELLED/)
+  failCommand = 'locals'
+  await assert.rejects(sessions.command(id, 'locals', { stopId: 'stop-2' }, 100), /DEBUGGER_TIMEOUT/)
+  assert.equal(sessions.paused('emulator')?.state, 'paused', 'inspection timeout preserves known suspension')
+  failCommand = 'step'
+  await assert.rejects(sessions.command(id, 'step', { stopId: 'stop-2', threadId: 't2' }, 100), /DEBUGGER_TIMEOUT/)
+  assert.equal((await sessions.command(id, 'state')).cleanup.status, 'complete')
+  assert.equal(close, 1); assert.equal(removed, 1)
+  failCommand = ''
+  const second = await sessions.attach('emulator', 'test.app')
+  failCleanup = true
+  const partial = await sessions.command(second.debug_session_id, 'detach')
+  assert.equal(partial.success, false); assert.equal(partial.cleanup.status, 'failed')
+  await assert.rejects(sessions.attach('emulator', 'test.app'), /DEBUGGER_BUSY/)
+  failCleanup = false
+  const retry = await sessions.command(second.debug_session_id, 'detach')
+  assert.equal(retry.cleanup.status, 'complete'); assert.equal(close, 2)
+  assert.equal((await sessions.command(second.debug_session_id, 'detach')).cleanup.status, 'complete')
+  const third = await sessions.attach('emulator', 'test.app')
+  emit({ event: 'worker_failed' })
+  const crashed = await sessions.command(third.debug_session_id, 'state')
+  assert.equal(crashed.state, 'failed')
+  assert.equal(crashed.cleanup.status, 'complete')
+  assert.equal(crashed.error.code, 'DEBUGGER_WORKER_FAILED')
+  assert.equal(sessions.paused('emulator'), null)
+  for (const tool of debuggerTools) {
+    const contract = debuggerContracts[tool.name]
+    assert.equal(tool.inputSchema.additionalProperties, false)
+    assert.equal(contract.schema.safeParse({ ...Object.fromEntries(tool.inputSchema.required.map(k => [k, 'x'])), unexpected: true }).success, false)
+  }
+  assert.equal(debuggerContracts.attach_debugger.schema.safeParse({ platform: 'android', appId: 'test.app' }).success, false)
+  assert.equal(debuggerContracts.set_debugger_breakpoint.schema.safeParse({ debugSessionId: 's', className: '$(bad)', line: 2 }).success, false)
+  console.log('PASS debugger session ownership, stop epochs, event concurrency/overflow, timeout recovery, cleanup retries, strict contracts')
+} finally { await sessions.shutdown() }

package/test/unit/observe/android_tree_acquisition.test.ts

@@ -36,6 +36,8 @@ else process.exit(1)
     const first = await observe.getUITree('fake-a')
     const second = await observe.getUITree('fake-b')
     assert.equal(first.error, undefined)
+    assert.equal(typeof first.snapshot_session_id, 'string')
+    assert.equal(first.snapshot_session_id, second.snapshot_session_id)
     assert.equal(second.error, undefined)
     assert.equal(first.snapshot_revision, 1)
     assert.notEqual(first.snapshot_revision, second.snapshot_revision)

package/test/unit/observe/capture_debug_snapshot.test.ts

@@ -1,5 +1,6 @@
 import { ToolsObserve } from '../../../src/observe/index.js'
 import assert from 'assert'
+import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
 
 async function run() {
   console.log('Starting capture_debug_snapshot unit tests...')
@@ -12,24 +13,41 @@ async function run() {
   const origReadLogStreamHandler = (ToolsObserve as any).readLogStreamHandler
   const origGetLogsHandler = (ToolsObserve as any).getLogsHandler
 
+  const device = { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true }
+  let resolutions = 0
+  _setDeviceListersForTests({
+    listAndroidDevices: async () => { resolutions++; return [device] },
+    listIOSDevices: async () => { throw new Error('Android snapshot must not discover iOS devices') }
+  })
+  const assertTarget = (args: any) => {
+    assert.strictEqual(args.platform, 'android')
+    assert.strictEqual(args.deviceId, device.id, 'Every component must use the resolved fixture device')
+  }
+
   try {
     // --- Test 1: all components succeed and logs come from stream ---
-    ;(ToolsObserve as any).captureScreenshotHandler = async function() {
+    ;(ToolsObserve as any).captureScreenshotHandler = async function(args: any) {
+      assertTarget(args)
       return { device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true }, screenshot: 'BASE64PNG', resolution: { width: 1080, height: 1920 } }
     }
-    ;(ToolsObserve as any).getCurrentScreenHandler = async function() {
+    ;(ToolsObserve as any).getCurrentScreenHandler = async function(args: any) {
+      assert.strictEqual(args.deviceId, device.id)
       return { device: { platform: 'android', id: 'mock' }, package: 'com.example', activity: 'com.example.Main', shortActivity: 'Main' }
     }
-    ;(ToolsObserve as any).getScreenFingerprintHandler = async function() {
+    ;(ToolsObserve as any).getScreenFingerprintHandler = async function(args: any) {
+      assertTarget(args)
       return { fingerprint: 'abc123', activity: 'Main' }
     }
-    ;(ToolsObserve as any).getUITreeHandler = async function() {
+    ;(ToolsObserve as any).getUITreeHandler = async function(args: any) {
+      assertTarget(args)
       return { device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true }, screen: '', resolution: { width: 1080, height: 1920 }, elements: [] }
     }
-    ;(ToolsObserve as any).readLogStreamHandler = async function() {
+    ;(ToolsObserve as any).readLogStreamHandler = async function(args: any) {
+      assertTarget(args)
       return { entries: [ { timestamp: '2026-03-23T20:00:00.000Z', level: 'ERROR', message: 'Boom' } ], crash_summary: { crash_detected: true } }
     }
-    ;(ToolsObserve as any).getLogsHandler = async function() {
+    ;(ToolsObserve as any).getLogsHandler = async function(args: any) {
+      assertTarget(args)
       return { device: { platform: 'android', id: 'mock' }, logs: [], logCount: 0 }
     }
 
@@ -41,20 +59,13 @@ async function run() {
     assert.strictEqual(res1.semantic.confidence >= 0.7, true)
     assert.deepStrictEqual(res1.semantic.actions_available, null)
     console.log('Test 1:', pass1 ? 'PASS' : 'FAIL')
-
-    // Restore handlers before next test
-    ;(ToolsObserve as any).captureScreenshotHandler = origCaptureHandler
-    ;(ToolsObserve as any).getCurrentScreenHandler = origGetCurrentHandler
-    ;(ToolsObserve as any).getScreenFingerprintHandler = origGetFpHandler
-    ;(ToolsObserve as any).getUITreeHandler = origGetTreeHandler
-    ;(ToolsObserve as any).readLogStreamHandler = origReadLogStreamHandler
-    ;(ToolsObserve as any).getLogsHandler = origGetLogsHandler
+    assert.strictEqual(resolutions, 1, 'Resolve one device for the entire snapshot')
 
     // --- Test 2: screenshot and ui tree fail; logs fallback to getLogs ---
-    ;(ToolsObserve as any).captureScreenshotHandler = async function() { throw new Error('screencap failed') }
-    ;(ToolsObserve as any).getUITreeHandler = async function() { throw new Error('uie_error') }
-    ;(ToolsObserve as any).readLogStreamHandler = async function() { return { entries: [] } }
-    ;(ToolsObserve as any).getLogsHandler = async function() { return { device: { platform: 'android', id: 'mock' }, logs: ['INFO starting','ERROR crash here'], logCount: 2 } }
+    ;(ToolsObserve as any).captureScreenshotHandler = async function(args: any) { assertTarget(args); throw new Error('screencap failed') }
+    ;(ToolsObserve as any).getUITreeHandler = async function(args: any) { assertTarget(args); throw new Error('uie_error') }
+    ;(ToolsObserve as any).readLogStreamHandler = async function(args: any) { assertTarget(args); return { entries: [] } }
+    ;(ToolsObserve as any).getLogsHandler = async function(args: any) { assertTarget(args); return { device: { platform: 'android', id: 'mock' }, logs: ['INFO starting','ERROR crash here'], logCount: 2 } }
 
     const res2: any = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'android', includeLogs: true, logLines: 10, appId: 'com.example' })
     console.log('res2:', JSON.stringify(res2, null, 2))
@@ -62,20 +73,12 @@ async function run() {
     assert.ok(pass2, 'captureDebugSnapshot should surface partial failures and fallback logs')
     console.log('Test 2:', pass2 ? 'PASS' : 'FAIL')
 
-    // Restore handlers before next test
-    ;(ToolsObserve as any).captureScreenshotHandler = origCaptureHandler
-    ;(ToolsObserve as any).getCurrentScreenHandler = origGetCurrentHandler
-    ;(ToolsObserve as any).getScreenFingerprintHandler = origGetFpHandler
-    ;(ToolsObserve as any).getUITreeHandler = origGetTreeHandler
-    ;(ToolsObserve as any).readLogStreamHandler = origReadLogStreamHandler
-    ;(ToolsObserve as any).getLogsHandler = origGetLogsHandler
-
     // --- Test 3: includeLogs=false should omit logs ---
-    ;(ToolsObserve as any).captureScreenshotHandler = async function() { return { device: { platform: 'android', id: 'mock' }, screenshot: null } }
-    ;(ToolsObserve as any).getCurrentScreenHandler = async function() { return { device: { platform: 'android', id: 'mock' }, package: '', activity: '', shortActivity: '' } }
-    ;(ToolsObserve as any).getScreenFingerprintHandler = async function() { return { fingerprint: null } }
-    ;(ToolsObserve as any).getUITreeHandler = async function() { return { device: { platform: 'android', id: 'mock' }, screen: '', resolution: { width: 0, height: 0 }, elements: [] } }
-    ;(ToolsObserve as any).readLogStreamHandler = async function() { return { entries: [] } }
+    ;(ToolsObserve as any).captureScreenshotHandler = async function(args: any) { assertTarget(args); return { device: { platform: 'android', id: 'mock' }, screenshot: null } }
+    ;(ToolsObserve as any).getCurrentScreenHandler = async function(args: any) { assert.strictEqual(args.deviceId, device.id); return { device: { platform: 'android', id: 'mock' }, package: '', activity: '', shortActivity: '' } }
+    ;(ToolsObserve as any).getScreenFingerprintHandler = async function(args: any) { assertTarget(args); return { fingerprint: null } }
+    ;(ToolsObserve as any).getUITreeHandler = async function(args: any) { assertTarget(args); return { device: { platform: 'android', id: 'mock' }, screen: '', resolution: { width: 0, height: 0 }, elements: [] } }
+    ;(ToolsObserve as any).readLogStreamHandler = async function(args: any) { assertTarget(args); return { entries: [] } }
 
     const res3: any = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'android', includeLogs: false })
     console.log('res3:', JSON.stringify(res3, null, 2))
@@ -84,12 +87,19 @@ async function run() {
     console.log('Test 3:', pass3 ? 'PASS' : 'FAIL')
 
     let screenshotCalls = 0
-    ;(ToolsObserve as any).captureScreenshotHandler = async function() { screenshotCalls++; return { screenshot: 'unexpected' } }
+    ;(ToolsObserve as any).captureScreenshotHandler = async function(args: any) { assertTarget(args); screenshotCalls++; return { screenshot: 'unexpected' } }
     const res4: any = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'android', includeLogs: false, includeScreenshot: false })
     assert.strictEqual(screenshotCalls, 0, 'includeScreenshot=false must not invoke screenshot capture')
     assert.strictEqual(res4.raw.screenshot, null)
+    assert.strictEqual(resolutions, 4, 'Each snapshot resolves its own target once')
+
+    // Discovery failure must not collect from an arbitrary/default device.
+    _setDeviceListersForTests({ listAndroidDevices: async () => { throw new Error('fixture discovery unavailable') } })
+    await assert.rejects(() => ToolsObserve.captureDebugSnapshotHandler({ platform: 'android' }), /fixture discovery unavailable/)
+    assert.strictEqual(screenshotCalls, 0, 'No component capture should run without a resolved target')
 
   } finally {
+    _resetDeviceListersForTests()
     ;(ToolsObserve as any).captureScreenshotHandler = origCaptureHandler
     ;(ToolsObserve as any).getCurrentScreenHandler = origGetCurrentHandler
     ;(ToolsObserve as any).getScreenFingerprintHandler = origGetFpHandler

package/test/unit/observe/compact_tree_error.test.ts

@@ -0,0 +1,24 @@
+import assert from 'node:assert/strict'
+import { AndroidObserve, ToolsObserve } from '../../../src/observe/index.js'
+import { deriveSnapshotMetadata, resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
+import { withResolvedDevice } from '../../../src/utils/resolve-device.js'
+
+async function run() {
+  const original = AndroidObserve.prototype.getUITree
+  const device = { platform: 'android', id: 'fixture', model: 'Fixture', osVersion: '16', simulator: true }
+  const body = { screen: '', resolution: { width: 100, height: 200 }, elements: [] }
+  const metadata = deriveSnapshotMetadata('android:fixture', body, 'ui_tree')
+  AndroidObserve.prototype.getUITree = async () => ({ ...body, device, ...metadata, error: 'observation unavailable' })
+  try {
+    const compact: any = await withResolvedDevice(device, () => ToolsObserve.getUITreeHandler({ platform: 'android', deviceId: 'fixture', responseMode: 'compact', sinceSnapshotRevision: metadata.snapshot_revision }))
+    assert.equal(compact.error, 'observation unavailable', 'compact observations must not conceal an error behind a retained revision')
+    assert.equal(compact.delta_available, false)
+    assert.equal(compact.snapshot_session_id, metadata.snapshot_session_id)
+    assert.equal(compact.state_delta, undefined)
+    console.log('Compact UI-tree error evidence: PASS')
+  } finally {
+    AndroidObserve.prototype.getUITree = original
+    resetSnapshotMetadataForTests()
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/observe/conditional_snapshots.test.ts

@@ -0,0 +1,33 @@
+import assert from 'node:assert/strict'
+import { deriveSnapshotMetadata, hasSnapshotBaseline, resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
+
+const originalNow = Date.now
+try {
+  resetSnapshotMetadataForTests()
+  let now = originalNow()
+  Date.now = () => now
+  const body = { screen: '', resolution: { width: 100, height: 200 }, elements: Array.from({ length: 501 }, (_, index) => ({ text: `Item ${index}`, stable_id: `item-${index}`, visible: true, bounds: [0, index, 20, index + 1] })) }
+  const first = deriveSnapshotMetadata('android:fixture', body, 'ui_tree')
+  assert.equal(hasSnapshotBaseline('android:other', first.snapshot_revision), false)
+  assert.equal(hasSnapshotBaseline('android:fixture', first.snapshot_revision), true)
+  now += 9 * 60 * 1000
+  const repeat = deriveSnapshotMetadata('android:fixture', body, 'ui_tree')
+  assert.equal(repeat.snapshot_revision, first.snapshot_revision)
+  now += 2 * 60 * 1000
+  assert.equal(hasSnapshotBaseline('android:fixture', repeat.snapshot_revision), true, 'successful re-observation refreshes retention')
+  const changed = structuredClone(body)
+  changed.elements[500].text = 'Changed beyond delta history limit'
+  const second = deriveSnapshotMetadata('android:fixture', changed, 'ui_tree')
+  assert.notEqual(second.snapshot_revision, first.snapshot_revision, 'every element contributes to conditional revision')
+  assert.equal(second.snapshot_session_id, first.snapshot_session_id)
+  now += 11 * 60 * 1000
+  assert.equal(hasSnapshotBaseline('android:fixture', second.snapshot_revision), false)
+  const fresh = deriveSnapshotMetadata('android:fixture', changed, 'ui_tree')
+  assert.equal(hasSnapshotBaseline('android:fixture', fresh.snapshot_revision), true)
+  const failed = deriveSnapshotMetadata('android:empty', null, 'ui_tree')
+  assert.equal(hasSnapshotBaseline('android:empty', failed.snapshot_revision), false, 'error metadata never creates a baseline')
+  console.log('Conditional snapshot retention/session coverage: PASS')
+} finally {
+  Date.now = originalNow
+  resetSnapshotMetadataForTests()
+}

package/test/unit/observe/correlated-evidence.test.ts

@@ -0,0 +1,128 @@
+import assert from 'node:assert/strict'
+import { withEvidence, captureEvidence, evidenceDispatch, currentEvidenceActionId, markEvidenceVerification, omitEvidence, validateActionRef, type EvidenceDevice } from '../../../src/observe/evidence.js'
+
+async function run() {
+  const android = { platform: 'android' as const, id: 'evidence-unit-android' }
+  const ios = { platform: 'ios' as const, id: 'evidence-unit-ios' }
+  const originalWall = Date.now
+  const originalMono = Object.getOwnPropertyDescriptor(performance, 'now')
+  let wall = 1000000
+  let mono = 0
+  Date.now = () => wall
+  Object.defineProperty(performance, 'now', { configurable: true, value: () => mono })
+  const tick = (n = 10) => { wall += n; mono += n }
+  const observe = (device: EvidenceDevice = android) => captureEvidence('ui_tree', device, async () => {
+    tick()
+    return { device, captured_at_ms: wall, snapshot_session_id: 'tree-session', snapshot_revision: 1 }
+  })
+  const act = async (device: EvidenceDevice = android) => withEvidence({ action: true }, async () => {
+    const id = currentEvidenceActionId()
+    await evidenceDispatch(device, async () => { tick() })
+    return id
+  })
+  try {
+    const a = await withEvidence({ action: true }, async () => {
+      await observe()
+      tick()
+      const id = currentEvidenceActionId()
+      await evidenceDispatch(android, async () => { tick() })
+      await observe()
+      markEvidenceVerification()
+      return id
+    })
+    assert.equal(a.evidence.action_id, a.result)
+    assert.equal(a.evidence.correlation_id, a.result)
+    assert.deepEqual(a.evidence.observations.map(v => v.freshness), ['stale', 'fresh'])
+    assert.deepEqual(a.evidence.observations[0].freshness_reasons, ['BEFORE_ACTION'])
+    assert.ok(a.evidence.dispatch_started_at_ms! < a.evidence.dispatch_completed_at_ms!)
+    assert.ok(a.evidence.verification_completed_at_ms! >= a.evidence.dispatch_completed_at_ms!)
+    assert.deepEqual(a.evidence.trace_context, { supported: false, trace_id: null, markers: [] })
+    const ref = { sessionId: a.evidence.session_id, actionId: a.evidence.action_id! }
+    const linked = await withEvidence({ ref }, () => observe())
+    assert.equal(linked.evidence.association, 'explicit')
+    assert.equal(linked.evidence.correlation_id, a.evidence.correlation_id)
+    assert.equal(linked.evidence.verification_completed_at_ms, a.evidence.verification_completed_at_ms)
+    assert.equal(linked.evidence.observations[0].snapshot_revision, 1)
+    assert.ok(linked.evidence.observations[0].age_ms! >= 0)
+    const mismatch = await withEvidence({ ref }, () => observe(ios))
+    assert.equal(mismatch.evidence.association_reason, 'DEVICE_MISMATCH')
+    assert.equal(mismatch.evidence.action_id, null)
+    assert.notEqual(mismatch.evidence.correlation_id, a.evidence.correlation_id)
+    const foreign = await withEvidence({ ref: { ...ref, sessionId: 'previous-process' } }, () => observe())
+    assert.equal(foreign.evidence.association_reason, 'SESSION_MISMATCH')
+    assert.equal(foreign.evidence.action_id, null)
+
+    const oldSource = wall - 100
+    const reused = await withEvidence({}, () => captureEvidence('ui_tree', ios, async () => ({ device: ios, captured_at_ms: oldSource })))
+    assert.equal(reused.evidence.observations[0].source_captured_at_ms, oldSource)
+    assert.deepEqual(reused.evidence.observations[0].freshness_reasons, ['REUSED_OBSERVATION'])
+    const cachedBeforeAction = await withEvidence({ ref }, () => captureEvidence('ui_tree', android, async () => ({ captured_at_ms: a.evidence.operation_started_at_ms - 10 })))
+    assert.deepEqual(cachedBeforeAction.evidence.observations[0].freshness_reasons, ['BEFORE_ACTION'])
+
+    let release!: () => void
+    let entered!: () => void
+    const ready = new Promise<void>(resolve => { entered = resolve })
+    const gate = new Promise<void>(resolve => { release = resolve })
+    const pending = withEvidence({ action: true }, () => evidenceDispatch(android, async () => { entered(); await gate; tick() }))
+    await ready
+    const overlap = await withEvidence({}, () => observe())
+    assert.deepEqual(overlap.evidence.observations[0].freshness_reasons, ['OVERLAPPING_ACTION'])
+    const separate = await withEvidence({}, () => observe(ios))
+    assert.equal(separate.evidence.observations[0].freshness, 'fresh')
+    release(); await pending
+    const superseded = await withEvidence({}, async () => { await observe(); tick(); await act() })
+    assert.deepEqual(superseded.evidence.observations[0].freshness_reasons, ['SUPERSEDED_BY_ACTION'])
+    const [one, two] = await Promise.all([act(), act(ios)])
+    assert.notEqual(one.evidence.action_id, two.evidence.action_id)
+    assert.equal(one.evidence.device?.platform, 'android')
+    assert.equal(two.evidence.device?.platform, 'ios')
+
+    const logs = await withEvidence({}, () => captureEvidence('logs', android, async () => ({ logs: [{ timestamp: null, message: 'untimed' }, { timestamp: 42 }, { timestamp: '2020-01-01T00:00:00Z' }] })))
+    const log = logs.evidence.observations[0]
+    assert.equal(log.freshness, 'unknown')
+    assert.equal(log.earliest_entry_at_ms, 42)
+    assert.equal(log.event_time_comparable, false)
+    assert.equal(log.age_ms, null)
+    const partial = await withEvidence({}, async () => {
+      omitEvidence('logs'); omitEvidence('screenshot')
+      await captureEvidence('ui_tree', android, async () => { throw new Error('offline') }).catch(() => null)
+    })
+    assert.deepEqual(partial.evidence.observations.map(v => v.status), ['omitted', 'omitted', 'failed'])
+    assert.equal(partial.evidence.observations[0].freshness, 'not_applicable')
+    assert.equal(partial.evidence.observations[2].error, 'offline')
+    const unknown = await withEvidence({}, () => captureEvidence('screenshot', null, async () => ({})))
+    assert.equal(unknown.evidence.observations[0].freshness, 'unknown')
+    const reversal = await withEvidence({}, async () => {
+      await observe(); wall -= 1000; mono += 10
+    })
+    assert.deepEqual(reversal.evidence.observations[0].freshness_reasons, ['CLOCK_DISCONTINUITY'])
+    assert.equal(reversal.evidence.observations[0].age_ms, null)
+
+    tick(600001)
+    const expired = await withEvidence({ ref }, () => observe())
+    assert.equal(expired.evidence.association_reason, 'ACTION_UNAVAILABLE')
+    const first = await act()
+    for (let i = 0; i < 1000; i++) await act()
+    const evicted = await withEvidence({ ref: { sessionId: first.evidence.session_id, actionId: first.evidence.action_id! } }, () => observe())
+    assert.equal(evicted.evidence.association_reason, 'ACTION_UNAVAILABLE')
+    const noDispatch = await withEvidence({ action: true }, async () => undefined)
+    assert.equal(noDispatch.evidence.dispatch_started_at_ms, null)
+    assert.equal(noDispatch.evidence.verification_completed_at_ms, null)
+    const multi = await withEvidence({ action: true }, async () => {
+      await evidenceDispatch(android, async () => tick())
+      tick()
+      await evidenceDispatch(android, async () => tick())
+    })
+    assert.equal(multi.evidence.dispatch_completed_at_ms! - multi.evidence.dispatch_started_at_ms!, 30)
+    for (const invalid of [null, [], {}, { sessionId: 'a', actionId: '' }, { sessionId: 'a', actionId: 'x'.repeat(129) }, { ...ref, extra: true }]) {
+      assert.throws(() => validateActionRef(invalid), /INVALID_ARGUMENT/)
+    }
+    assert.deepEqual(validateActionRef(ref), ref)
+  } finally {
+    Date.now = originalWall
+    if (originalMono) Object.defineProperty(performance, 'now', originalMono)
+    else delete (performance as any).now
+  }
+  console.log('Correlated evidence clocks, freshness, references, isolation and bounds: PASS')
+}
+run().catch(error => { console.error(error); process.exit(1) })

package/test/unit/observe/ios_tree_acquisition.test.ts

@@ -43,6 +43,8 @@ console.log(JSON.stringify({ devices: { 'com.apple.CoreSimulator.SimRuntime.iOS-
     const first = await observe.getUITree('fake-a')
     const second = await observe.getUITree('fake-b')
     assert.equal(first.error, undefined)
+    assert.equal(typeof first.snapshot_session_id, 'string')
+    assert.equal(first.snapshot_session_id, second.snapshot_session_id)
     assert.equal(second.error, undefined)
     assert.equal(first.elements[0].text, 'Ready')
     assert.equal(second.snapshot_delta, null, 'different simulators keep independent delta history')

package/test/unit/observe/readiness.test.ts

@@ -0,0 +1,41 @@
+import assert from 'node:assert/strict'
+import { ReadinessTracker } from '../../../src/observe/readiness.js'
+import { getSnapshotSessionId } from '../../../src/observe/snapshot-metadata.js'
+
+const device = { platform: 'android', id: 'fixture' }
+const sample = (label = 'Ready', extra: any = {}) => ({ device, snapshot_session_id: getSnapshotSessionId(), snapshot_revision: 1,
+  captured_at_ms: 10000, screen: '', resolution: { width: 100, height: 200 },
+  elements: [{ type: 'Button', text: label, visible: true, enabled: true, bounds: [0, 0, 50, 50] }], ...extra })
+const tracker = new ReadinessTracker('android', 'fixture')
+assert.equal(tracker.observe(sample(), 10000, 0).state, 'unknown')
+assert.equal(tracker.observe(sample(), 10000, 499).state, 'unknown')
+assert.equal(tracker.observe(sample(), 10000, 500).state, 'settled')
+assert.equal(tracker.observe(sample('Changed'), 10000, 1000).state, 'transitioning')
+assert.equal(tracker.observe(sample('Changed'), 10000, 1500).state, 'settled')
+for (const label of [' Loading… ', 'Please wait...', 'please   wait']) {
+  const state = tracker.observe(sample(label), 10000, 2000)
+  assert.equal(state.state, 'loading')
+  assert.equal(state.basis, 'heuristic')
+  assert.equal(tracker.observe(sample(label), 10000, 3000).state, 'loading', 'identical loaders never settle')
+}
+for (const type of ['android.widget.ProgressBar', 'ActivityIndicator', 'ProgressIndicator']) {
+  const tree = sample('Progress', { elements: [{ type, visible: true }] })
+  assert.equal(tracker.observe(tree, 10000, 4000).state, 'loading')
+  assert.equal(tracker.summary.basis, 'observed')
+}
+assert.notEqual(tracker.observe(sample('Progress'), 10000, 5000).state, 'loading', 'legacy broad keywords are not loaders')
+for (const extra of [{ error: 'offline' }, { elements: [] }, { captured_at_ms: 9999 }, { snapshot_session_id: 'old' }, { device: { ...device, id: 'other' } }, { resolution: { width: Infinity, height: 2 } }]) {
+  assert.equal(tracker.observe(sample('Ready', extra), 10000, 6000).state, 'unknown')
+  assert.equal(tracker.observe(sample(), 10000, 7000).state, 'unknown', 'failure breaks continuity')
+  assert.equal(tracker.observe(sample(), 10000, 7500).state, 'settled')
+}
+for (let index = 0; index < 20; index++) tracker.observe(sample(), 10000, 8000 + index)
+assert.equal(tracker.summary.evidence.length, 8)
+assert.equal(tracker.summary.capabilities.unresponsive, false)
+assert.equal(tracker.summary.capabilities.debugger_paused, true)
+assert.ok(tracker.deadline().limitations.includes('DEADLINE_EXCEEDED'))
+assert.equal(new ReadinessTracker('android', 'fixture').observe(sample(), 10000, 9000).state, 'unknown', 'no cross-request history')
+assert.ok(!JSON.stringify(tracker.summary).includes('Ready'), 'evidence contains codes rather than private labels')
+assert.equal(new ReadinessTracker('ios', 'fixture').summary.capabilities.debugger_paused, false)
+assert.ok(tracker.summary.limitations.includes('MANAGED_DEBUGGER_ONLY'))
+console.log('Readiness classifier: PASS')