mobile-debug-mcp 0.34.0 → 0.36.0

package/test/device/automated/debugger/runtime.ios.test.ts

@@ -0,0 +1,221 @@
+import assert from 'node:assert/strict'
+import { execFileSync } from 'node:child_process'
+import { readFile, rm, readdir, writeFile, rename } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { buildIOSDebuggerFixture, iosDebuggerAppId, iosDebuggerSource } from '../../../fixtures/ios-debugger-app/build.js'
+
+if (!process.env.MCP_IOS_DEBUGGER_DEVICE) {
+  console.log('UNRUN iOS debugger: select a booted simulator with MCP_IOS_DEBUGGER_DEVICE')
+} else {
+  const deviceId = process.env.MCP_IOS_DEBUGGER_DEVICE
+  const sim = (...args: string[]) => execFileSync('xcrun', ['simctl', ...args], { encoding: 'utf8', timeout: 30000 }).trim()
+  console.log('Building disposable iOS fixture')
+  const fixture = buildIOSDebuggerFixture()
+  console.log('Fixture built')
+  const source = await readFile(iosDebuggerSource, 'utf8')
+  const line = (marker: string) => source.split('\n').findIndex(row => row.includes('// ' + marker)) + 1
+  const client = new Client({ name: 'ios-debugger-smoke', version: '1.0.0' })
+  const transport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
+  transport.stderr?.on('data', data => process.stderr.write(data))
+  const call = async (name: string, args: Record<string, unknown> = {}, signal?: AbortSignal) => {
+    const response = await client.callTool({ name, arguments: args }, undefined, { timeout: 45000, signal })
+    return JSON.parse((response.content as { type: string; text: string }[]).find(item => item.type === 'text')!.text)
+  }
+  const hash = createHash('sha256')
+  const fingerprint = async (directory: string): Promise<void> => {
+    for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+      const file = directory + '/' + entry.name
+      if (entry.isDirectory()) await fingerprint(file)
+      else if (!file.includes('__pycache__')) hash.update(file).update(await readFile(file))
+    }
+  }
+  await fingerprint('dist'); await fingerprint('src/debugger/lldb')
+  const serverHash = hash.digest('hex')
+  const target = { platform: 'ios', deviceId, appId: iosDebuggerAppId }
+  let debugSessionId = '', cursor = 0
+  const session = () => ({ debugSessionId })
+  const attach = async () => {
+    const response = await call('attach_debugger', { ...target, timeoutMs: 30000 })
+    assert.equal(response.success, true, JSON.stringify(response))
+    assert.equal(response.device.platform, 'ios')
+    debugSessionId = response.debug_session_id; cursor = 0
+  }
+  const breakpoint = async (marker: string) => {
+    const response = await call('set_debugger_breakpoint', { ...session(), sourceFile: iosDebuggerSource, line: line(marker) })
+    assert.equal(response.success, true, JSON.stringify(response))
+    assert.equal(response.result.status, 'resolved', JSON.stringify(response))
+    assert.ok(response.result.locations.every((loc: any) => loc.line === line(marker)))
+    return response.result.breakpoint_id
+  }
+  const remove = (breakpointId: string) => call('remove_debugger_breakpoint', { ...session(), breakpointId })
+  const stop = async () => {
+    for (let i = 0; i < 15; i++) {
+      const response = await call('wait_for_debugger_event', { ...session(), afterSequence: cursor, timeoutMs: 1000 })
+      assert.equal(response.success, true, JSON.stringify(response)); cursor = response.next_cursor
+      const found = response.events.find((event: any) => event.event === 'stopped')
+      if (found) { console.log('STOP', JSON.stringify(found)); return found }
+    }
+    throw new Error('No iOS debugger stop observed')
+  }
+  const resume = (event: any) => call('resume_debugger', { ...session(), stopId: event.stop_id })
+  const locals = async (event: any) => {
+    const stack = await call('get_debugger_stack', { ...session(), stopId: event.stop_id, threadId: event.thread_id })
+    assert.equal(stack.success, true, JSON.stringify(stack))
+    const frame = stack.result.frames.find((f: any) => f.source_file === iosDebuggerSource)
+    assert.ok(frame, JSON.stringify(stack))
+    const result = await call('get_debugger_locals', { ...session(), stopId: event.stop_id, frameId: frame.frame_id })
+    assert.equal(result.success, true, JSON.stringify(result)); console.log('LOCALS', JSON.stringify(result.result))
+    return { result: result.result, frame }
+  }
+  const expectLocal = (result: any, name: string, value: string) => assert.equal(result.locals.find((v: any) => v.name === name)?.value, value, JSON.stringify(result))
+  let commandFile = ''
+  const trigger = async (command: string) => {
+    console.log('TRIGGER', command)
+    await writeFile(commandFile + '.next', command)
+    await rename(commandFile + '.next', commandFile)
+  }
+  const tap = async (text: string) => {
+    const tree = await call('get_ui_tree', { platform: 'ios', deviceId })
+    assert.ok(tree.elements.some((e: any) => e.text === text), JSON.stringify(tree))
+    const commands: Record<string, string> = { Calculate: 'calculate', 'Run async': 'async', 'Start cancellation': 'start-cancellation', 'Cancel task': 'cancel' }
+    // The installed idb HID backend is unavailable. A fixture-only main-loop
+    // command file invokes the same button actions without debugger evaluation.
+    await trigger(commands[text])
+  }
+  const expectUI = async (text: string) => {
+    for (let i = 0; i < 15; i++) {
+      const tree = await call('get_ui_tree', { platform: 'ios', deviceId })
+      if (tree.elements.some((e: any) => e.text === text)) return
+      await new Promise(resolve => setTimeout(resolve, 200))
+    }
+    throw new Error('Missing independent UI state: ' + text)
+  }
+  const detach = async () => {
+    const response = await call('detach_debugger', session())
+    assert.equal(response.cleanup.status, 'complete', JSON.stringify(response))
+    assert.deepEqual(response.cleanup.remaining_resources, [])
+    assert.equal((await call('detach_debugger', session())).cleanup.status, 'complete')
+  }
+  try {
+    sim('install', deviceId, fixture.app)
+    sim('launch', deviceId, iosDebuggerAppId)
+    commandFile = sim('get_app_container', deviceId, iosDebuggerAppId, 'data') + '/Documents/debugger-command'
+    await client.connect(transport)
+    const shortProbe = await call('get_debugger_capabilities', { ...target, timeoutMs: 100 })
+    assert.equal(shortProbe.error?.code, 'DEBUGGER_TIMEOUT')
+    const absent = await call('get_debugger_capabilities', { ...target, appId: 'dev.mobiledebug.absentfixture' })
+    assert.equal(absent.supported, false); assert.ok(absent.reasons.includes('PROCESS_NOT_FOUND'))
+    const cap = await call('get_debugger_capabilities', target)
+    assert.equal(cap.supported, true, JSON.stringify(cap))
+    assert.equal(cap.capabilities.async_execution_inspection, true)
+    assert.equal(cap.capabilities.async_stepping, true)
+    const foreign = await call('attach_debugger', { ...target, processId: process.pid })
+    assert.equal(foreign.success, false); assert.equal(foreign.error.code, 'PROCESS_NOT_FOUND')
+    await attach()
+    const bp = await breakpoint('BREAK_CALCULATE')
+    const pending = await call('set_debugger_breakpoint', { ...session(), sourceFile: '/tmp/nonexistent-ios-debugger-source.swift', line: 1 })
+    assert.equal(pending.result.status, 'pending'); await remove(pending.result.breakpoint_id)
+    const noncode = await call('set_debugger_breakpoint', { ...session(), sourceFile: iosDebuggerSource, line: 9999 })
+    assert.equal(noncode.result.status, 'rejected'); await remove(noncode.result.breakpoint_id)
+    const storedHandle = await call('wait_for_ui', { platform: 'ios', deviceId, selector: { text: 'Calculate' }, condition: 'exists', timeout_ms: 10000 })
+    assert.equal(storedHandle.status, 'success', JSON.stringify(storedHandle))
+    assert.ok(storedHandle.element.elementId)
+    await tap('Calculate')
+    let event = await stop()
+    const originalStop = event
+    assert.equal(event.location.line, line('BREAK_CALCULATE'))
+    const inspected = await locals(event); expectLocal(inspected.result, 'known', '41')
+    const guarded = await call('tap', { platform: 'ios', deviceId, x: 10, y: 10 })
+    assert.equal(guarded.failure_code, 'DEBUGGER_PAUSED'); assert.equal(guarded.delivery_status, 'not_delivered')
+    const storedTap = await call('tap_element', { elementId: storedHandle.element.elementId, verificationMode: 'none', responseMode: 'compact' })
+    assert.equal(storedTap.failure_code, 'DEBUGGER_PAUSED', JSON.stringify(storedTap))
+    assert.equal(storedTap.delivery_status, 'not_delivered'); assert.equal(storedTap.dispatch_started, false)
+    assert.deepEqual(storedTap.debugger.device, { platform: 'ios', id: deviceId })
+    console.log('PASS paused stored iOS handle without platform/device hints rejected before dispatch')
+    assert.equal((await call('get_app_readiness', { platform: 'ios', deviceId })).readiness.state, 'debugger_paused')
+    await remove(bp)
+    for (const kind of ['into', 'over', 'out']) {
+      const response = await call('step_debugger', { ...session(), stopId: event.stop_id, threadId: event.thread_id, kind })
+      assert.equal(response.success, true, JSON.stringify(response)); event = await stop()
+    }
+    const stale = await call('get_debugger_locals', { ...session(), stopId: originalStop.stop_id, frameId: inspected.frame.frame_id })
+    assert.equal(stale.error.code, 'DEBUGGER_STALE_REFERENCE')
+    await resume(event)
+    await expectUI('Debugger result 42')
+    const controller = new AbortController()
+    const waiting = call('wait_for_debugger_event', { ...session(), afterSequence: cursor, timeoutMs: 30000 }, controller.signal)
+    setTimeout(() => controller.abort(), 100)
+    await assert.rejects(waiting)
+    assert.equal((await call('get_debugger_state', session())).state, 'running')
+    await detach()
+
+    await attach()
+    const before = await breakpoint('BEFORE_AWAIT'), after = await breakpoint('AFTER_AWAIT')
+    await tap('Run async')
+    event = await stop(); assert.equal(event.location.line, line('BEFORE_AWAIT'))
+    expectLocal((await locals(event)).result, 'known', '42')
+    await remove(before)
+    await resume(event)
+    event = await stop(); assert.equal(event.location.line, line('AFTER_AWAIT'))
+    expectLocal((await locals(event)).result, 'after', '43')
+    await remove(after); await resume(event)
+    await expectUI('Async result 44')
+    await detach()
+
+    // Boundary stepping has a distinct evidence result, independent of breakpoint coverage.
+    await attach()
+    const boundary = await breakpoint('BEFORE_AWAIT')
+    await tap('Run async'); event = await stop(); await remove(boundary)
+    assert.equal((await call('step_debugger', { ...session(), stopId: event.stop_id, threadId: event.thread_id, kind: 'over' })).success, true)
+    event = await stop()
+    assert.equal(event.location.source_file, iosDebuggerSource)
+    assert.equal(event.location.line, line('AFTER_AWAIT'), 'Advertised async stepping must follow the continuation')
+    console.log('ASYNC_BOUNDARY_STEP', JSON.stringify({ expected_line: line('AFTER_AWAIT'), observed: event.location }))
+    await detach(); await expectUI('Async result 44')
+
+    await attach()
+    const cancel = await breakpoint('CANCELLED')
+    await tap('Start cancellation'); await expectUI('Task running'); await tap('Cancel task')
+    event = await stop(); expectLocal((await locals(event)).result, 'cancelled', 'true')
+    await remove(cancel); await resume(event); await detach(); await expectUI('Task cancelled')
+
+    if (process.env.MCP_IOS_DEBUGGER_EXTENDED === '1') {
+      await attach(); await breakpoint('BREAK_CALCULATE'); await tap('Calculate'); await stop()
+      const deadline = Date.now() + 75000
+      let state: any
+      do { await new Promise(resolve => setTimeout(resolve, 1000)); state = await call('get_debugger_state', session()) } while (state.state === 'paused' && Date.now() < deadline)
+      assert.equal(state.reason, 'pause_limit'); assert.equal(state.cleanup.status, 'complete')
+      await expectUI('Debugger result 42')
+    }
+    await attach()
+    await trigger('exit')
+    let exited: any
+    for (let i = 0; i < 100; i++) {
+      exited = await call('get_debugger_state', session())
+      if (exited.state === 'disconnected' && exited.cleanup.status === 'complete') break
+      await new Promise(resolve => setTimeout(resolve, 100))
+    }
+    assert.equal(exited.state, 'disconnected'); assert.equal(exited.cleanup.status, 'complete')
+    sim('launch', deviceId, iosDebuggerAppId); await expectUI('Debugger ready')
+    // Clear the earlier calculate result before proving shutdown recovery.
+    await tap('Start cancellation'); await expectUI('Task running'); await tap('Cancel task'); await expectUI('Task cancelled')
+    // Closing the server while paused must release its owned suspension.
+    await attach(); await breakpoint('BREAK_CALCULATE'); await tap('Calculate'); await stop()
+    await client.close()
+    const verifier = new Client({ name: 'ios-cleanup-verifier', version: '1.0.0' })
+    await verifier.connect(new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' }))
+    try {
+      const response = await verifier.callTool({ name: 'get_ui_tree', arguments: { platform: 'ios', deviceId } })
+      const tree = JSON.parse((response.content as any[])[0].text)
+      assert.ok(tree.elements.some((e: any) => e.text === 'Debugger result 42'), JSON.stringify(tree))
+    } finally { await verifier.close() }
+    console.log('PASS iOS MCP debugger core/async/cancellation/cleanup', JSON.stringify({ deviceId, server_sha256: serverHash, source_sha256: createHash('sha256').update(source).digest('hex'), xcode: execFileSync('xcodebuild', ['-version'], { encoding: 'utf8' }).trim(), lldb: execFileSync('xcrun', ['lldb', '--version'], { encoding: 'utf8' }).trim() }))
+  } finally {
+    if (debugSessionId) { try { await call('detach_debugger', session()) } catch {} }
+    await client.close().catch(() => {})
+    sim('uninstall', deviceId, iosDebuggerAppId)
+    await rm(fixture.directory, { recursive: true, force: true })
+  }
+}

