mobile-debug-mcp 0.34.0 → 0.36.0

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

@@ -2,7 +2,7 @@ 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'
+import { debuggerContracts, debuggerTools } from '../../../src/server/schemas/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')

package/test/unit/interact/adjustment_service.test.ts

@@ -0,0 +1,42 @@
+import assert from 'node:assert/strict'
+import { adjustControl } from '../../../src/interact/adjustment/adjustment.js'
+import type { AdjustmentDependencies } from '../../../src/interact/adjustment/adjustment-context.js'
+import type { ActionTargetResolved, DeviceInfo } from '../../../src/types.js'
+import type { UiElement } from '../../../src/interact/model.js'
+
+const device: DeviceInfo = { platform: 'android', id: 'fixture', model: 'fixture', osVersion: 'fixture', simulator: true }
+let value = 10
+const calls: string[] = []
+const element = (): UiElement => ({ visible: true, enabled: true, role: 'slider', stable_id: 'duration', bounds: [0, 0, 300, 40],
+  state: { value, value_range: { min: 0, max: 100 } }, actions: ['set_value'] })
+const handle = { elementId: 'handle', platform: 'android' as const, deviceId: device.id, bounds: [0, 0, 300, 40] as [number, number, number, number], index: 0, stable_id: 'duration' }
+const target = (): ActionTargetResolved => ({ elementId: 'handle', text: null, resource_id: null, accessibility_id: null, class: 'Slider', bounds: handle.bounds, index: 0 })
+const deps: AdjustmentDependencies = {
+  observe: async () => ({ device, elements: [element()] }), fingerprint: async () => 'fingerprint',
+  getHandle: () => handle, currentHandle: () => ({ el: element(), index: 0 }), target,
+  wait: async () => { throw new Error('handle targeting must not use selector waits') },
+  find: async () => { throw new Error('handle targeting must not use semantic search') },
+  expectState: async input => {
+    calls.push('verify')
+    return { success: true, element_id: 'handle', expected_state: { property: input.property, expected: input.expected },
+      observed_state: { property: input.property, value }, trace: { action_id: 'assertion', steps: [], final_outcome: 'success', attempts: 1 } }
+  },
+  service: async () => ({ resolved: { id: device.id }, interact: { setAdjustableValue: async () => { calls.push('semantic'); return { success: false } } } }),
+  tap: async () => { calls.push('coordinate'); value = 20; return { success: true, device } },
+  swipe: async () => { throw new Error('a converged coordinate adjustment must not dispatch a gesture') }
+}
+const already = await adjustControl({ element_id: 'handle', targetValue: 10 }, deps)
+assert.equal(already.success, true)
+assert.equal(already.attempts, 0)
+assert.deepEqual(calls, [])
+const adjusted = await adjustControl({ element_id: 'handle', targetValue: 20 }, deps)
+assert.equal(adjusted.success, true)
+assert.equal(adjusted.attempts, 2)
+assert.equal(adjusted.adjustment_mode, 'coordinate')
+assert.deepEqual(calls, ['semantic', 'coordinate', 'verify'], 'failed direct capability falls back in the established order')
+calls.length = 0
+const stale = await adjustControl({ element_id: 'missing', targetValue: 20 }, { ...deps, getHandle: () => undefined })
+assert.equal(stale.success, false)
+assert.equal(stale.failure_code, 'STALE_REFERENCE')
+assert.deepEqual(calls, [], 'missing handles cannot dispatch native input')
+console.log('PASS injected adjustment service: read-only convergence, strategy order, attempt accounting and stale-handle rejection')

package/test/unit/interact/adjustment_verification.test.ts

