mobile-debug-mcp 0.33.0 → 0.35.0

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

@@ -0,0 +1,219 @@
+import { debuggerResponse } from '../../../../src/server/handlers/debugger-response.js'
+import { debuggerContracts } from '../../../../src/server/schemas/debugger-schema.js'
+import assert from 'node:assert/strict'
+import { execFileSync, spawn } from 'node:child_process'
+import { readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { createHash } from 'node:crypto'
+import { buildDebuggerFixture, debuggerAppId } from '../../../fixtures/debugger-app/build.js'
+
+// Explicit opt-in: installs/removes only this isolated fixture on the selected device.
+if (!process.env.MCP_DEBUGGER_DEVICE) {
+  console.log('UNRUN Android debugger fixture: set MCP_DEBUGGER_DEVICE to an authorized emulator serial')
+} else {
+  const deviceId = process.env.MCP_DEBUGGER_DEVICE
+  const adb = (...args: string[]) => execFileSync(process.env.ADB_PATH || 'adb', ['-s', deviceId, ...args], { encoding: 'utf8', timeout: 15000 })
+  const client = new Client({ name: 'android-debugger-smoke', version: '1.0.0' })
+  const transport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
+  const compactMode = process.env.MCP_DEBUGGER_RESPONSE_MODE === 'compact'
+  const measurements: { tool: string; debug_bytes: number; compact_bytes: number }[] = []
+  const call = async (name: string, args: Record<string, unknown>) => {
+    const response = await client.callTool({ name, arguments: { ...args, ...(debuggerContracts[name] && compactMode ? { responseMode: 'compact' } : {}) } }, undefined, { timeout: 45000 })
+    const text = (response.content as any[]).find(c => c.type === 'text')!.text!
+    const payload = JSON.parse(text)
+    if (debuggerContracts[name]) {
+      const command = debuggerContracts[name].command
+      if (compactMode && !['attach', 'state', 'capabilities'].includes(command) && payload.debug_session_id != null) {
+        for (const field of ['device', 'target', 'capabilities']) assert.ok(!Object.hasOwn(payload, field))
+      }
+      if (!compactMode) {
+        const compact = debuggerResponse(command, 'compact', payload)
+        measurements.push({ tool: name, debug_bytes: Buffer.byteLength(JSON.stringify(response)), compact_bytes: Buffer.byteLength(JSON.stringify({ ...response, content: [{ type: 'text', text: JSON.stringify(compact, null, 2) }] })) })
+      }
+    }
+    return payload
+  }
+  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 hash.update(file).update(await readFile(file))
+    }
+  }
+  await fingerprint('dist'); await fingerprint('src/debugger/java')
+  const buildHash = hash.digest('hex')
+  const fixture = buildDebuggerFixture()
+  const source = await readFile(new URL('../../../fixtures/debugger-app/MainActivity.java', import.meta.url), 'utf8')
+  const line = (marker: string) => source.split('\n').findIndex(l => l.includes(marker)) + 1
+  let debugSessionId = ''
+  let cursor = 0
+  const eventsUntilStop = async () => {
+    for (let i = 0; i < 10; i++) {
+      const result = await call('wait_for_debugger_event', { debugSessionId, afterSequence: cursor, timeoutMs: 1000 })
+      cursor = result.next_cursor
+      if (result.events.length) console.log('Debug events', JSON.stringify(result.events))
+      const event = result.events.find((e: any) => e.event === 'stopped')
+      if (event) return event
+    }
+    throw new Error('No debugger stop observed')
+  }
+  const forwardsBefore = adb('forward', '--list').trim()
+  try {
+    await client.connect(transport)
+    const listed = await client.listTools()
+    assert.ok(listed.tools.some(tool => tool.name === 'attach_debugger'))
+    adb('install', '-r', fixture.artifact)
+    adb('shell', 'am', 'start', '-W', '-n', `${debuggerAppId}/.MainActivity`)
+    const cap = await call('get_debugger_capabilities', { platform: 'android', deviceId, appId: debuggerAppId })
+    assert.equal(cap.supported, true, JSON.stringify(cap))
+    const timeout = await call('get_debugger_capabilities', { platform: 'android', deviceId, appId: debuggerAppId, timeoutMs: 100 })
+    assert.equal(timeout.error.code, 'DEBUGGER_TIMEOUT')
+    const unsupported = await call('get_debugger_capabilities', { platform: 'android', deviceId, appId: 'com.missing.debugfixture' })
+    assert.equal(unsupported.supported, false)
+    assert.ok(unsupported.reasons.includes('PROCESS_NOT_FOUND'))
+    const attached = await call('attach_debugger', { platform: 'android', deviceId, appId: debuggerAppId, timeoutMs: 30000 })
+    assert.equal(attached.success, true, JSON.stringify(attached)); debugSessionId = attached.debug_session_id
+    const bp = await call('set_debugger_breakpoint', { debugSessionId, className: `${debuggerAppId}.MainActivity`, line: line('BREAK_CALCULATE') })
+    assert.equal(bp.result.status, 'verified', JSON.stringify(bp))
+    const pending = await call('set_debugger_breakpoint', { debugSessionId, className: `${debuggerAppId}.LateWork`, line: line('BREAK_LATE') })
+    assert.equal(pending.result.status, 'pending', JSON.stringify(pending))
+    const unavailable = await call('set_debugger_breakpoint', { debugSessionId, className: `${debuggerAppId}.MainActivity`, line: 9999 })
+    assert.equal(unavailable.result.status, 'rejected')
+    // Fixture button placement is obtained from real UI semantics, not fixed coordinates.
+    const tree = await call('get_ui_tree', { platform: 'android', deviceId })
+    const button = tree.elements.find((e: any) => /^calculate$/i.test(e.text ?? ''))
+    assert.ok(button, 'Calculate button visible in real UI tree: ' + JSON.stringify(tree))
+    console.log('Fixture target', JSON.stringify({ bounds: button.bounds, device: tree.device, resolution: tree.resolution }))
+    const [left, top, right, bottom] = button.bounds
+    // Shell input is asynchronous so suspension cannot block the test's next debugger call.
+    await writeFile(fixture.directory + '/fixture.png', execFileSync(process.env.ADB_PATH || 'adb', ['-s', deviceId, 'exec-out', 'screencap', '-p']))
+    const tap = spawn(process.env.ADB_PATH || 'adb', ['-s', deviceId, 'shell', 'input', 'tap', String(Math.floor((left + right) / 2)), String(Math.floor((top + bottom) / 2))], { stdio: 'ignore' })
+    tap.on('error', error => { throw error })
+    const stop = await eventsUntilStop()
+    assert.equal(stop.stops[0].location.line, line('BREAK_CALCULATE'))
+    const stack = await call('get_debugger_stack', { debugSessionId, stopId: stop.stop_id, threadId: stop.thread_id })
+    assert.equal(stack.result.frames[0].location.method, 'calculate')
+    const frameId = stack.result.frames[0].frame_id
+    const locals = await call('get_debugger_locals', { debugSessionId, stopId: stop.stop_id, frameId })
+    assert.equal(locals.result.locals.find((v: any) => v.name === 'known')?.value, '42', JSON.stringify(locals))
+    const longText = locals.result.locals.find((v: any) => v.name === 'longText')
+    assert.equal(longText.value.length, 256); assert.equal(longText.truncated, true)
+    const object = locals.result.locals.find((v: any) => v.name === 'object')
+    assert.equal(object.value.type, 'java.lang.Object'); assert.equal(typeof object.value.object_id, 'string')
+    const readiness = await call('get_app_readiness', { platform: 'android', deviceId })
+    assert.equal(readiness.readiness.state, 'debugger_paused')
+    for (const name of ['tap', 'wait_for_ui', 'terminate_app', 'run_journey']) {
+      const blocked = await call(name, { platform: 'android', deviceId, x: 5, y: 5, appId: debuggerAppId })
+      assert.equal(blocked.failure_code, 'DEBUGGER_PAUSED', name)
+      assert.equal(blocked.dispatch_started, false)
+    }
+    await call('remove_debugger_breakpoint', { debugSessionId, breakpointId: bp.result.breakpoint_id })
+    const step = await call('step_debugger', { debugSessionId, stopId: stop.stop_id, threadId: stop.thread_id, kind: 'into' })
+    assert.equal(step.success, true, JSON.stringify(step))
+    const stale = await call('get_debugger_locals', { debugSessionId, stopId: stop.stop_id, frameId })
+    assert.equal(stale.error.code, 'DEBUGGER_STALE_REFERENCE')
+    const into = await eventsUntilStop()
+    assert.equal(into.stops[0].location.method, 'increment')
+    assert.equal((await call('step_debugger', { debugSessionId, stopId: into.stop_id, threadId: into.thread_id, kind: 'over' })).success, true)
+    const over = await eventsUntilStop()
+    assert.equal(over.stops[0].location.method, 'increment')
+    assert.equal((await call('step_debugger', { debugSessionId, stopId: over.stop_id, threadId: over.thread_id, kind: 'out' })).success, true)
+    const out = await eventsUntilStop()
+    assert.equal(out.stops[0].location.method, 'calculate')
+    assert.equal((await call('resume_debugger', { debugSessionId, stopId: out.stop_id })).success, true)
+    let resultVisible = false
+    for (let i = 0; i < 10; i++) {
+      const observed = await call('get_ui_tree', { platform: 'android', deviceId })
+      if (observed.elements.some((e: any) => e.text === 'Result 43')) { resultVisible = true; break }
+    }
+    assert.ok(resultVisible, 'UI tree independently establishes resumed execution: Result 43')
+    const noLocalsSource = await readFile(new URL('../../../fixtures/debugger-app/NoLocals.java', import.meta.url), 'utf8')
+    const noLocalsLine = noLocalsSource.split('\n').findIndex(line => line.includes('BREAK_NO_LOCALS')) + 1
+    const removedPending = await call('set_debugger_breakpoint', { debugSessionId, className: `${debuggerAppId}.NoLocals`, line: noLocalsLine })
+    await call('remove_debugger_breakpoint', { debugSessionId, breakpointId: removedPending.result.breakpoint_id })
+    await call('set_debugger_breakpoint', { debugSessionId, className: `${debuggerAppId}.NoLocals`, line: noLocalsLine })
+    const metadataTree = await call('get_ui_tree', { platform: 'android', deviceId })
+    const mb = metadataTree.elements.find((e: any) => /^no locals$/i.test(e.text ?? '')).bounds
+    spawn(process.env.ADB_PATH || 'adb', ['-s', deviceId, 'shell', 'input', 'tap', String(Math.floor((mb[0] + mb[2]) / 2)), String(Math.floor((mb[1] + mb[3]) / 2))], { stdio: 'ignore' })
+    const metadataStop = await eventsUntilStop()
+    assert.ok(metadataStop.stops.every((stop: any) => stop.breakpoint_id !== removedPending.result.breakpoint_id), 'removed pending breakpoint never rebinds')
+    const metadataStack = await call('get_debugger_stack', { debugSessionId, stopId: metadataStop.stop_id, threadId: metadataStop.thread_id })
+    const metadataLocals = await call('get_debugger_locals', { debugSessionId, stopId: metadataStop.stop_id, frameId: metadataStack.result.frames[0].frame_id })
+    assert.equal(metadataLocals.result.availability, 'unknown')
+    assert.equal(metadataLocals.result.reason, 'EMPTY_OR_UNAVAILABLE_VARIABLE_METADATA')
+    await call('resume_debugger', { debugSessionId, stopId: metadataStop.stop_id })
+    const lateTree = await call('get_ui_tree', { platform: 'android', deviceId })
+    const lateButton = lateTree.elements.find((e: any) => /^late class$/i.test(e.text ?? ''))
+    assert.ok(lateButton)
+    const bounds = lateButton.bounds
+    spawn(process.env.ADB_PATH || 'adb', ['-s', deviceId, 'shell', 'input', 'tap', String(Math.floor((bounds[0] + bounds[2]) / 2)), String(Math.floor((bounds[1] + bounds[3]) / 2))], { stdio: 'ignore' })
+    const lateStop = await eventsUntilStop()
+    assert.equal(lateStop.stops[0].location.class_name, `${debuggerAppId}.LateWork`)
+    assert.equal(lateStop.stops[0].location.line, line('BREAK_LATE'))
+    const aborted = new AbortController()
+    const cancelled = client.callTool({ name: 'wait_for_debugger_event', arguments: { debugSessionId, afterSequence: cursor, timeoutMs: 1000 } }, undefined, { signal: aborted.signal, timeout: 5000 })
+    const cancelTimer = setTimeout(() => aborted.abort(), 100)
+    try { await assert.rejects(cancelled) } finally { clearTimeout(cancelTimer) }
+    assert.equal((await call('get_debugger_state', { debugSessionId })).state, 'paused')
+    if (process.env.MCP_DEBUGGER_EXTENDED === '1') {
+      console.log('Checking real 60-second pause expiry while polling state')
+      const deadline = Date.now() + 65000
+      let state: any
+      do {
+        await new Promise(resolve => setTimeout(resolve, 1000))
+        state = await call('get_debugger_state', { debugSessionId })
+      } while (state.state === 'paused' && Date.now() < deadline)
+      assert.equal(state.state, 'detached', JSON.stringify(state))
+      assert.equal(state.reason, 'pause_limit')
+      assert.equal(state.cleanup.status, 'complete')
+      console.log('PASS real pause expiry despite active client polling')
+    }
+    const detach = await call('detach_debugger', { debugSessionId })
+    assert.equal(detach.cleanup.status, 'complete', JSON.stringify(detach))
+    assert.equal((await call('detach_debugger', { debugSessionId })).cleanup.status, 'complete')
+    assert.equal(adb('forward', '--list').trim(), forwardsBefore, 'unrelated forwards preserved')
+    const reattached = await call('attach_debugger', { platform: 'android', deviceId, appId: debuggerAppId, timeoutMs: 30000 })
+    assert.equal(reattached.success, true, JSON.stringify(reattached))
+    debugSessionId = reattached.debug_session_id
+    adb('shell', 'am', 'force-stop', debuggerAppId)
+    let disconnected: any
+    for (let i = 0; i < 20; i++) {
+      disconnected = await call('get_debugger_state', { debugSessionId })
+      if (disconnected.cleanup.status === 'complete') break
+      await new Promise(resolve => setTimeout(resolve, 100))
+    }
+    assert.equal(disconnected.state, 'disconnected', JSON.stringify(disconnected))
+    assert.equal(disconnected.cleanup.status, 'complete')
+    assert.equal(adb('forward', '--list').trim(), forwardsBefore)
+    // Disconnect the MCP client with an actively paused session; shutdown owns resume/dispose.
+    adb('shell', 'am', 'start', '-W', '-n', `${debuggerAppId}/.MainActivity`)
+    const shutdownSession = await call('attach_debugger', { platform: 'android', deviceId, appId: debuggerAppId, timeoutMs: 30000 })
+    assert.equal(shutdownSession.success, true, JSON.stringify(shutdownSession))
+    debugSessionId = shutdownSession.debug_session_id; cursor = 0
+    await call('set_debugger_breakpoint', { debugSessionId, className: `${debuggerAppId}.MainActivity`, line: line('BREAK_CALCULATE') })
+    const shutdownTree = await call('get_ui_tree', { platform: 'android', deviceId })
+    const shutdownButton = shutdownTree.elements.find((e: any) => /^calculate$/i.test(e.text ?? ''))
+    const sb = shutdownButton.bounds
+    spawn(process.env.ADB_PATH || 'adb', ['-s', deviceId, 'shell', 'input', 'tap', String(Math.floor((sb[0] + sb[2]) / 2)), String(Math.floor((sb[1] + sb[3]) / 2))], { stdio: 'ignore' })
+    await eventsUntilStop()
+    await client.close(); debugSessionId = ''
+    assert.equal(adb('forward', '--list').trim(), forwardsBefore, 'MCP disconnect cleans active owned forward')
+    const verifier = new Client({ name: 'debugger-shutdown-verifier', version: '1.0.0' })
+    try {
+      await verifier.connect(new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' }))
+      const result = await verifier.callTool({ name: 'get_ui_tree', arguments: { platform: 'android', deviceId } })
+      const treeAfterShutdown = JSON.parse((result.content as any[]).find(c => c.type === 'text').text)
+      assert.ok(treeAfterShutdown.elements.some((e: any) => e.text === 'Result 43'), 'fresh UI proves paused fixture resumed after server shutdown')
+    } finally { await verifier.close() }
+    console.log(JSON.stringify({ status: 'PASS', build_sha256: buildHash, device: deviceId, api: adb('shell', 'getprop', 'ro.build.version.sdk').trim(), runtime: process.version, transport: 'MCP stdio', extended: process.env.MCP_DEBUGGER_EXTENDED === '1' }))
+    console.log('Debugger response measurement', JSON.stringify({ mode: compactMode ? 'compact' : 'debug', calls: measurements, debug_bytes: measurements.reduce((sum, row) => sum + row.debug_bytes, 0), compact_bytes: measurements.reduce((sum, row) => sum + row.compact_bytes, 0) }))
+    console.log('PASS Android debugger: explicit attach, source stop, stack/known locals, pause guards, into/over/out, stale frame, resume UI, detach/forward ownership')
+  } finally {
+    if (debugSessionId) await call('detach_debugger', { debugSessionId }).catch(() => {})
+    await client.close()
+    adb('uninstall', debuggerAppId)
+    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/system-trace.smoke.ts

@@ -0,0 +1,104 @@
+import { execCmd } from '../../../../src/utils/exec.js'
+import { getAdbCmd } from '../../../../src/utils/android/utils.js'
+import { createHash } from 'node:crypto'
+import assert from 'node:assert/strict'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { inspectPerfetto } from '../../../helpers/perfetto.js'
+
+async function run() {
+  if (process.env.SKIP_DEVICE_TESTS === '1') { console.log('System trace smoke: SKIPPED (SKIP_DEVICE_TESTS=1)'); return }
+  const client = new Client({ name: 'system-trace-smoke', version: '1.0.0' })
+  const transport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
+  const parse = (r: any) => JSON.parse(r.content[0].text)
+  const call = async (name: string, args: Record<string, unknown>) => parse(await client.callTool({ name, arguments: args }, undefined, { timeout: 120000 }))
+  const owned: string[] = [], artifacts: string[] = []
+  try {
+    await client.connect(transport)
+    const devices = await call('list_devices', {})
+    const device = devices.devices.find((d: any) => d.platform === 'android' && d.simulator)
+    assert.ok(device, 'A running Android emulator is required')
+    const target = { platform: 'android', deviceId: device.id }
+    const cap = await call('get_system_trace_capabilities', target)
+    assert.equal(cap.supported, true, JSON.stringify(cap))
+    const fixtureLaunch = await call('start_app', { ...target, appId: 'com.android.settings', verificationMode: 'none', responseMode: 'compact' })
+    assert.equal(fixtureLaunch.success, true)
+    const baseline = await call('get_ui_tree', { ...target, responseMode: 'debug' })
+    const settingsNode = baseline.elements?.find((e: any) => e.visible && e.resourceId?.startsWith('com.android.settings:id/'))
+    assert.ok(settingsNode, 'Fresh baseline must contain a visible Settings-owned UI resource')
+    const settingsSelector = { resource_id: settingsNode.resourceId }
+    const start = await call('start_system_trace', { ...target, durationMs: 30000 })
+    owned.push(start.trace_id)
+    assert.equal(start.state, 'recording', JSON.stringify(start))
+    const journey = await call('run_journey', { ...target, systemTraceId: start.trace_id,
+      steps: [
+        { id: 'settings', type: 'start_app', appId: 'com.android.settings', verificationMode: 'none' },
+        { id: 'settings-visible', type: 'assert', timeoutMs: 10000, assertion: { kind: 'element_visible', selector: settingsSelector } }
+      ] })
+    assert.equal(journey.success, true, JSON.stringify(journey))
+    assert.equal(journey.steps[1].status, 'passed', 'The baseline Settings-owned UI element must remain semantically visible')
+    assert.equal(journey.evidence.trace_context.trace_id, start.trace_id)
+    assert.equal(journey.steps[0].result.evidence.trace_context.trace_id, start.trace_id)
+    assert.equal(journey.system_trace.coverage, 'covered')
+    const stop = await call('stop_system_trace', { traceId: start.trace_id })
+    if (stop.artifact) artifacts.push(stop.artifact.path)
+    assert.equal(stop.state, 'completed', JSON.stringify(stop)); assert.equal(stop.cleanup.status, 'complete')
+    assert.deepEqual(stop.correlation_ids, [journey.evidence.correlation_id])
+    const content = inspectPerfetto(await fs.readFile(stop.artifact.path), 30000)
+    assert.equal((await call('stop_system_trace', { traceId: start.trace_id })).artifact.path, stop.artifact.path)
+    const rejected = await call('run_journey', { ...target, systemTraceId: start.trace_id,
+      steps: [{ id: 'must-not-launch', type: 'start_app', appId: 'com.invalid.trace.smoke' }] })
+    assert.equal(rejected.error.code, 'TRACE_NOT_FOUND')
+    const cancel = await call('start_system_trace', { ...target, durationMs: 30000 })
+    owned.push(cancel.trace_id)
+    const cancelled = await call('cancel_system_trace', { traceId: cancel.trace_id })
+    assert.equal(cancelled.state, 'cancelled', JSON.stringify(cancelled))
+    assert.equal((await call('get_system_trace_status', { traceId: cancel.trace_id })).artifact, null)
+    const short = await call('start_system_trace', { ...target, durationMs: 1001 })
+    owned.push(short.trace_id)
+    assert.equal(short.state, 'recording', JSON.stringify(short))
+    let ended = short
+    for (let i = 0; i < 30 && ended.state === 'recording'; i++) {
+      await new Promise(resolve => setTimeout(resolve, 200))
+      ended = await call('get_system_trace_status', { traceId: short.trace_id })
+    }
+    if (ended.artifact) artifacts.push(ended.artifact.path)
+    assert.equal(ended.state, 'completed', JSON.stringify(ended)); assert.equal(ended.completion_reason, 'duration_limit')
+    const durationContent = inspectPerfetto(await fs.readFile(ended.artifact.path), 1001)
+    const shutdownClient = new Client({ name: 'system-trace-shutdown-smoke', version: '1.0.0' })
+    const shutdownTransport = new StdioClientTransport({ command: process.execPath, args: ['dist/server.js'], stderr: 'pipe' })
+    let shutdownTrace: any
+    let shutdownDiagnostics = ''
+    try {
+      await shutdownClient.connect(shutdownTransport)
+      shutdownTransport.stderr?.on('data', data => { shutdownDiagnostics += String(data) })
+      shutdownTrace = parse(await shutdownClient.callTool({ name: 'start_system_trace', arguments: { ...target, durationMs: 30000 } }, undefined, { timeout: 120000 }))
+      assert.equal(shutdownTrace.state, 'recording')
+    } finally { await shutdownClient.close() }
+    const remote = shutdownTrace.cleanup.remaining_resources.find((r: string) => r.startsWith('/data/misc/perfetto-traces/mcp-'))
+    assert.ok(remote)
+    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/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: {
+        capture_started_at_ms: stop.capture_started_at_ms, capture_completed_at_ms: stop.capture_completed_at_ms },
+      artifact_bytes: stop.artifact.size_bytes, content, durationContent, cancel: 'PASS', expired_journey: 'PASS', active_shutdown: 'PASS',
+      cleanup: 'Device capture files removed; test host artifacts removed in finally. No settings or app data changed. Settings remains foreground.' }
+    console.log(JSON.stringify(report))
+    if (process.env.SYSTEM_TRACE_EVIDENCE_PATH) await fs.writeFile(process.env.SYSTEM_TRACE_EVIDENCE_PATH, JSON.stringify(report, null, 2) + '\n')
+  } finally {
+    const cleanupErrors: string[] = []
+    for (const traceId of owned) {
+      try { const r = await call('cancel_system_trace', { traceId }); if (r.artifact && !artifacts.includes(r.artifact.path)) artifacts.push(r.artifact.path); if (r.cleanup?.status !== 'complete') cleanupErrors.push(traceId) } catch { cleanupErrors.push(traceId) }
+    }
+    await client.close()
+    for (const file of artifacts) await fs.rm(path.dirname(file), { recursive: true, force: true })
+    assert.deepEqual(cleanupErrors, [], 'Owned trace cleanup failed')
+  }
+}
+run().catch(error => { console.error(error); process.exitCode = 1 })

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 })