mobile-debug-mcp 0.35.0 → 0.37.0

package/test/unit/interact/ui-change-readiness-interruption.test.ts

@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict'
+import { ReadinessTracker, withReadinessTracker } from '../../../src/observe/readiness.js'
+import { withDeviceReadinessProbe } from '../../../src/observe/device-readiness.js'
+import { getSnapshotSessionId } from '../../../src/observe/snapshot-metadata.js'
+import { waitForUIChange } from '../../../src/interact/waits/ui-change-wait.js'
+import { resolveUiChangeScope } from '../../../src/interact/targeting/target-scope.js'
+import type { Clock } from '../../../src/runtime/clock.js'
+
+async function run() {
+  let now = 10000
+  const clock: Clock = { now: () => now, sleep: async ms => { now += ms } }
+  class Tracker extends ReadinessTracker {
+    override observe(tree: unknown, started: number) { return super.observe(tree, started, now) }
+  }
+  const tracker = new Tracker('android', 'fixture', 100)
+  const readTimes: number[] = []
+  const result = await withDeviceReadinessProbe(async (_command, args) => ({
+    exitCode: 0, stderr: '', stdout: args.includes('power')
+      ? `mWakefulness=${now >= 10600 && now < 11200 ? 'Asleep' : 'Awake'}\nmWakefulnessChanging=false`
+      : 'KeyguardServiceDelegate\n showing=false\n mIsShowing=false'
+  }), () => withReadinessTracker(tracker, () => waitForUIChange({ platform: 'android', deviceId: 'fixture', timeout_ms: 3000, stability_window_ms: 1200, expected_change: 'text_change' }, {
+    clock,
+    observe: async () => {
+      const text = readTimes.length ? 'After' : 'Before'
+      readTimes.push(now)
+      return { device: { platform: 'android', id: 'fixture' }, screen: '', resolution: { width: 100, height: 100 },
+        elements: [{ text, type: 'TextView', stable_id: 'label', visible: true, bounds: [0, 0, 100, 40] }],
+        captured_at_ms: now, snapshot_revision: readTimes.length, snapshot_session_id: getSnapshotSessionId() }
+    },
+    scope: (tree, scope, target) => resolveUiChangeScope(tree, scope, target, () => null)
+  })))
+  assert.equal(result.success, true)
+  assert.deepEqual(readTimes, [10000, 10300, 11200, 11500, 11800, 12100, 12400])
+  assert.equal(result.elapsed_ms, 2400, 'the full change stability window starts again after the blocker')
+  console.log('PASS readiness interruption resets UI-change stability, excluding blocked time')
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

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

@@ -1,6 +1,8 @@
 import { ToolsObserve } from '../../../src/observe/index.js'
 import assert from 'assert'
 import { _setDeviceListersForTests, _resetDeviceListersForTests } from '../../../src/utils/resolve-device.js'
+import { computeScreenFingerprint } from '../../../src/utils/ui/index.js'
+import type { DeviceInfo } from '../../../src/types.js'
 
 async function run() {
   console.log('Starting capture_debug_snapshot unit tests...')
@@ -13,7 +15,7 @@ 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 }
+  const device: DeviceInfo = { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true }
   let resolutions = 0
   _setDeviceListersForTests({
     listAndroidDevices: async () => { resolutions++; return [device] },
@@ -30,17 +32,23 @@ async function run() {
       assertTarget(args)
       return { device: { platform: 'android', id: 'mock', osVersion: '12', model: 'Pixel', simulator: true }, screenshot: 'BASE64PNG', resolution: { width: 1080, height: 1920 } }
     }
+    const current = { device, package: 'com.example', activity: 'com.example.Main', shortActivity: 'Main' }
+    const postTreeActivity = { ...current, activity: 'com.example.After' }
+    let activityCalls = 0
     ;(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' }
+      return ++activityCalls === 1 ? current : postTreeActivity
     }
-    ;(ToolsObserve as any).getScreenFingerprintHandler = async function(args: any) {
-      assertTarget(args)
-      return { fingerprint: 'abc123', activity: 'Main' }
+    let independentFingerprints = 0
+    ;(ToolsObserve as any).getScreenFingerprintHandler = async function() {
+      independentFingerprints++
+      return { fingerprint: 'independent' }
     }
+    let treeReads = 0
     ;(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: [] }
+      treeReads++
+      return { device, screen: '', resolution: { width: 1080, height: 1920 }, elements: [] }
     }
     ;(ToolsObserve as any).readLogStreamHandler = async function(args: any) {
       assertTarget(args)
@@ -53,8 +61,11 @@ async function run() {
 
     const res1: any = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'android', includeLogs: true, logLines: 50, sessionId: 's1' })
     console.log('res1:', JSON.stringify(res1, null, 2))
-    const pass1 = res1 && res1.raw && res1.raw.screenshot === 'BASE64PNG' && res1.raw.activity && res1.raw.fingerprint === 'abc123' && Array.isArray(res1.raw.logs) && res1.raw.logs.length === 1
+    const pass1 = res1 && res1.raw && res1.raw.screenshot === 'BASE64PNG' && res1.raw.activity === current.activity && Array.isArray(res1.raw.logs) && res1.raw.logs.length === 1
     assert.ok(pass1, 'captureDebugSnapshot should aggregate successful handler results')
+    assert.equal(treeReads, 1)
+    assert.equal(independentFingerprints, 0)
+    assert.equal(res1.raw.fingerprint, computeScreenFingerprint(res1.raw.ui_tree, postTreeActivity, 'android').fingerprint)
     assert.strictEqual(res1.semantic.screen, 'Main')
     assert.strictEqual(res1.semantic.confidence >= 0.7, true)
     assert.deepStrictEqual(res1.semantic.actions_available, null)
@@ -63,7 +74,7 @@ async function run() {
 
     // --- Test 2: screenshot and ui tree fail; logs fallback to getLogs ---
     ;(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).getUITreeHandler = async function(args: any) { assertTarget(args); treeReads++; throw new Error('ACTION_TIMEOUT') }
     ;(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 } }
 
@@ -71,33 +82,76 @@ async function run() {
     console.log('res2:', JSON.stringify(res2, null, 2))
     const pass2 = res2 && res2.raw && res2.raw.screenshot_error && res2.raw.ui_tree_error && Array.isArray(res2.raw.logs) && res2.raw.logs.length === 2
     assert.ok(pass2, 'captureDebugSnapshot should surface partial failures and fallback logs')
+    assert.equal(res2.raw.ui_tree_error, 'ACTION_TIMEOUT')
+    assert.equal(res2.raw.fingerprint_error, 'ACTION_TIMEOUT')
+    assert.equal(res2.raw.fingerprint, null)
+    assert.equal(treeReads, 2)
     console.log('Test 2:', pass2 ? 'PASS' : 'FAIL')
 
     // --- Test 3: includeLogs=false should omit logs ---
     ;(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).getCurrentScreenHandler = async function(args: any) { assert.strictEqual(args.deviceId, device.id); throw new Error('activity unavailable') }
+    ;(ToolsObserve as any).getUITreeHandler = async function(args: any) {
+      assertTarget(args)
+      const revision = ++treeReads
+      return { device, screen: '', snapshot_revision: revision, captured_at_ms: 1000 + revision,
+        resolution: { width: 1080, height: 1920 }, elements: [{ visible: true, text: `State ${revision}` }] }
+    }
     ;(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))
     const pass3 = res3 && res3.raw && typeof res3.raw.logs !== 'undefined' && res3.raw.logs.length === 0
     assert.ok(pass3, 'captureDebugSnapshot should return an empty logs array when includeLogs is false')
+    assert.equal(res3.raw.activity_error, 'activity unavailable')
+    assert.equal(res3.raw.fingerprint, computeScreenFingerprint(res3.raw.ui_tree, null, 'android').fingerprint)
     console.log('Test 3:', pass3 ? 'PASS' : 'FAIL')
 
     let screenshotCalls = 0
     ;(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 })
+    const res4: any = await ToolsObserve.captureDebugSnapshotHandler({ 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')
+    assert.equal(treeReads, 4)
+    assert.notEqual(res4.raw.fingerprint, res3.raw.fingerprint)
+    assert.equal(res4.raw.snapshot_revision, 4)
+    assert.equal(res4.raw.captured_at_ms, 1004)
+    assert.equal(independentFingerprints, 0)
 
     // 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')
 
+    const other: DeviceInfo = { ...device, id: 'other-fixture' }
+    _setDeviceListersForTests({ listAndroidDevices: async () => [device, other] })
+    ;(ToolsObserve as any).getUITreeHandler = async ({ deviceId }: { deviceId: string }) => ({
+      device: deviceId === device.id ? device : other, screen: '',
+      resolution: { width: 100, height: 200 }, elements: [{ visible: true, text: deviceId }]
+    })
+    ;(ToolsObserve as any).getCurrentScreenHandler = async ({ deviceId }: { deviceId: string }) => ({
+      activity: 'com.example.Main', device: deviceId === device.id ? device : other
+    })
+    const [first, second] = await Promise.all([device, other].map(target => ToolsObserve.captureDebugSnapshotHandler({
+      platform: 'android', deviceId: target.id, includeLogs: false, includeScreenshot: false
+    })))
+    assert.equal(first.raw.ui_tree?.device.id, device.id)
+    assert.equal(second.raw.ui_tree?.device.id, other.id)
+    assert.notEqual(first.raw.fingerprint, second.raw.fingerprint)
+    assert.equal(independentFingerprints, 0)
+
+    const ios: DeviceInfo = { ...device, platform: 'ios', id: 'ios-fixture' }
+    _setDeviceListersForTests({ listIOSDevices: async () => [ios] })
+    ;(ToolsObserve as any).getUITreeHandler = async ({ platform, deviceId }: { platform: string; deviceId: string }) => {
+      assert.equal(platform, 'ios')
+      assert.equal(deviceId, ios.id)
+      return { device: ios, screen: '', resolution: { width: 100, height: 200 }, elements: [] }
+    }
+    const iosResult = await ToolsObserve.captureDebugSnapshotHandler({ platform: 'ios', deviceId: ios.id, includeLogs: false, includeScreenshot: false })
+    assert.equal(iosResult.raw.fingerprint, 'independent')
+    assert.equal(independentFingerprints, 1)
+
   } finally {
     _resetDeviceListersForTests()
     ;(ToolsObserve as any).captureScreenshotHandler = origCaptureHandler

package/test/unit/observe/device-readiness-cleanup.test.ts

@@ -0,0 +1,24 @@
+import assert from 'node:assert/strict'
+import { cleanupReadinessDevice } from '../../device/automated/observe/device-readiness-cleanup.js'
+
+async function run() {
+  for (const failedStep of [0, 1, 2]) {
+    const commands: string[][] = []
+    let closed = 0
+    const commandFailure = new Error('disconnected')
+    const closeFailure = new Error('close failed')
+    const failures = await cleanupReadinessDevice(true, (...args) => {
+      commands.push(args)
+      if (commands.length - 1 === failedStep) throw commandFailure
+    }, async () => { closed++; throw closeFailure })
+    assert.equal(commands.length, 3, 'a failed restoration must not skip later steps')
+    assert.equal(commands[2].at(-1), '3', 'Home is attempted')
+    assert.equal(closed, 1, 'client close always attempted')
+    assert.deepEqual(failures, [commandFailure, closeFailure])
+  }
+  let closed = false
+  assert.deepEqual(await cleanupReadinessDevice(false, () => { assert.fail('restoration disabled') }, async () => { closed = true }), [])
+  assert.equal(closed, true)
+  console.log('PASS readiness cleanup continues after each ADB failure and closes the client')
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

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

@@ -0,0 +1,97 @@
+import { handleAdjustControl } from '../../../src/server/handlers/interact.js'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import type { AdjustControlResponse } from '../../../src/types.js'
+import { ReadinessTracker } from '../../../src/observe/readiness.js'
+import { getSnapshotSessionId } from '../../../src/observe/snapshot-metadata.js'
+import assert from 'node:assert/strict'
+import { parseAndroidPower, parseAndroidLock, observeDeviceReadiness, parseIosLock, withDeviceReadinessProbe } from '../../../src/observe/device-readiness.js'
+import { registerDebuggerPauseProvider } from '../../../src/debugger/guard.js'
+import { runWithBudget } from '../../../src/utils/operation-budget.js'
+import { compactAction, actionHandler } from '../../../src/server/handlers/action-execution.js'
+import { wrapResponse } from '../../../src/server/common.js'
+import { withResolvedDevice } from '../../../src/utils/resolve-device.js'
+
+const power = (state: string, changing = 'false') => `mWakefulness=${state}\nmWakefulnessChanging=${changing}`
+const lock = (state: string) => `KeyguardServiceDelegate\n showing=${state}\n KeyguardStateMonitor\n mIsShowing=${state}`
+for (const [text, expected] of [[power('Awake'), 'awake'], [power('Asleep'), 'asleep'], [power('Dozing'), 'asleep'], [power('Awake', 'true'), 'transitioning'], [power('Dreaming'), 'unknown'], ['mWakefulness=Awake', 'unknown'], [power('Awake') + '\nmWakefulness=Asleep', 'unknown']]) assert.equal(parseAndroidPower(text), expected)
+assert.equal(parseAndroidPower('Power Manager State:\n' + power('Dozing') + '\nSettings and Configuration:\nmWakefulness=3'), 'asleep', 'vendor debug fields outside current-state section cannot conflict with it')
+assert.equal(parseAndroidLock(lock('true')), 'locked')
+assert.equal(parseAndroidLock(lock('false')), 'unlocked')
+for (const text of ['', 'deviceHasKeyguard=true', 'showing=false', lock('true').replace('mIsShowing=true', 'mIsShowing=false')]) assert.equal(parseAndroidLock(text), 'unknown')
+const unsupported = JSON.stringify({ error: { domain: 'com.apple.dt.CoreDeviceError', code: 1001, userInfo: { CapabilityFeatureIdentifier: { string: 'com.apple.coredevice.feature.getlockstate' } } } })
+assert.equal(parseIosLock(unsupported), 'unsupported')
+assert.equal(parseIosLock(unsupported.replace('getlockstate', 'other')), 'unknown')
+assert.equal(parseIosLock('{"result":{"passcodeRequired":false}}'), 'unknown', 'unverified success semantics cannot establish unlocked')
+const device = { platform: 'android', id: 'fixture', model: 'Fixture', osVersion: '16', simulator: true }
+async function run() {
+  const calls: string[][] = []
+  const probe = async (_command: string, args: string[], timeout: number) => {
+    calls.push(args)
+    assert.ok(timeout > 0 && timeout <= 1000)
+    return { exitCode: 0, stdout: args.includes('power') ? power('Asleep') : lock('true'), stderr: '' }
+  }
+  const started = Date.now()
+  const state = await runWithBudget(500, () => observeDeviceReadiness(device, probe))
+  assert.deepEqual(state.blockers, ['DEVICE_ASLEEP', 'DEVICE_LOCKED'])
+  assert.equal(state.input_ready, false)
+  assert.ok(state.evidence.every(item => item.captured_at_ms >= started))
+  assert.ok(calls.every(args => args[0] === '-s' && args[1] === device.id))
+  assert.ok(!JSON.stringify(state).includes('mWakefulness'))
+  const partial = await observeDeviceReadiness(device, async (...args) => {
+    if (args[1].includes('power')) throw new Error('private diagnostic')
+    return probe(...args)
+  })
+  assert.equal(partial.wakefulness, 'unknown')
+  assert.equal(partial.lock_state, 'locked')
+  assert.ok(!JSON.stringify(partial).includes('private diagnostic'))
+  const recovered = await observeDeviceReadiness(device, async (_cmd, args) => ({ exitCode: 0, stdout: args.includes('power') ? power('Awake') : lock('false'), stderr: '' }))
+  assert.equal(recovered.input_ready, null)
+  assert.deepEqual(recovered.blockers, [])
+  const tracker = new ReadinessTracker(device.platform, device.id, 100)
+  const tree = { device, captured_at_ms: Date.now(), snapshot_revision: 1, snapshot_session_id: getSnapshotSessionId(), resolution: { width: 100, height: 100 }, elements: [{ type: 'Button', visible: true, text: 'Ready' }] }
+  tracker.observe(tree, tree.captured_at_ms, 0)
+  assert.equal(tracker.observe(tree, tree.captured_at_ms, 100).state, 'settled')
+  await withDeviceReadinessProbe(probe, () => tracker.observeDevice())
+  assert.equal(tracker.ready, false)
+  await withDeviceReadinessProbe(async (_cmd, args) => ({ exitCode: 0, stdout: args.includes('power') ? power('Awake') : lock('false'), stderr: '' }), () => tracker.observeDevice())
+  assert.equal(tracker.observe(tree, tree.captured_at_ms, 500).state, 'unknown', 'blocker breaks UI stability continuity')
+  assert.equal(tracker.observe(tree, tree.captured_at_ms, 600).state, 'settled')
+  const before = calls.length
+  const expired = await runWithBudget(0, () => observeDeviceReadiness(device, probe))
+  assert.equal(calls.length, before, 'no probe starts after expiry')
+  assert.equal(expired.wakefulness, 'unknown')
+  assert.equal((await observeDeviceReadiness(null, probe)).limitations[0], 'DEVICE_TARGET_UNAVAILABLE')
+  const ios = await observeDeviceReadiness({ platform: 'ios', id: 'ios-fixture' }, async (_cmd, args, timeout) => { assert.equal(args[args.indexOf('--timeout') + 1], '5'); assert.ok(timeout <= 1000); return { exitCode: 1, stdout: unsupported, stderr: '' } })
+  assert.equal(ios.lock_state, 'unsupported')
+  assert.equal(ios.wakefulness, 'unknown')
+  registerDebuggerPauseProvider(() => ({ debug_session_id: 'paused', captured_at_ms: started, target: {} }))
+  try {
+    const paused = await observeDeviceReadiness(device, probe)
+    assert.deepEqual(paused.blockers, ['DEBUGGER_PAUSED'])
+    assert.equal(calls.length, before)
+  } finally { registerDebuggerPauseProvider(() => null) }
+  assert.deepEqual(compactAction({ success: true, device_readiness: state }, 'none').device_readiness, state)
+  for (const responseMode of ['debug', 'compact']) {
+    const response = await withDeviceReadinessProbe(probe, () => withResolvedDevice(device, () => actionHandler('start_app', async () => wrapResponse({ success: true, device }))( { platform: 'android', deviceId: device.id, responseMode, verificationMode: 'none', actionTimeoutMs: 500 })))
+    const result = JSON.parse(response.content[0].text!)
+    assert.equal(result.success, true, 'blocker observation preserves dispatch outcome')
+    assert.equal(result.verification.status, 'not_requested')
+    assert.deepEqual(result.device_readiness.blockers, ['DEVICE_ASLEEP', 'DEVICE_LOCKED'])
+  }
+  const failedProbe = await withDeviceReadinessProbe(async () => { throw new Error('private'); }, () => withResolvedDevice(device, () => actionHandler('tap', async () => wrapResponse({ success: true, device }))({ responseMode: 'compact', verificationMode: 'none', actionTimeoutMs: 200 })))
+  const unknown = JSON.parse(failedProbe.content[0].text!)
+  assert.equal(unknown.success, true)
+  assert.equal(unknown.device_readiness.wakefulness, 'unknown')
+  assert.equal(unknown.device_readiness.lock_state, 'unknown')
+  assert.ok(!JSON.stringify(unknown.device_readiness).includes('private'))
+  const adjust = ToolsInteract.adjustControlHandler
+  ToolsInteract.adjustControlHandler = async () => ({ success: true, device } as AdjustControlResponse)
+  try {
+    const response = await withDeviceReadinessProbe(probe, () => handleAdjustControl({ selector: { text: 'Volume' }, targetValue: 50 }))
+    const result = JSON.parse(response.content[0].text!)
+    assert.equal(result.success, true)
+    assert.equal(result.device_readiness.input_ready, false, 'adjust_control carries the same blocker contract')
+  } finally { ToolsInteract.adjustControlHandler = adjust }
+  console.log('Device readiness: parsing, probes, budgets, recovery, debugger and action contracts PASS')
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

package/test/unit/observe/ios-trace-native.test.ts

@@ -0,0 +1,90 @@
+import assert from 'node:assert/strict'
+import { promises as fs } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { iosCapabilities, resolveIosApp } from '../../../src/observe/ios-trace/capabilities.js'
+import { validateArtifact, validateToc, traceSize, IOS_TRACE_MAX_BYTES } from '../../../src/observe/ios-trace/artifact.js'
+import { IosTraceNative } from '../../../src/observe/ios-trace/native.js'
+import { spawnTrace, stopTraceChild, classifyTraceFailure, type TraceSpawn, type TraceCommandResult } from '../../../src/observe/ios-trace/process.js'
+const app={app_id:'fixture',pid:123,executable:'/Fixture.app/Fixture',started_at:'Wed Nov 4 10:00:00 2026'}
+const toc=(id='sim',pid=123,template='Time Profiler')=>`<trace-toc><run><info><target><device uuid="${id}"/><process pid="${pid}"/></target><summary><template-name>${template}</template-name></summary></info><processes><process pid="${pid}" path="/Fixture.app/Fixture"/></processes><data><table schema="time-sample"/></data></run></trace-toc>`
+function fake(){
+  const calls:{command:string;args:string[];signals:NodeJS.Signals[]}[]=[],lines:string[]=[]
+  let mismatch=false,failExport=false,failReady=false
+  const spawn:TraceSpawn=(command,args)=>{
+    const call={command,args,signals:[] as NodeJS.Signals[]};calls.push(call)
+    const recording=args.includes('record'),listener=command.endsWith('/notification'),pending=recording||listener
+    let alive=pending,resolve!:(r:TraceCommandResult)=>void
+    const done=new Promise<TraceCommandResult>(r=>{resolve=r})
+    const execute=async()=>{
+      let output=''
+      if(args.includes('get_app_container'))output='/Fixture.app'
+      else if(args.includes('launchctl'))output='123 0 UIKitApplication:fixture[abc]'
+      else if(command==='/bin/ps')output=args.includes('lstart=')?app.started_at:mismatch?'/Other.app/Other':app.executable
+      else if(args.includes('clang'))await fs.writeFile(args[args.indexOf('-o')+1],'binary')
+      else if(args.includes('xcodebuild'))output='Xcode 27.2'
+      else if(args.includes('templates'))output='== Standard Templates ==\nTime Profiler\nSystem Trace\nAnimation Hitches'
+      else if(args.includes('xctrace')&&args.includes('devices'))output='fixture (sim)'
+      else if(args.includes('devices'))output=JSON.stringify({devices:{'iOS-26-4':[{udid:'sim',state:'Booted',name:'fixture',isAvailable:true}]}})
+      else if(args.includes('export')){
+        if(failExport){resolve({code:2,output:'private stderr',timedOut:false});return}
+        const file=args[args.indexOf('--output')+1]
+        await fs.writeFile(file,args.includes('--toc')?toc():'<trace-query-result><node><schema name="time-sample"/><row><sample-time>1</sample-time></row></node></trace-query-result>')
+      }
+      if(!pending)resolve({code:0,output,timedOut:false})
+    }
+    void execute()
+    return {done,alive:()=>alive,signal:s=>{call.signals.push(s);alive=false;resolve({code:0,output:'Stopped',timedOut:false})},line:async(line)=>{lines.push(line);if(failReady&&line==='READY')throw new Error('READINESS_TIMEOUT')}}
+  }
+  return {spawn,calls,lines,flags:(v:{mismatch?:boolean;export?:boolean;ready?:boolean})=>{mismatch=v.mismatch??false;failExport=v.export??false;failReady=v.ready??false}}
+}
+async function run(){
+  const f=fake(),directory=await fs.mkdtemp(path.join(os.tmpdir(),'ios-trace-unit-'))
+  try{
+    assert.deepEqual(await resolveIosApp('sim','fixture',f.spawn),app)
+    f.flags({mismatch:true});await assert.rejects(()=>resolveIosApp('sim','fixture',f.spawn),/APP_IDENTITY_UNAVAILABLE/);f.flags({})
+    const cap=await iosCapabilities('sim','fixture','Time Profiler',f.spawn,'darwin')
+    assert.equal(cap.supported,true);assert.equal(cap.prerequisites.permissions,'unknown');assert.equal(cap.templates.filter(t=>t.supported).length,1)
+    assert.equal((await iosCapabilities('sim',undefined,'System Trace',f.spawn,'darwin')).supported,false)
+    assert.equal((await iosCapabilities('physical',undefined,'Time Profiler',f.spawn,'darwin')).supported,false)
+    assert.equal((await iosCapabilities('sim',undefined,'Time Profiler',f.spawn,'linux')).reasons[0],'MACOS_REQUIRED')
+    assert.ok(!f.calls.some(c=>c.args.includes('record')),'Discovery must not record')
+    validateToc(toc(),'sim',app)
+    assert.throws(()=>validateToc(toc(),'sim',{...app,executable:'/Other.app/Other'}),/ARTIFACT_APP_MISMATCH/)
+    assert.equal(classifyTraceFailure({code:1,output:'secret path: permission denied',timedOut:false}),'PROFILING_PERMISSION_REQUIRED')
+    assert.equal(classifyTraceFailure({code:1,output:'Cannot find process for provided pid: 123',timedOut:false}),'APP_NOT_RUNNING')
+    for(const xml of [toc('other'),toc('sim',456),toc('sim',123,'System Trace'),'<invalid>'])assert.throws(()=>validateToc(xml,'sim',app))
+    const file=path.join(directory,'capture.trace');await fs.mkdir(file);await fs.writeFile(path.join(file,'data'),'samples')
+    const artifact=await validateArtifact(file,'sim',app,f.spawn)
+    assert.equal(artifact.validation.sample_rows,1);assert.equal(artifact.kind,'directory');assert.equal((await fs.stat(path.join(file,'data'))).mode&0o777,0o600)
+    await assert.rejects(()=>fs.stat(path.join(directory,'samples.xml')),{code:'ENOENT'})
+    f.flags({export:true});await assert.rejects(()=>validateArtifact(file,'sim',app,f.spawn));f.flags({})
+    const outside=path.join(directory,'link');await fs.symlink(file,outside);await assert.rejects(()=>traceSize(outside),/UNSAFE_ARTIFACT/)
+    const huge=path.join(directory,'huge');await fs.writeFile(huge,'');await fs.truncate(huge,IOS_TRACE_MAX_BYTES+1)
+    assert.ok(await traceSize(huge)>IOS_TRACE_MAX_BYTES)
+    const native=new IosTraceNative(f.spawn)
+    const recording=await native.start('sim',app,directory,30000,()=>{})
+    assert.deepEqual(f.lines,['ARMED','READY'])
+    const recorder=f.calls.find(c=>c.args.includes('record'))!,listener=f.calls.find(c=>c.command.endsWith('/notification'))!
+    assert.equal(recorder.args[recorder.args.indexOf('--device')+1],'sim')
+    assert.equal(recorder.args[recorder.args.indexOf('--attach')+1],'123')
+    assert.equal(recorder.args[recorder.args.indexOf('--notify-tracing-started')+1],listener.args[0])
+    assert.ok(!recorder.args.includes('--no-prompt'));await native.stop(recording);assert.deepEqual(recorder.signals,['SIGINT'])
+    const failed=fake();failed.flags({ready:true});const other=new IosTraceNative(failed.spawn)
+    await assert.rejects(()=>other.start('sim',app,directory,30000,()=>{}),/READINESS_TIMEOUT/)
+    assert.ok(failed.calls.find(c=>c.args.includes('record'))?.signals.includes('SIGINT'))
+    native.shutdown();other.shutdown()
+    const child=spawnTrace(process.execPath,['-e','process.stdout.write("READY\\n");setInterval(()=>{},1000)'],2000)
+    await child.line('READY',1000);await stopTraceChild(child,1000);assert.equal(child.alive(),false)
+    const signals:NodeJS.Signals[]=[]
+    const stuck={done:new Promise<TraceCommandResult>(()=>{}),alive:()=>true,line:async()=>{},signal:(s:NodeJS.Signals)=>{signals.push(s)}}
+    await assert.rejects(()=>stopTraceChild(stuck,1),/ACTION_TIMEOUT/)
+    assert.deepEqual(signals,['SIGINT','SIGKILL'])
+    const noisy=await spawnTrace(process.execPath,['-e','process.stdout.write("x".repeat(100000))'],2000).done
+    assert.equal(noisy.output.length,65536)
+    const timeout=await spawnTrace(process.execPath,['-e','setInterval(()=>{},1000)'],30).done
+    assert.equal(timeout.timedOut,true)
+    console.log('PASS iOS native discovery, notification, ownership, artifact schemas and bounded children')
+  }finally{await fs.rm(directory,{recursive:true,force:true})}
+}
+run().catch(error=>{console.error(error);process.exitCode=1})

package/test/unit/observe/ios-trace-sessions.test.ts

@@ -0,0 +1,154 @@
+import assert from 'node:assert/strict'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { IosTraceSessions } from '../../../src/observe/ios-trace/sessions.js'
+import { IosTraceNative, type IosRecording } from '../../../src/observe/ios-trace/native.js'
+import type { TraceClock } from '../../../src/observe/system-trace.js'
+import type { TraceCommandResult } from '../../../src/observe/ios-trace/process.js'
+
+const target = { platform: 'ios' as const, id: 'sim', simulator: true, osVersion: '26.4', model: 'fixture' }
+function fixture() {
+  let monitorTick = 0, exitOnMonitor = false, exportMessage = 'EXPORT_FAILED'
+  let now = 1000, failStart = false, failStop = false, failExport = false, monitor = '', stops = 0, starts = 0, validations = 0
+  const timers = new Map<ReturnType<typeof setTimeout>, () => void>(), recordings: IosRecording[] = [], directories: string[] = []
+  const time: TraceClock = { wall: () => now, mono: () => now, sleep: async ms => {now += ms},
+    schedule: fn => { const id = {} as ReturnType<typeof setTimeout>; timers.set(id,fn); return id }, clear: id => {timers.delete(id)} }
+  class Native extends IosTraceNative {
+    resolve = async () => ({ app_id:'fixture', pid:100, executable:'/fixture.app/Fixture',started_at:'fixture-start' })
+    async start(_d: string, _app: unknown, directory: string, _duration: number, own: (r: IosRecording) => void) {
+      starts++; directories.push(directory)
+      let alive = true, resolve!: (v: TraceCommandResult) => void
+      const done = new Promise<TraceCommandResult>(r => {resolve=r})
+      const recording: IosRecording = {file:path.join(directory,'capture.trace'), ready_at_ms:now,
+        recorder:{done, alive:()=>alive, line:async()=>{},signal:()=>{alive=false;resolve({code:0,output:'Reached specified time limit',timedOut:false})}}}
+      own(recording); recordings.push(recording)
+      await fs.mkdir(recording.file)
+      await fs.writeFile(path.join(recording.file,'data'),'sample')
+      if(failStart) throw new Error('READINESS_TIMEOUT')
+      return recording
+    }
+    async stop(r: IosRecording) {stops++; if(failStop) throw new Error('ACTION_TIMEOUT');r.recorder.signal('SIGINT');return r.recorder.done}
+    async monitor(device: string, app: {pid:number;executable:string}, recording: IosRecording) {
+      assert.equal(device,target.id);assert.equal(app.pid,100);assert.equal(app.executable,'/fixture.app/Fixture')
+      assert.equal(recording,recordings.at(-1),'Retries must retain the same owned recording')
+      now+=monitorTick
+      if(exitOnMonitor)recording.recorder.signal('SIGINT')
+      if(monitor)throw new Error(monitor)
+    }
+    async validate(r: IosRecording) {validations++;if(failExport)throw new Error(exportMessage);return {path:r.file,format:'instruments' as const,kind:'directory' as const,size_bytes:6,validation:{readable:true,schema:'time-sample',sample_rows:1}}}
+    shutdown() {for(const r of recordings)r.recorder.signal('SIGINT')}
+  }
+  const sessions = new IosTraceSessions(new Native(),time)
+  return {sessions,recordings,timers,flags:(v:{start?:boolean;stop?:boolean;export?:boolean;monitor?:string;monitorTick?:number;exitOnMonitor?:boolean;exportMessage?:string})=>{failStart=v.start??false;failStop=v.stop??false;failExport=v.export??false;monitor=v.monitor??'';monitorTick=v.monitorTick??0;exitOnMonitor=v.exitOnMonitor??false;exportMessage=v.exportMessage??'EXPORT_FAILED'},
+    tick:(ms:number)=>{now+=ms},counts:()=>({stops,starts,validations}),
+    cleanup:async()=>{await sessions.shutdown();for(const d of directories)await fs.rm(d,{recursive:true,force:true})}}
+}
+async function run() {
+  const f=fixture()
+  try {
+    const start=await f.sessions.start(target,'fixture')
+    await assert.rejects(()=>f.sessions.start(target,'fixture'),/TRACE_BUSY/)
+    assert.equal(start.state,'recording');assert.equal(start.recording_ready_at_ms,1000)
+    const finish=await f.sessions.link(start.trace_id,target,'journey')
+    for(const device of [{platform:'android',id:'sim'},{platform:'ios',id:'other'}])await assert.rejects(()=>f.sessions.link(start.trace_id,device,'wrong'),/TRACE_NOT_FOUND/)
+    const [a,b]=await Promise.all([f.sessions.control(start.trace_id,'stop'),f.sessions.control(start.trace_id,'stop')])
+    assert.equal(a.state,'completed');assert.deepEqual(a,b);assert.deepEqual(a.correlation_ids,['journey']);assert.equal((await finish()).coverage,'partial')
+    assert.equal(f.counts().validations,1)
+    await assert.rejects(()=>f.sessions.link(start.trace_id,target,'stale'),/TRACE_NOT_FOUND/)
+    await assert.rejects(()=>f.sessions.control('foreign','stop'),/TRACE_NOT_FOUND/)
+    assert.equal((await f.sessions.control(start.trace_id,'cancel')).artifact?.path,a.artifact?.path)
+    const cancelled=await f.sessions.start(target,'fixture')
+    const dir=path.dirname(f.recordings[1].file)
+    assert.equal((await f.sessions.control(cancelled.trace_id,'cancel')).state,'cancelled')
+    await assert.rejects(()=>fs.stat(dir),{code:'ENOENT'})
+    const expires=await f.sessions.start(target,'fixture',1000);f.tick(1001)
+    const expired=await f.sessions.control(expires.trace_id,'status')
+    assert.equal(expired.state,'completed');assert.equal(expired.completion_reason,'duration_limit')
+    f.tick(600001);await assert.rejects(()=>f.sessions.control(start.trace_id,'status'),/TRACE_NOT_FOUND/)
+  }finally{await f.cleanup()}
+  for(const failure of ['start','stop','export','monitor'] as const){
+    const f=fixture()
+    try{
+      if(failure==='start')f.flags({start:true})
+      const s=await f.sessions.start(target,'fixture')
+      if(failure==='start'){assert.equal(s.state,'failed');assert.equal(s.reason,'READINESS_TIMEOUT');assert.equal(s.cleanup.status,'complete');assert.equal(f.recordings[0].recorder.alive(),false);continue}
+      f.flags(failure==='monitor'?{monitor:'STORAGE_LIMIT'}:{[failure]:true})
+      const failed=await f.sessions.control(s.trace_id,failure==='monitor'?'status':'stop')
+      assert.equal(failed.state,'failed');assert.equal(failed.artifact,null)
+      if(failure==='monitor'){assert.equal(failed.reason,'STORAGE_LIMIT');assert.equal(failed.cleanup.status,'complete');continue}
+      f.flags({})
+      assert.equal((await f.sessions.control(s.trace_id,'stop')).state,'completed')
+      assert.equal(f.counts().starts,1,'Retry must not start a new recording')
+    }finally{await f.cleanup()}
+  }
+  const exportClassification=fixture()
+  try {
+    const s=await exportClassification.sessions.start(target,'fixture')
+    exportClassification.flags({export:true,exportMessage:'COMMAND_FAILED'})
+    const failed=await exportClassification.sessions.control(s.trace_id,'stop')
+    assert.equal(failed.reason,'TRACE_ARTIFACT_FAILED','Monitor classification must not alter export errors')
+    assert.match(failed.recovery!,/Retry stop/)
+  }finally{await exportClassification.cleanup()}
+  for(const reason of ['COMMAND_FAILED','ACTION_TIMEOUT','TARGET_DISCONNECTED','private unexpected output']) {
+    const f=fixture()
+    try {
+      const s=await f.sessions.start(target,'fixture')
+      f.flags({monitor:reason})
+      for(let n=0;n<2;n++)assert.equal((await f.sessions.control(s.trace_id,'status')).state,'recording')
+      assert.equal(f.counts().stops,0)
+      f.flags({});assert.equal((await f.sessions.control(s.trace_id,'status')).state,'recording')
+      f.flags({monitor:reason})
+      for(let n=0;n<2;n++)assert.equal((await f.sessions.control(s.trace_id,'status')).state,'recording','Successful poll must reset consecutive failure count')
+      const failed=await f.sessions.control(s.trace_id,'status')
+      assert.equal(failed.state,'failed');assert.equal(failed.reason,reason==='private unexpected output'?'TRACE_MONITOR_FAILED':reason)
+      assert.equal(failed.cleanup.status,'complete');assert.equal(failed.artifact,null)
+      assert.equal(f.counts().starts,1);assert.equal(f.recordings[0].recorder.alive(),false)
+      assert.ok(!JSON.stringify(failed).includes('private unexpected output'))
+    }finally{await f.cleanup()}
+  }
+  for(const reason of ['APP_IDENTITY_CHANGED','APP_NOT_RUNNING']) {
+    const f=fixture()
+    try {
+      const s=await f.sessions.start(target,'fixture');f.flags({monitor:reason})
+      const failed=await f.sessions.control(s.trace_id,'status')
+      assert.equal(failed.state,'failed');assert.equal(failed.reason,reason);assert.equal(failed.cleanup.status,'complete')
+    }finally{await f.cleanup()}
+  }
+  for(const ended of ['deadline','recorder'] as const) {
+    const f=fixture()
+    try {
+      const s=await f.sessions.start(target,'fixture',1000)
+      f.flags({monitor:'COMMAND_FAILED',monitorTick:ended==='deadline'?1001:0,exitOnMonitor:ended==='recorder'})
+      const result=await f.sessions.control(s.trace_id,'status')
+      assert.equal(result.state,'completed','A tolerated failed poll must still reconcile duration/recorder completion')
+      assert.equal(result.completion_reason,'duration_limit');assert.ok(result.artifact)
+    }finally{await f.cleanup()}
+  }
+  const cancelledStopFailure=fixture()
+  try {
+    const started=await cancelledStopFailure.sessions.start(target,'fixture')
+    const directory=path.dirname(cancelledStopFailure.recordings[0].file)
+    cancelledStopFailure.flags({stop:true})
+    const failed=await cancelledStopFailure.sessions.control(started.trace_id,'cancel')
+    assert.equal(failed.cleanup.status,'failed')
+    await fs.stat(directory) // Never remove a directory while the recorder may still write.
+    cancelledStopFailure.flags({})
+    assert.equal((await cancelledStopFailure.sessions.control(started.trace_id,'cancel')).cleanup.status,'complete')
+  } finally {await cancelledStopFailure.cleanup()}
+  const exitedStopFailure=fixture()
+  try {
+    const started=await exitedStopFailure.sessions.start(target,'fixture')
+    const directory=path.dirname(exitedStopFailure.recordings[0].file)
+    exitedStopFailure.flags({stop:true})
+    assert.deepEqual(await exitedStopFailure.sessions.shutdown(),[], 'a stop failure after confirmed recorder exit must not strand discarded files')
+    const result=await exitedStopFailure.sessions.control(started.trace_id,'status')
+    assert.equal(result.state,'failed', 'cleanup must not hide the recorder failure')
+    assert.equal(result.reason,'ACTION_TIMEOUT')
+    assert.equal(result.cleanup.status,'complete')
+    await assert.rejects(()=>fs.stat(directory),{code:'ENOENT'})
+  } finally {await exitedStopFailure.cleanup()}
+  const shutdown=fixture()
+  try{const s=await shutdown.sessions.start(target,'fixture');assert.deepEqual(await shutdown.sessions.shutdown(),[]);assert.equal((await shutdown.sessions.control(s.trace_id,'status')).state,'cancelled');await assert.rejects(()=>shutdown.sessions.start(target,'fixture'),/TRACE_BUSY/)}finally{await shutdown.cleanup()}
+  console.log('PASS iOS trace lifecycle, linkage, failure cleanup, retries and expiry')
+}
+run().catch(error=>{console.error(error);process.exitCode=1})

package/test/unit/observe/readiness-retained-blockers.test.ts

@@ -0,0 +1,40 @@
+import assert from 'node:assert/strict'
+import { ReadinessTracker } from '../../../src/observe/readiness.js'
+import { withDeviceReadinessProbe } from '../../../src/observe/device-readiness.js'
+import { runWithBudget } from '../../../src/utils/operation-budget.js'
+
+async function run() {
+  let power = 'Asleep', lock = 'true', fail = false
+  const tracker = new ReadinessTracker('android', 'fixture')
+  const observe = () => withDeviceReadinessProbe(async (_command, args) => {
+    if (fail) throw new Error('native failure')
+    return { exitCode: 0, stderr: '', stdout: args.includes('power')
+      ? (power ? `mWakefulness=${power}\nmWakefulnessChanging=false` : '')
+      : (lock ? `KeyguardServiceDelegate\n showing=${lock}\n mIsShowing=${lock}` : '') }
+  }, () => tracker.observeDevice())
+  await observe()
+  const blockedEvidence = structuredClone(tracker.deviceReadiness.evidence)
+  fail = true
+  await observe()
+  assert.deepEqual(tracker.deviceReadiness.blockers, ['DEVICE_ASLEEP', 'DEVICE_LOCKED'])
+  assert.deepEqual(tracker.deviceReadiness.evidence, blockedEvidence, 'retained evidence keeps its original timestamps')
+  assert.ok(tracker.deviceReadiness.limitations.includes('DEVICE_POWER_OBSERVATION_FAILED'))
+  assert.ok(tracker.deviceReadiness.limitations.includes('DEVICE_LOCK_OBSERVATION_FAILED'))
+  assert.ok(tracker.deviceReadiness.limitations.includes('DEVICE_BLOCKER_EVIDENCE_RETAINED'))
+  await runWithBudget(0, observe)
+  tracker.deadline()
+  assert.deepEqual(tracker.deviceReadiness.blockers, ['DEVICE_ASLEEP', 'DEVICE_LOCKED'])
+  assert.deepEqual(tracker.deviceReadiness.evidence, blockedEvidence)
+  fail = false; power = 'Awake'; lock = ''
+  await observe()
+  assert.deepEqual(tracker.deviceReadiness.blockers, ['DEVICE_LOCKED'], 'fresh awake evidence clears only the power blocker')
+  assert.equal(tracker.deviceReadiness.input_ready, false)
+  power = ''; lock = 'false'
+  await observe()
+  assert.deepEqual(tracker.deviceReadiness.blockers, [], 'fresh unlocked evidence clears the remaining lock blocker')
+  assert.equal(tracker.deviceReadiness.wakefulness, 'unknown', 'do not retain previously clear observations')
+  assert.equal(tracker.deviceReadiness.input_ready, null)
+  assert.ok(!tracker.deviceReadiness.limitations.includes('DEVICE_BLOCKER_EVIDENCE_RETAINED'))
+  console.log('PASS inconclusive/expired probes retain blockers per axis; only fresh clear signals remove them')
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

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

@@ -36,6 +36,6 @@ 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.equal(new ReadinessTracker('ios', 'fixture').summary.capabilities.debugger_paused, true)
 assert.ok(tracker.summary.limitations.includes('MANAGED_DEBUGGER_ONLY'))
 console.log('Readiness classifier: PASS')