@@ -0,0 +1,35 @@
+import assert from 'node:assert/strict'
+import type { ExpectStateResponse } from '../../../src/types.js'
+import { verifyAdjustment, type AdjustmentVerificationInput } from '../../../src/interact/adjustment/adjustment-verification.js'
+
+const input: AdjustmentVerificationInput = {
+  labeled: false, currentEl: { state: { value: 10 } },
+  actualState: { property: 'value', value: 10 }, property: 'value', target: 20, tolerance: 0.5,
+  expectation: { element_id: 'control', property: 'value', expected: 20, platform: 'android', deviceId: 'fixture' }
+}
+let observations = 0
+let assertions = 0
+const verified = await verifyAdjustment(input, {
+  observe: async () => { throw new Error('ordinary verification must use the assertion boundary') },
+  expectState: async args => {
+    assertions++
+    assert.equal(args.element_id, 'control')
+    return { success: false, observed_state: { value: 20.25 }, reason: 'exact comparison failed' } as ExpectStateResponse
+  }
+})
+assert.equal(assertions, 1)
+assert.equal(verified.withinTolerance, true, 'numeric tolerance is independent of exact assertion success')
+assert.equal(verified.observedState?.value, 20.25)
+const stale = await verifyAdjustment({ ...input, labeled: true, actualState: { property: 'value', value: 20 } }, {
+  observe: async () => { observations++; return { elements: [] } },
+  expectState: async () => { throw new Error('label verification must acquire a new tree') }
+})
+assert.equal(observations, 1)
+assert.equal(stale.withinTolerance, false, 'fallback state must not establish fresh convergence')
+assert.equal(stale.verification.success, false)
+assert.equal(stale.observedState?.value, 20, 'last readable state remains available for diagnostics')
+await assert.rejects(verifyAdjustment(input, {
+  observe: async () => null,
+  expectState: async () => { throw new Error('ACTION_TIMEOUT') }
+}), /ACTION_TIMEOUT/, 'timeouts propagate without manufacturing an observation')
+console.log('PASS adjustment verification dependencies, tolerance, freshness and timeout preservation')

package/test/unit/interact/clock_dependencies.test.ts

@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict'
+import type { Clock } from '../../../src/runtime/clock.js'
+import type { UiTree } from '../../../src/interact/observation.js'
+import { waitForUI } from '../../../src/interact/waits/ui-wait.js'
+import { waitForScreenChange } from '../../../src/interact/waits/screen-wait.js'
+import { findElement } from '../../../src/interact/targeting/find-element.js'
+import { expectState } from '../../../src/interact/assertions/state-assertion.js'
+import { _resolvedTargetFromElement } from '../../../src/interact/targeting/element-helpers.js'
+
+function fakeClock() {
+  let now = 1000
+  const delays: number[] = []
+  const clock: Clock = { now: () => now, sleep: async ms => { delays.push(ms); now += ms } }
+  return { clock, delays }
+}
+const resolve = (_platform: string, _device: string | undefined, element: NonNullable<UiTree['elements']>[number], index: number) => _resolvedTargetFromElement('test-id', element, index)
+const present = (clock: Clock): UiTree => ({ captured_at_ms: clock.now(), elements: [{ text: 'Button', state: { enabled: true } }] })
+
+{
+  const { clock, delays } = fakeClock()
+  const result = await waitForUI({ selector: { text: 'Button' }, timeout_ms: 500, poll_interval_ms: 50 }, {
+    clock, observe: async () => present(clock), resolve
+  })
+  assert.equal(result?.status, 'success')
+  assert.deepEqual(result?.metrics, { latency_ms: 50, poll_count: 2, attempts: 1 })
+  assert.deepEqual(delays, [50])
+}
+{
+  const { clock, delays } = fakeClock()
+  const result = await waitForUI({ selector: { text: 'missing' }, timeout_ms: 100, poll_interval_ms: 50,
+    retry: { max_attempts: 2, backoff_ms: 20 } }, { clock, observe: async () => ({ elements: [] }), resolve })
+  assert.equal(result?.status, 'timeout')
+  assert.deepEqual(result?.metrics, { latency_ms: 320, poll_count: 6, attempts: 2 })
+  assert.deepEqual(delays, [50, 50, 50, 20, 50, 50, 50])
+}
+{
+  const { clock, delays } = fakeClock()
+  let samples = 0
+  const result = await waitForScreenChange({ previousFingerprint: 'old', timeoutMs: 500, pollIntervalMs: 50 }, {
+    clock, fingerprint: async () => ({ fingerprint: samples++ === 0 ? 'old' : 'new' })
+  })
+  assert.equal(result.success, true)
+  assert.equal(result.elapsedMs, 100)
+  assert.deepEqual(delays, [50, 50])
+}
+{
+  const { clock, delays } = fakeClock()
+  const result = await findElement({ query: 'missing', timeoutMs: 200 }, async () => ({ elements: [] }), clock)
+  assert.equal(result.found, false)
+  assert.deepEqual(delays, [100, 100, 100])
+}
+{
+  const { clock, delays } = fakeClock()
+  const result = await expectState({ selector: { text: 'Button' }, property: 'enabled', expected: true }, {
+    clock, observe: async () => present(clock), getHandle: () => undefined,
+    currentHandle: () => null, target: (platform, device, match) => resolve(platform, device, match.el, match.idx)
+  })
+  assert.equal(result.success, true)
+  assert.equal(result.stabilization_window_ms, 150)
+  assert.deepEqual(delays, [150])
+  assert(result.trace.steps.every(step => step.timestamp >= 1000 && step.timestamp <= 1150))
+}
+console.log('PASS injected clocks: wait stability, retry/backoff deadlines, screen confirmation, search expiry and state trace timestamps without global timer replacement')