package/test/device/automated/interact/interaction.android.test.ts

@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict'
+import { execFileSync } from 'node:child_process'
+import { rm } from 'node:fs/promises'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { buildDebuggerFixture, debuggerAppId } from '../../../fixtures/debugger-app/build.js'
+
+// Reuse the isolated fixture; the device runner executes fixture journeys sequentially.
+const deviceId = process.env.MCP_INTERACTION_DEVICE ?? process.env.MCP_DEBUGGER_DEVICE
+if (!deviceId) {
+  console.log('UNRUN Android interaction fixture: select an emulator with MCP_INTERACTION_DEVICE')
+} else {
+  const fixture = buildDebuggerFixture()
+  const adb = (...args: string[]) => execFileSync(process.env.ADB_PATH || 'adb', ['-s', deviceId, ...args], { encoding: 'utf8', timeout: 30000 })
+  const client = new Client({ name: 'interaction-service-smoke', version: '1.0.0' })
+  const target = { platform: 'android', deviceId }
+  const call = async (name: string, args: Record<string, unknown>) => {
+    const response = await client.callTool({ name, arguments: args }, undefined, { timeout: 120000 })
+    const text = response.content.find(item => item.type === 'text')
+    assert(text?.type === 'text')
+    return JSON.parse(text.text)
+  }
+  try {
+    await client.connect(new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' }))
+    adb('install', '-r', fixture.artifact)
+    const started = await call('start_app', { ...target, appId: debuggerAppId, verificationMode: 'none', responseMode: 'compact' })
+    assert.equal(started.success, true)
+    const waited = await call('wait_for_ui', { ...target, selector: { text: 'Calculate' }, condition: 'clickable', timeout_ms: 20000 })
+    assert.equal(waited.status, 'success', JSON.stringify(waited))
+    assert.ok(waited.element?.elementId)
+    const tapped = await call('tap_element', { ...target, elementId: waited.element.elementId, verificationMode: 'none', actionTimeoutMs: 30000 })
+    assert.equal(tapped.success, true, JSON.stringify(tapped))
+    const visible = await call('expect_element_visible', { ...target, selector: { text: 'Result 43' }, timeout_ms: 20000 })
+    assert.equal(visible.success, true, JSON.stringify(visible))
+    const journey = await call('run_journey', { ...target, steps: [
+      { id: 'calculate-again', type: 'tap', selector: { text: 'Calculate' }, verificationMode: 'none' },
+      { id: 'enabled-result', type: 'assert', timeoutMs: 30000, assertion: { kind: 'state_equals', selector: { text: 'Result 43' }, property: 'enabled', expected: true } },
+      { id: 'visible-result', type: 'assert', timeoutMs: 20000, assertion: { kind: 'element_visible', selector: { text: 'Result 43' } } }
+    ], defaults: { actionTimeoutMs: 30000 } })
+    assert.equal(journey.success, true, JSON.stringify(journey))
+    const adjusted = await call('adjust_control', { ...target, selector: { accessibility_id: 'Fixture level' },
+      property: 'value', targetValue: 75, tolerance: 5, maxAttempts: 5 })
+    assert.equal(adjusted.success, true, JSON.stringify(adjusted))
+    assert.equal(adjusted.converged, true, JSON.stringify(adjusted))
+    assert(Math.abs(adjusted.actual_state.value - 75) <= 5, JSON.stringify(adjusted))
+    const level = await call('expect_element_visible', { ...target, selector: { text: `${adjusted.actual_state.value} %` }, timeout_ms: 20000 })
+    assert.equal(level.success, true, JSON.stringify(level))
+    console.log(JSON.stringify({ status: 'PASS', server: client.getServerVersion(), device: deviceId,
+      api: adb('shell', 'getprop', 'ro.build.version.sdk').trim(), runtime: process.version,
+      journey: 'clickable wait, resolved-handle tap, visible assertion, selector journey and stable enabled-state assertion and labelled SeekBar convergence',
+      evidence: 'Result 43, enabled=true and adjusted slider label established by fresh hierarchy assertions', cleanup: 'Owned fixture removed in finally; no other app data or device settings changed' }))
+  } finally {
+    await client.close()
+    try { adb('uninstall', debuggerAppId) } finally { await rm(fixture.directory, { recursive: true, force: true }) }
+  }
+}

package/test/device/automated/observe/ios-system-trace.smoke.ts

@@ -0,0 +1,119 @@
+import { verifyIosTraceShutdown } from '../../../helpers/ios-trace-shutdown.js'
+import assert from 'node:assert/strict'
+import { execFileSync } from 'node:child_process'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { createHash } from 'node:crypto'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { buildReadinessFixture, readinessAppId } from '../../../fixtures/readiness-app/build.js'
+
+const inputEnvironment = () => Object.fromEntries(['IDB_COMPANION','MCP_IDB_PATH','IDB_PATH','XCRUN_PATH'].flatMap(key=>process.env[key]?[[key,process.env[key]!]]:[]))
+async function run() {
+  const deviceId=process.env.IOS_SYSTEM_TRACE_DEVICE
+  if(process.env.SKIP_DEVICE_TESTS==='1'||!deviceId){console.log('iOS system trace smoke: UNRUN (set IOS_SYSTEM_TRACE_DEVICE to an explicit simulator UDID)');return}
+  assert.equal(process.platform,'darwin')
+  const command=(args:string[])=>execFileSync('xcrun',args,{encoding:'utf8',timeout:120000,stdio:'pipe'})
+  const sims=JSON.parse(command(['simctl','list','devices','--json']))
+  const device=Object.values(sims.devices).flat().find((d:any)=>d.udid===deviceId) as any
+  assert.ok(device?.isAvailable,'Explicit available simulator required')
+  let booted=false,installed=false,fixture:ReturnType<typeof buildReadinessFixture>|undefined
+  const client=new Client({name:'ios-system-trace-smoke',version:'1.0.0'})
+  const transport=new StdioClientTransport({command:process.execPath,args:['dist/server.js'],stderr:'pipe',env:inputEnvironment()})
+  const owned=new Set<string>(),artifacts:string[]=[],checks:Record<string,unknown>={}
+  let journeyFailure: Error | undefined
+  const target={platform:'ios',deviceId},traceTarget={...target,appId:readinessAppId}
+  const call=async(name:string,args:Record<string,unknown>)=>{
+    const result=await client.callTool({name,arguments:args},undefined,{timeout:180000})
+    return JSON.parse((result.content as any[]).find(c=>c.type==='text').text)
+  }
+  const start=async(durationMs=90000)=>{
+    const r=await call('start_system_trace',{...traceTarget,durationMs})
+    if(r.trace_id&&r.cleanup?.status!=='complete')owned.add(r.trace_id)
+    assert.equal(r.state,'recording',JSON.stringify(r));assert.ok(r.recording_ready_at_ms>=r.capture_started_at_ms)
+    return r
+  }
+  const stop=async(id:string)=>{
+    const r=await call('stop_system_trace',{traceId:id})
+    if(r.artifact)artifacts.push(r.artifact.path)
+    assert.equal(r.state,'completed',JSON.stringify(r));assert.equal(r.cleanup.status,'complete')
+    assert.equal(r.artifact.validation.readable,true);owned.delete(id);return r
+  }
+  try{
+    if(device.state!=='Booted'){command(['simctl','boot',deviceId]);booted=true;command(['simctl','bootstatus',deviceId,'-b'])}
+    let preexisting=false
+    try{const existing=command(['simctl','get_app_container',deviceId,readinessAppId,'app']).trim();await fs.stat(existing);preexisting=true}catch{/* absent or stale simulator registration */}
+    assert.equal(preexisting,false,'Refuse to replace a pre-existing fixture')
+    fixture=buildReadinessFixture('ios');command(['simctl','install',deviceId,fixture.artifact]);installed=true
+    command(['simctl','launch',deviceId,readinessAppId])
+    await client.connect(transport)
+    const cap=await call('get_system_trace_capabilities',traceTarget)
+    assert.equal(cap.supported,true,JSON.stringify(cap));assert.equal(cap.prerequisites.permissions,'unknown')
+    const tree=await call('get_ui_tree',target)
+    assert.ok(tree.elements.some((e:any)=>e.text==='Ready'),'Fixture must be semantically visible')
+    assert.ok(tree.elements.some((e:any)=>e.text==='Show loader'),'Fixture button must be semantically visible')
+    const recording=await start()
+    const baselineJourney=await call('run_journey',{...target,systemTraceId:recording.trace_id,steps:[{id:'ready',type:'assert',timeoutMs:10000,assertion:{kind:'element_visible',selector:{text:'Ready'}}}]})
+    assert.equal(baselineJourney.success,true,JSON.stringify(baselineJourney));checks.linked_baseline='PASS; Ready asserted via built-server journey'
+    const journeySubmitted=Date.now()
+    const journey=await call('run_journey',{...target,systemTraceId:recording.trace_id,steps:[
+      {id:'show-loader',type:'tap',selector:{text:'Show loader'},verificationMode:'none'},
+      {id:'done',type:'assert',timeoutMs:30000,assertion:{kind:'element_visible',selector:{text:'Done'}}}
+    ]})
+    if (!journey.success) journeyFailure = new Error(`Traced fixture input journey failed at ${journey.stopped_at_step_id}; ${journey.steps[0].result?.failure_code}`)
+    else assert.equal(journey.steps[1].status,'passed')
+    assert.equal(journey.evidence.trace_context.trace_id,recording.trace_id)
+    assert.equal(journey.steps[0].result.evidence.trace_context.trace_id,recording.trace_id)
+    assert.equal(journey.system_trace.coverage,'covered');assert.ok(recording.recording_ready_at_ms<=journeySubmitted)
+    const completed=await stop(recording.trace_id)
+    assert.equal(completed.device.id,deviceId);assert.equal(completed.app_id,readinessAppId)
+    assert.deepEqual(completed.correlation_ids,[baselineJourney.evidence.correlation_id,journey.evidence.correlation_id]);assert.ok(completed.artifact.validation.sample_rows>0)
+    checks.journey={status:journey.success?'PASS':'FAIL',trace_id:recording.trace_id,correlation_id:journey.evidence.correlation_id,
+      ready_at_ms:recording.recording_ready_at_ms,journey_submitted_at_ms:journeySubmitted,outcome:journey.success?'Done visible via journey UI-tree assertion':journeyFailure?.message,
+      sample_rows:completed.artifact.validation.sample_rows,artifact_bytes:completed.artifact.size_bytes,warnings:completed.warnings}
+    const stale=await call('run_journey',{...target,systemTraceId:recording.trace_id,steps:[{id:'must-not-tap',type:'tap',selector:{text:'Show loader'},verificationMode:'none'}]})
+    assert.equal(stale.error.code,'TRACE_NOT_FOUND')
+    const unchanged=await call('expect_element_visible',{...target,selector:{text:journey.success?'Done':'Ready'},timeoutMs:10000})
+    assert.ok(unchanged.success||unchanged.visible||unchanged.status==='success',JSON.stringify(unchanged))
+    checks.stale_id='PASS; rejected tap left prior fixture label visible'
+    const cancelled=await start(30000),directory=cancelled.cleanup.remaining_resources[0]
+    const cancel=await call('cancel_system_trace',{traceId:cancelled.trace_id})
+    assert.equal(cancel.state,'cancelled');assert.equal(cancel.cleanup.status,'complete');assert.equal(cancel.artifact,null);owned.delete(cancelled.trace_id)
+    await assert.rejects(()=>fs.stat(directory),{code:'ENOENT'});checks.cancel='PASS'
+    const short=await start(5000)
+    let expired=short
+    for(let i=0;i<90&&expired.state==='recording';i++){
+      await new Promise(r=>setTimeout(r,500));expired=await call('get_system_trace_status',{traceId:short.trace_id})
+    }
+    if(expired.artifact)artifacts.push(expired.artifact.path)
+    assert.equal(expired.state,'completed',JSON.stringify(expired));assert.equal(expired.completion_reason,'duration_limit');assert.equal(expired.cleanup.status,'complete');owned.delete(short.trace_id);checks.expiry='PASS'
+    const failedRecording=await start(60000)
+    const failedJourney=await call('run_journey',{...target,systemTraceId:failedRecording.trace_id,steps:[{id:'missing',type:'assert',timeoutMs:1000,assertion:{kind:'element_visible',selector:{text:'impossible-trace-fixture-label'}}}]})
+    assert.equal(failedJourney.success,false)
+    assert.equal((await call('get_system_trace_status',{traceId:failedRecording.trace_id})).state,'recording')
+    await stop(failedRecording.trace_id);checks.failed_journey='PASS; failure retained capture for explicit stop'
+    await verifyIosTraceShutdown(traceTarget,inputEnvironment());checks.shutdown='PASS; owned recording and partial directory removed'
+    const live=command(['simctl','spawn',deviceId,'launchctl','list'])
+    assert.ok(live.includes(`UIKitApplication:${readinessAppId}[`),'Recorder cleanup must leave the fixture app running')
+    checks.app_survived_cleanup='PASS'
+    const hash=createHash('sha256')
+    for(const file of ['dist/server.js','dist/observe/system-trace.js','dist/observe/system-trace-router.js','dist/observe/ios-trace/native.js','dist/observe/ios-trace/sessions.js','dist/observe/ios-trace/process.js'])hash.update(await fs.readFile(file))
+    checks.status=journeyFailure?'FAIL':'PASS';checks.build_sha256=hash.digest('hex');checks.runtime=process.version;checks.device=deviceId;checks.server=client.getServerVersion()
+    checks.physical_device='UNRUN; unsupported initial matrix';checks.native_failure_injection='UNRUN on real target; deterministic unit tests separate'
+    checks.input_toolchain=process.env.IDB_COMPANION?'Explicit test companion via IDB_COMPANION; see investigation.md':'Repository default idb companion'
+    if(journeyFailure) throw journeyFailure
+  }catch(error){checks.status='FAIL';checks.error=String(error);throw error}finally{
+    const errors:string[]=[]
+    for(const id of owned)try{const r=await call('cancel_system_trace',{traceId:id});if(r.artifact&&!artifacts.includes(r.artifact.path))artifacts.push(r.artifact.path);if(r.cleanup?.status!=='complete')errors.push(id)}catch{errors.push(id)}
+    await client.close()
+    for(const file of artifacts)await fs.rm(path.dirname(file),{recursive:true,force:true})
+    if(installed)command(['simctl','uninstall',deviceId,readinessAppId])
+    if(fixture)await fs.rm(fixture.directory,{recursive:true,force:true})
+    if(booted)command(['simctl','shutdown',deviceId])
+    checks.cleanup={trace_errors:errors,fixture_removed:installed,simulator_shutdown:booted,host_artifacts_removed:true}
+    console.log(JSON.stringify(checks))
+    if(process.env.IOS_SYSTEM_TRACE_EVIDENCE_PATH)await fs.writeFile(process.env.IOS_SYSTEM_TRACE_EVIDENCE_PATH,JSON.stringify(checks,null,2)+'\n')
+    assert.deepEqual(errors,[],'Trace cleanup failed')
+  }
+}
+run().catch(error=>{console.error(error);process.exitCode=1})

package/test/device/automated/observe/system-trace.smoke.ts

@@ -82,7 +82,7 @@ async function run() {
     const absent = await execCmd(getAdbCmd(), ['-s', device.id, 'shell', 'test', '!', '-e', remote], { timeout: 10000 })
     assert.equal(absent.exitCode, 0, `Shutdown must stop and remove its owned device capture: ${shutdownTrace.trace_id}; ${shutdownDiagnostics}; ${absent.stderr}`)
     const buildHash = createHash('sha256')
-    for (const file of ['dist/server.js', 'dist/observe/system-trace.js', 'dist/observe/system-trace-android.js', 'dist/server/tool-handlers.js', 'dist/observe/evidence.js']) buildHash.update(await fs.readFile(file))
+    for (const file of ['dist/server.js', 'dist/observe/system-trace.js', 'dist/observe/system-trace-android.js', 'dist/server/handlers/tool-handlers.js', 'dist/observe/evidence.js']) buildHash.update(await fs.readFile(file))
     const report = { status: 'PASS', build_sha256: buildHash.digest('hex'), runtime: process.version, server: client.getServerVersion(), device: device.id, osVersion: device.osVersion,
       starting_state: 'System Settings fixture', journey: 'start Settings, assert baseline Settings-owned resource visible in UI tree; explicit trace association',
       trace_id: start.trace_id, correlation_id: journey.evidence.correlation_id, phases: {

package/test/device/manual/interact/modul8_selector_tap.manual.ts

@@ -11,7 +11,7 @@ async function run() {
   const transport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
   const target = { platform: 'android', deviceId: 'emulator-5554' }
   const report: any = { verified_on: new Date().toISOString(), device: target, package: 'com.ideamechanics.modul8.dev',
-    source: 'rebuilt local MCP stdio server', build_sha256: createHash('sha256').update(readFileSync('dist/server/tool-handlers.js')).digest('hex'),
+    source: 'rebuilt local MCP stdio server', build_sha256: createHash('sha256').update(readFileSync('dist/server/handlers/tool-handlers.js')).digest('hex'),
     steps: [], status: 'UNRUN', cleanup: 'UNRUN' }
   const call = async (name: string, args: Record<string, unknown>) => {
     const response: any = await client.callTool({ name, arguments: { ...target, ...args } }, undefined, { timeout: 120000 })