package/test/unit/interact/element_helpers.test.ts

@@ -0,0 +1,19 @@
+import assert from 'node:assert/strict'
+import { _matchesSelector, _resolveActionableAncestor, _normalizeBounds } from '../../../src/interact/targeting/element-helpers.js'
+import { _readNumericControlRange, _quantizeTargetValue } from '../../../src/interact/adjustment/control-values.js'
+
+assert(_matchesSelector({ text: 'Save', resourceId: 'app:id/save' }, { text: 'save', resource_id: 'app:id/save' }))
+assert(!_matchesSelector({ text: 'Save', resourceId: 'app:id/other' }, { text: 'save', resource_id: 'app:id/save' }), 'all supplied selector fields constrain selection')
+assert(_matchesSelector({ contentDesc: 'Save changes' }, { accessibility_id: 'changes', contains: true }))
+assert(!_matchesSelector({ text: 'Save' }, undefined))
+assert.deepEqual(_normalizeBounds(['1', 2, 3, 4]), [1, 2, 3, 4])
+assert.equal(_normalizeBounds([1, 'invalid', 3, 4]), null)
+const elements = [
+  { id: 'parent', clickable: true, bounds: [0, 0, 100, 100] },
+  { parentId: 'parent', text: 'Save', bounds: [20, 20, 40, 40] }
+]
+assert.deepEqual(_resolveActionableAncestor(elements, { el: elements[1], idx: 1 }), { el: elements[0], idx: 0 })
+assert.deepEqual(_readNumericControlRange({ state: { value: '3 of 10' } }), { min: 0, max: 10 })
+assert.equal(_readNumericControlRange({ state: { value_range: { min: 10, max: 0 } } }), null)
+assert.equal(_quantizeTargetValue(0.26, 0, 1, 0.1), 0.3)
+console.log('PASS injected-free selector, actionable ancestor, numeric range and snapping helpers')

package/test/unit/interact/legacy_wait_service.test.ts

@@ -0,0 +1,17 @@
+import assert from 'node:assert/strict'
+import { waitForUICore } from '../../../src/interact/waits/legacy-wait.js'
+import type { LegacyWaitDependencies } from '../../../src/interact/waits/legacy-wait-state.js'
+
+const calls: string[] = []
+const deps: LegacyWaitDependencies = {
+  fingerprint: async () => { calls.push('fingerprint'); return { fingerprint: 'initial' } },
+  logs: async () => { calls.push('logs'); return { logs: ['before'] } },
+  stream: async () => { calls.push('stream'); return { entries: [{ message: 'operation done' }] } },
+  find: async () => { throw new Error('log waits must not search UI elements') },
+  snapshot: async () => { throw new Error('successful waits must not collect failure snapshots') }
+}
+const result = await waitForUICore({ type: 'log', query: 'done', timeoutMs: 1000 }, deps)
+assert.equal(result.success, true)
+assert.equal(result.observed_state, true)
+assert.deepEqual(calls, ['fingerprint', 'logs', 'stream'])
+console.log('PASS injected legacy wait: baseline collection, stream-first matching and no failure snapshot')

package/test/unit/interact/state_comparison.test.ts

@@ -0,0 +1,20 @@
+import assert from 'node:assert/strict'
+import { compareReadableState } from '../../../src/interact/assertions/state-comparison.js'
+
+assert.equal(compareReadableState('checked', true, { checked: true }).success, true)
+const invalidBoolean = compareReadableState('checked', 'true', { checked: true })
+assert.equal(invalidBoolean.success, false)
+assert.equal(invalidBoolean.reason, 'expected checked must be boolean')
+assert.equal(invalidBoolean.observedValue, true)
+assert.equal(invalidBoolean.rawValue, null)
+assert.equal(compareReadableState('value', 20, { value: '20' }).success, false, 'numeric assertions do not coerce readable strings')
+assert.equal(compareReadableState('value', '20', { value: '20' }).success, true)
+assert.equal(compareReadableState('selected', { id: 'dark' }, { selected: { id: 'dark', label: 'Dark' } }).success, true)
+assert.equal(compareReadableState('selected', false, { selected: false }).success, true)
+assert.equal(compareReadableState('selected', true, { selected: 'true' }).reason, 'selected state is not boolean')
+assert.equal(compareReadableState('text_value', '', { text_value: '' }).reason, 'expected text_value must be string')
+assert.equal(compareReadableState('value', 20, null).reason, 'value state unavailable')
+const range = { min: 0, max: 20 }
+assert.equal(compareReadableState('value_range', range, { value_range: range }).success, true, 'fallback comparison preserves reference equality')
+assert.equal(compareReadableState('value_range', { min: 0, max: 20 }, { value_range: range }).success, false)
+console.log('PASS readable-state comparison compatibility without UI or global mocks')

package/test/unit/interact/target_scope.test.ts

@@ -0,0 +1,35 @@
+import assert from 'node:assert/strict'
+import { ResolvedElements } from '../../../src/interact/targeting/resolved-elements.js'
+import { findScopedElement, resolveUiChangeScope } from '../../../src/interact/targeting/target-scope.js'
+import type { ResolvedUiElementContext } from '../../../src/interact/model.js'
+
+const store = new ResolvedElements(2)
+const context = (id: string): ResolvedUiElementContext => ({
+  elementId: id, platform: 'android', deviceId: 'fixture', bounds: null, index: 0, stable_id: id
+})
+store.remember('one', context('one'))
+store.remember('two', context('two'))
+store.remember('one', context('one'))
+store.remember('three', context('three'))
+assert.equal(store.get('two'), undefined, 'oldest handle is evicted; refresh updates insertion order')
+assert(store.get('one'))
+const tree = { elements: [{ text: 'Root', stable_id: 'one', children: [1] }, { text: 'Child', parentId: 0 }] }
+const match = findScopedElement(tree, 'one', store)
+assert.equal(match?.index, 0)
+assert.equal(match?.reason, 'stable_id_match')
+let calls = 0
+const subtree = resolveUiChangeScope(tree, 'subtree', 'custom-handle', (_tree, id) => {
+  calls++
+  assert.equal(id, 'custom-handle')
+  return { index: 0, stableId: 'one', reason: 'injected_lookup' }
+})
+assert.equal(calls, 1)
+assert.equal(subtree.elements.length, 2)
+assert.equal(subtree.resolution.reason, 'injected_lookup')
+assert.equal(resolveUiChangeScope(tree, 'subtree', '', () => { throw new Error('must not resolve empty targets') }).error?.code, 'INVALID_SCOPE')
+assert.equal(resolveUiChangeScope(tree, 'subtree', 'missing', () => null).error?.code, 'ELEMENT_NOT_FOUND')
+const other = new ResolvedElements(2)
+assert.equal(other.get('one'), undefined, 'resolution stores do not share process-global state')
+store.clear()
+assert.equal(store.get('one'), undefined)
+console.log('PASS bounded handle retention and injected subtree resolution without static replacements')

package/test/unit/network/get_network_activity.test.ts

@@ -5,7 +5,7 @@ import {
   classifyStatus,
   _setTimestampsForTests,
   ToolsNetwork
-} from '../../../src/network/index.js'
+} from '../../../src/observe/network/index.js'
 
 function run() {
 

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,131 @@
+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 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.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')

package/test/unit/observe/screenshot-encoding.test.ts

@@ -0,0 +1,30 @@
+import assert from 'node:assert/strict'
+import sharp from 'sharp'
+import { encodeScreenshot } from '../../../src/observe/screenshot-encoding.js'
+
+async function run() {
+  const alpha = await sharp({ create: { width: 2, height: 2, channels: 4, background: { r: 255, g: 0, b: 0, alpha: 0.5 } } }).png().toBuffer()
+  const opaque = await sharp({ create: { width: 2, height: 2, channels: 3, background: 'red' } }).png().toBuffer()
+  for (const platform of ['android', 'ios'] as const) {
+    const transparent = await encodeScreenshot(alpha, platform)
+    assert.equal(transparent.screenshot_mime, 'image/webp')
+    assert.equal((await sharp(Buffer.from(transparent.screenshot, 'base64')).metadata()).hasAlpha, true)
+    assert.equal(transparent.screenshot_fallback_mime, platform === 'ios' ? 'image/png' : 'image/jpeg')
+    if (platform === 'ios') assert.equal(transparent.screenshot_fallback, alpha.toString('base64'))
+    const solid = await encodeScreenshot(opaque, platform)
+    assert.equal(solid.screenshot_mime, 'image/webp')
+    assert.equal(solid.screenshot_fallback_mime, 'image/jpeg')
+    assert.equal((await sharp(Buffer.from(solid.screenshot_fallback!, 'base64')).metadata()).format, 'jpeg')
+  }
+  // An unreadable capture must survive conversion failures unchanged.
+  const invalid = Buffer.from('unreadable screenshot')
+  const originalError = console.error
+  try {
+    console.error = () => {}
+    for (const platform of ['android', 'ios'] as const) {
+      assert.deepEqual(await encodeScreenshot(invalid, platform), { screenshot: invalid.toString('base64'), screenshot_mime: 'image/png' })
+    }
+  } finally { console.error = originalError }
+  console.log('Screenshot alpha, fallback format and failed conversion tests passed')
+}
+run().catch(error => { console.error(error); process.exit(1) })

package/test/unit/observe/snapshot-logs.test.ts

@@ -0,0 +1,14 @@
+import assert from 'node:assert/strict'
+import { snapshotLog, streamLog } from '../../../src/observe/snapshot-logs.js'
+
+const iso = '2026-10-30T12:00:00Z'
+assert.deepEqual(snapshotLog({ timestamp: 123, message: 'warning', levelName: 'warn' }), { timestamp: 123, message: 'warning', level: 'WARN' })
+assert.equal(streamLog({ timestamp: 123, message: 'warning' }).timestamp, null)
+assert.equal(snapshotLog({ timestamp: 123, _iso: iso, msg: 'hello' }).timestamp, 123)
+assert.equal(streamLog({ timestamp: 123, _iso: iso, msg: 'hello' }).timestamp, Date.parse(iso))
+assert.equal(snapshotLog('FATAL EXCEPTION: crash').level, 'ERROR')
+assert.equal(streamLog('WARN: slow').level, 'WARN')
+assert.equal(snapshotLog({ timestamp: 'invalid', msg: 'hello' }).timestamp, null)
+assert.deepEqual(snapshotLog(null), { timestamp: null, level: 'INFO', message: '' })
+assert.equal(snapshotLog({ context: 'value' }).message, '{"context":"value"}')
+console.log('Snapshot and stream timestamp precedence and log normalization tests passed')

package/test/unit/observe/system-trace-router.test.ts

@@ -0,0 +1,49 @@
+import assert from 'node:assert/strict'
+import { SystemTraceRouter } from '../../../src/observe/system-trace-router.js'
+import type { SystemTraceSessions, TraceResult } from '../../../src/observe/system-trace.js'
+import type { IosTraceSessions, IosTraceResult } from '../../../src/observe/ios-trace/sessions.js'
+import type { IosTraceNative } from '../../../src/observe/ios-trace/native.js'
+function backend(platform:'android'|'ios') {
+  let next=0,starts=0
+  const results=new Map<string,TraceResult|IosTraceResult>()
+  const api={
+    capabilities:async()=>({}),
+    start:async(device:string|{id:string})=>{
+      starts++
+      const result={trace_id:platform+ ++next,device:{platform,id:typeof device==='string'?device:device.id},state:'recording',cleanup:{status:'pending'}} as TraceResult|IosTraceResult
+      results.set(result.trace_id,result);return result
+    },
+    control:async(id:string,op:string)=>{
+      const result=results.get(id);if(!result)throw new Error('TRACE_NOT_FOUND')
+      if(op==='cancel'){result.cleanup.status='complete';result.state='cancelled'}
+      return result
+    },
+    link:async()=>async()=>({trace_id:'linked',coverage:'covered',clock_alignment:'unknown'}),
+    shutdown:async()=>[]
+  }
+  return {api,results,count:()=>starts}
+}
+async function run(){
+  const android=backend('android'),ios=backend('ios')
+  let release!:()=>void,gate=Promise.resolve()
+  const native={shutdown:()=>{},capabilities:async(device:string)=>{await gate;return {supported:true,device:{platform:'ios',id:device,simulator:true}}}} as unknown as IosTraceNative
+  const router=new SystemTraceRouter(android.api as unknown as SystemTraceSessions,ios.api as unknown as IosTraceSessions,native)
+  const a=await router.start('a'),b=await router.start('b',30000,{appId:'fixture'})
+  await assert.rejects(()=>router.link(b.trace_id,{platform:'android',id:'b'},'bad'),/TRACE_NOT_FOUND/)
+  await assert.rejects(()=>router.link(b.trace_id,{platform:'ios',id:'other'},'bad'),/TRACE_NOT_FOUND/)
+  await assert.rejects(()=>router.start('b',30000,{appId:'fixture'}),/TRACE_BUSY/)
+  await router.start('c');await router.start('d',30000,{appId:'fixture'})
+  await assert.rejects(()=>router.start('fifth'),/TRACE_BUSY/)
+  await router.control(a.trace_id,'cancel')
+  await router.start('freed')
+  await router.control(b.trace_id,'cancel')
+  gate=new Promise<void>(r=>{release=r})
+  const first=router.start('pending',30000,{appId:'fixture'})
+  await new Promise(r=>setImmediate(r))
+  await assert.rejects(()=>router.start('pending',30000,{appId:'fixture'}),/TRACE_BUSY/)
+  release();await first
+  assert.equal(ios.count(),3)
+  await router.shutdown();await assert.rejects(()=>router.start('closed'),/TRACE_BUSY/)
+  console.log('PASS cross-platform trace routing, pinned linkage, shared reservations and shutdown')
+}
+run().catch(error=>{console.error(error);process.exitCode=1})