mobile-debug-mcp 0.34.0 → 0.36.0

package/src/observe/ios/ui-tree.ts

@@ -0,0 +1,143 @@
+import { remainingBudget } from '../../utils/operation-budget.js'
+import { execCmd } from '../../utils/exec.js'
+import { createObservationMeasurement } from '../performance-metrics.js'
+import { GetUITreeResponse, UIElement } from "../../types.js"
+import { getIOSDeviceMetadata, getIdbCmd, isIDBInstalled } from "../../utils/ios/utils.js"
+import { deriveSnapshotMetadata } from '../snapshot-metadata.js'
+import { delay } from './context.js'
+import { traverseIDBNode } from './ui-elements.js'
+export async function collectGetUITree(deviceId: string = "booted"): Promise<GetUITreeResponse> {
+  const measurement = createObservationMeasurement('ios')
+  let device
+  try {
+    device = await measurement.timed('metadata_ms', () => getIOSDeviceMetadata(deviceId))
+  } catch (error) {
+    measurement.setOutcome('unavailable')
+    measurement.finish()
+    throw error
+  }
+  const deviceKey = `ios:${device.id}`
+
+  const idbExists = await measurement.timed('capability_check_ms', () => isIDBInstalled());
+  if (!idbExists) {
+    const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree')
+    measurement.setOutcome('unavailable')
+    measurement.finish()
+    return missingIDBResponse(device, snapshotMetadata)
+  }
+
+  const targetUdid = (device.id && device.id !== 'booted') ? device.id : undefined;
+
+  const acquisition = await readIOSTree(targetUdid, measurement)
+  if (!acquisition.success) {
+    const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree')
+    measurement.setOutcome('unavailable'); measurement.finish()
+    return {
+      device, screen: '', resolution: { width: 0, height: 0 }, elements: [], ...snapshotMetadata,
+      error: 'Failed to retrieve valid UI dump after 3 attempts.'
+    }
+  }
+
+  const jsonContent = acquisition.tree
+  try {
+    const elements: UIElement[] = await measurement.timed('conversion_ms', async () => {
+      const parsed: UIElement[] = []
+      if (Array.isArray(jsonContent)) {
+        for (const node of jsonContent) traverseIDBNode(node, parsed)
+      } else {
+        traverseIDBNode(jsonContent!, parsed)
+      }
+      return parsed
+    })
+
+    let width = 0;
+    let height = 0;
+    if (elements.length > 0) {
+      const rootBounds = elements[0].bounds;
+      width = rootBounds[2] - rootBounds[0];
+      height = rootBounds[3] - rootBounds[1];
+    }
+
+    const snapshotMetadata = deriveSnapshotMetadata(deviceKey, {
+      screen: "",
+      resolution: { width, height },
+      elements
+    }, 'ui_tree')
+
+    measurement.setOutcome('observed')
+    const response = measurement.bindObservation({
+      device,
+      screen: "",
+      resolution: { width, height },
+      elements,
+      ...snapshotMetadata
+    })
+    measurement.finish()
+    return response
+  } catch (e) {
+    const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree')
+    measurement.setOutcome('unavailable')
+    measurement.finish()
+    return {
+      device,
+      screen: "",
+      resolution: { width: 0, height: 0 },
+      elements: [],
+      ...snapshotMetadata,
+      error: `Failed to parse idb output: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+}
+
+async function readIOSTree(targetUdid: string | undefined, measurement: ReturnType<typeof createObservationMeasurement>) {
+  let jsonContent: import('./ui-elements.js').IDBElement | import('./ui-elements.js').IDBElement[] | null = null;
+  let attempts = 0;
+  const maxAttempts = 3;
+
+  while (attempts < maxAttempts) {
+    remainingBudget()
+    attempts++;
+    try {
+      await measurement.timed('observation_wait_ms', () => delay(Math.min(remainingBudget(300 + (attempts * 100)), 300 + (attempts * 100))));
+      remainingBudget()
+
+      const args = ['ui', 'describe-all', '--json'];
+      if (targetUdid) {
+        args.push('--udid', targetUdid);
+      }
+
+      const output = await measurement.physicalRead(async () => {
+        const result = await execCmd(getIdbCmd(), args, { timeout: remainingBudget() })
+        if (result.stderr === 'ACTION_TIMEOUT') throw new Error('ACTION_TIMEOUT')
+        if (result.exitCode !== 0) throw new Error(`idb failed (code ${result.exitCode}): ${result.stderr}`)
+        if (!result.stdout.trim()) throw new Error('Empty idb UI tree output')
+        return result.stdout
+      })
+
+      if (output && output.trim().length > 0) {
+        jsonContent = await measurement.timed('parse_ms', async () => JSON.parse(output));
+        break; // Success
+      }
+    } catch (e) {
+      if (e instanceof Error && e.message === 'ACTION_TIMEOUT') throw e
+      console.error(`Attempt ${attempts} failed: ${e}`);
+    }
+
+    if (attempts === maxAttempts) {
+      return { success: false, tree: null };
+    }
+  }
+
+  return { success: true, tree: jsonContent }
+}
+
+function missingIDBResponse(device: GetUITreeResponse['device'], snapshotMetadata: ReturnType<typeof deriveSnapshotMetadata>): GetUITreeResponse {
+  return {
+    device,
+    screen: "",
+    resolution: { width: 0, height: 0 },
+    elements: [],
+    ...snapshotMetadata,
+    error: "iOS UI tree retrieval requires 'idb' (iOS Device Bridge). Please install it via Homebrew: `brew tap facebook/fb && brew install idb-companion` and `pip3 install fb-idb`."
+  };
+}

package/src/observe/ios-trace/artifact.ts

@@ -0,0 +1,55 @@
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { XMLParser, XMLValidator } from 'fast-xml-parser'
+import { getXcrunCmd } from '../../utils/ios/utils.js'
+import { traceCommand, spawnTrace, type TraceSpawn } from './process.js'
+import type { IosApp } from './capabilities.js'
+
+export const IOS_TRACE_MAX_BYTES = 256 * 1024 * 1024
+export async function traceSize(root: string, secure = false): Promise<number> {
+  const stat = await fs.lstat(root)
+  if (stat.isSymbolicLink() || (!stat.isFile() && !stat.isDirectory())) throw new Error('UNSAFE_ARTIFACT')
+  if (secure) await fs.chmod(root, stat.isDirectory() ? 0o700 : 0o600)
+  if (stat.isFile()) return stat.size
+  let size = 0
+  for (const name of await fs.readdir(root)) {
+    size += await traceSize(path.join(root, name), secure)
+    if (size > IOS_TRACE_MAX_BYTES) throw new Error('STORAGE_LIMIT')
+  }
+  return size
+}
+interface TocProcess { '@_pid'?: string; '@_path'?: string }
+interface TocRun {
+  processes?: { process?: TocProcess | TocProcess[] }
+  info?: { target?: { device?: { '@_uuid'?: string }; process?: { '@_pid'?: string; '@_name'?: string } }; summary?: { 'template-name'?: string } }
+  data?: { table?: { '@_schema'?: string }[] | { '@_schema'?: string } }
+}
+export function validateToc(xml: string, device: string, app: IosApp) {
+  if (XMLValidator.validate(xml) !== true) throw new Error('INVALID_TOC')
+  const parsed = new XMLParser({ ignoreAttributes: false }).parse(xml) as { 'trace-toc'?: { run?: TocRun | TocRun[] } }
+  const raw = parsed['trace-toc']?.run
+  if (!raw || Array.isArray(raw)) throw new Error('INVALID_TOC')
+  const target = raw.info?.target
+  if (target?.device?.['@_uuid'] !== device || Number(target.process?.['@_pid']) !== app.pid || raw.info?.summary?.['template-name'] !== 'Time Profiler') throw new Error('ARTIFACT_TARGET_MISMATCH')
+  const processes = raw.processes?.process
+  if (!(Array.isArray(processes) ? processes : [processes]).some(p => Number(p?.['@_pid']) === app.pid && p?.['@_path'] === app.executable)) throw new Error('ARTIFACT_APP_MISMATCH')
+  const tables = raw.data?.table
+  if (!(Array.isArray(tables) ? tables : [tables]).some(t => t?.['@_schema'] === 'time-sample')) throw new Error('SAMPLE_SCHEMA_MISSING')
+}
+export async function validateArtifact(file: string, device: string, app: IosApp, spawn: TraceSpawn = spawnTrace) {
+  const size = await traceSize(file, true)
+  if (size <= 0 || size > IOS_TRACE_MAX_BYTES) throw new Error('STORAGE_LIMIT')
+  const toc = path.join(path.dirname(file), 'toc.xml'), samples = path.join(path.dirname(file), 'samples.xml')
+  try {
+    await traceCommand(getXcrunCmd(), ['xctrace', 'export', '--input', file, '--toc', '--output', toc], 15000, spawn)
+    if ((await fs.stat(toc)).size > 1024 * 1024) throw new Error('INVALID_TOC')
+    validateToc(await fs.readFile(toc, 'utf8'), device, app)
+    await traceCommand(getXcrunCmd(), ['xctrace', 'export', '--input', file, '--xpath', '/trace-toc/run[@number="1"]/data/table[@schema="time-sample"]', '--output', samples], 15000, spawn)
+    if ((await fs.stat(samples)).size > IOS_TRACE_MAX_BYTES) throw new Error('STORAGE_LIMIT')
+    const xml = await fs.readFile(samples, 'utf8')
+    if (XMLValidator.validate(xml) !== true || !xml.includes('<trace-query-result>')) throw new Error('INVALID_SAMPLES')
+    const sample_rows = (xml.match(/<row(?:\s|>)/g) ?? []).length
+    return { path: file, format: 'instruments' as const, kind: (await fs.stat(file)).isDirectory() ? 'directory' as const : 'file' as const,
+      size_bytes: size, validation: { readable: true, schema: 'time-sample', sample_rows } }
+  } finally { await Promise.all([toc, samples].map(p => fs.rm(p, { force: true }))) }
+}

package/src/observe/ios-trace/capabilities.ts

@@ -0,0 +1,74 @@
+import { promises as fs } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { getXcrunCmd } from '../../utils/ios/utils.js'
+import { traceCommand, type TraceSpawn, spawnTrace } from './process.js'
+import { prepareNotification } from './notification.js'
+
+export const IOS_TEMPLATES = ['System Trace', 'Time Profiler', 'Animation Hitches', 'Hangs'] as const
+export type IosTemplate = typeof IOS_TEMPLATES[number]
+export interface IosTarget { id: string; platform: 'ios'; simulator: boolean; osVersion: string; model: string }
+export interface IosApp { app_id: string; pid: number; executable: string; started_at: string }
+export interface IosCapabilities {
+  supported: boolean; backend: 'xctrace'; device: IosTarget | null; xcode_version: string | null
+  prerequisites: Record<string, 'available' | 'missing' | 'unknown'>; reasons: string[]; recovery: string[]
+  discovered_templates: string[]; templates: { name: IosTemplate; supported: boolean; coverage: string; reason: string | null }[]
+  app: IosApp | null; limitations: string[]
+}
+interface Simulators { devices: Record<string, { udid: string; state: string; name: string; isAvailable: boolean }[]> }
+export async function resolveIosApp(device: string, appId: string, spawn: TraceSpawn = spawnTrace): Promise<IosApp> {
+  const run = (args: string[]) => traceCommand(getXcrunCmd(), args, 10000, spawn)
+  const container = await run(['simctl', 'get_app_container', device, appId, 'app'])
+  if (!path.isAbsolute(container) || !container.endsWith('.app')) throw new Error('APP_IDENTITY_UNAVAILABLE')
+  const output = await run(['simctl', 'spawn', device, 'launchctl', 'list'])
+  const ids = output.split('\n').filter(line => line.includes(`UIKitApplication:${appId}[`))
+    .map(line => Number(line.trim().split(/\s+/)[0])).filter(pid => Number.isSafeInteger(pid) && pid > 1)
+  if (ids.length !== 1) throw new Error('APP_NOT_RUNNING')
+  const executable = await traceCommand('/bin/ps', ['-p', String(ids[0]), '-o', 'comm='], 10000, spawn)
+  if (!executable.startsWith(container + '/') || executable.includes('\n')) throw new Error('APP_IDENTITY_UNAVAILABLE')
+  const started_at = await traceCommand('/bin/ps', ['-p', String(ids[0]), '-o', 'lstart='], 10000, spawn)
+  if (!started_at || started_at.includes('\n')) throw new Error('APP_IDENTITY_UNAVAILABLE')
+  return { app_id: appId, pid: ids[0], executable, started_at }
+}
+export async function iosCapabilities(device: string, appId?: string, template: IosTemplate = 'Time Profiler', spawn: TraceSpawn = spawnTrace, host: string = process.platform): Promise<IosCapabilities> {
+  const result: IosCapabilities = {
+    supported: false, backend: 'xctrace', device: null, xcode_version: null,
+    prerequisites: { host: host === 'darwin' ? 'available' : 'missing', permissions: 'unknown', symbols: 'unknown' },
+    reasons: [], recovery: [], discovered_templates: [], templates: [], app: null,
+    limitations: ['App attachment may include sensitive system metadata, paths, logs and signposts.', 'Permissions and symbolication are not established by discovery.', 'Physical iOS capture is not supported in the initial matrix.']
+  }
+  if (host !== 'darwin') { result.reasons.push('MACOS_REQUIRED'); return result }
+  const probe = async (key: string, fn: () => Promise<void>, recovery: string) => {
+    try { await fn(); result.prerequisites[key] = 'available' }
+    catch (error) { result.prerequisites[key] = 'missing'; result.reasons.push(error instanceof Error && ['APP_NOT_RUNNING', 'APP_IDENTITY_UNAVAILABLE'].includes(error.message) ? error.message : key.toUpperCase() + '_UNAVAILABLE'); result.recovery.push(recovery) }
+  }
+  await probe('xcode', async () => { result.xcode_version = await traceCommand(getXcrunCmd(), ['xcodebuild', '-version'], 10000, spawn) }, 'Select a full Xcode installation with xcode-select.')
+  await probe('templates', async () => {
+    const output = await traceCommand(getXcrunCmd(), ['xctrace', 'list', 'templates'], 10000, spawn)
+    result.discovered_templates = output.split('\n').map(s => s.trim()).filter(s => s && !s.startsWith('=='))
+  }, 'Install/select Xcode with Instruments and run xcrun xctrace list templates.')
+  await probe('instruments_targets', async () => {
+    const targets = await traceCommand(getXcrunCmd(), ['xctrace', 'list', 'devices'], 15000, spawn)
+    if (!targets.includes(`(${device})`)) throw new Error('TARGET_UNAVAILABLE')
+  }, 'Check xcrun xctrace list devices; use a simulator visible to Instruments.')
+  await probe('target', async () => {
+    const data = JSON.parse(await traceCommand(getXcrunCmd(), ['simctl', 'list', 'devices', '--json'], 10000, spawn)) as Simulators
+    const entries = Object.entries(data.devices).flatMap(([runtime, values]) => values.map(value => ({ ...value, runtime })))
+    const target = entries.find(d => d.udid === device)
+    if (!target || !target.isAvailable || target.state !== 'Booted') throw new Error('TARGET_UNAVAILABLE')
+    result.device = { platform: 'ios', id: target.udid, simulator: true, model: target.name, osVersion: target.runtime.split('iOS-')[1]?.replaceAll('-', '.') ?? target.runtime }
+  }, 'Use an explicit booted simulator UDID. Physical devices and the Mac host are unsupported.')
+  await probe('notification_helper', async () => {
+    const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'mcp-trace-probe-'))
+    try { await prepareNotification(directory, spawn) } finally { await fs.rm(directory, { recursive: true, force: true }) }
+  }, 'Allow Xcode clang to compile the local Darwin-notification listener.')
+  if (appId && result.device) await probe('app', async () => { result.app = await resolveIosApp(device, appId, spawn) }, 'Start the requested development app on the selected simulator before tracing.')
+  result.templates = IOS_TEMPLATES.map(name => ({ name,
+    supported: name === 'Time Profiler' && result.discovered_templates.includes(name) && result.device !== null,
+    coverage: name === 'Time Profiler' ? 'CPU samples; bundled Hangs instrument is not independently verified' : name === 'System Trace' ? 'Scheduling coverage unverified' : name === 'Hangs' ? 'Not a standalone template here' : 'Unsupported on tested simulator',
+    reason: name === 'Time Profiler' ? null : 'TEMPLATE_TARGET_UNSUPPORTED'
+  }))
+  if (!result.templates.find(t => t.name === template)?.supported) result.reasons.push('TEMPLATE_TARGET_UNSUPPORTED')
+  result.supported = result.reasons.length === 0
+  return result
+}

package/src/observe/ios-trace/native.ts

@@ -0,0 +1,72 @@
+import { promises as fs } from 'node:fs'
+import { randomUUID } from 'node:crypto'
+import path from 'node:path'
+import { getXcrunCmd } from '../../utils/ios/utils.js'
+import { iosCapabilities, resolveIosApp, type IosApp, type IosTemplate } from './capabilities.js'
+import { prepareNotification, listenNotification } from './notification.js'
+import { spawnTrace, stopTraceChild, classifyTraceFailure, type TraceSpawn, type OwnedTraceChild } from './process.js'
+import { traceSize, validateArtifact, IOS_TRACE_MAX_BYTES } from './artifact.js'
+
+export interface IosRecording { recorder: OwnedTraceChild; file: string; ready_at_ms: number }
+export class IosTraceNative {
+  private spawn: TraceSpawn
+  private children = new Set<OwnedTraceChild>()
+  private recorders = new Set<OwnedTraceChild>()
+  private closing = false
+  constructor(spawn: TraceSpawn = spawnTrace) {
+    this.spawn = (command, args, timeout) => {
+      if (this.closing) throw new Error('TRACE_BUSY')
+      const child = spawn(command, args, timeout)
+      this.children.add(child)
+      if (args.includes('xctrace') && args.includes('record')) this.recorders.add(child)
+      void child.done.then(() => { this.children.delete(child); this.recorders.delete(child) })
+      return child
+    }
+  }
+  shutdown() {
+    this.closing = true
+    for (const child of this.children) child.signal('SIGINT')
+    const helpers = setTimeout(() => { for (const child of this.children) if (!this.recorders.has(child)) child.signal('SIGKILL') }, 1000)
+    const recorders = setTimeout(() => { for (const child of this.recorders) child.signal('SIGKILL') }, 8000)
+    helpers.unref(); recorders.unref()
+  }
+  capabilities(device: string, appId?: string, template?: IosTemplate) { return iosCapabilities(device, appId, template, this.spawn) }
+  resolve(device: string, app: string) { return resolveIosApp(device, app, this.spawn) }
+  async storage(directory: string) {
+    const stat = await fs.statfs(directory)
+    if (stat.bavail * stat.bsize < 1024 * 1024 * 1024) throw new Error('STORAGE_LIMIT')
+  }
+  async start(device: string, app: IosApp, directory: string, duration: number, own: (recording: IosRecording) => void): Promise<IosRecording> {
+    await this.storage(directory)
+    const binary = await prepareNotification(directory, this.spawn)
+    return this.startRecorder(device, app, directory, duration, binary, own)
+  }
+  private async startRecorder(device: string, app: IosApp, directory: string, duration: number, binary: string, own: (recording: IosRecording) => void) {
+    const name = 'tools.mobiledebug.trace.' + randomUUID()
+    const listener = await listenNotification(binary, name, this.spawn)
+    let recording: IosRecording | undefined
+    try {
+      const current = await this.resolve(device, app.app_id)
+      if (current.pid !== app.pid || current.executable !== app.executable || current.started_at !== app.started_at) throw new Error('APP_IDENTITY_CHANGED')
+      const file = path.join(directory, 'capture.trace')
+      const recorder = this.spawn(getXcrunCmd(), ['xctrace', 'record', '--template', 'Time Profiler', '--device', device,
+        '--attach', String(app.pid), '--time-limit', `${duration}ms`, '--output', file, '--notify-tracing-started', name], duration + 65000)
+      recording = { recorder, file, ready_at_ms: 0 }; own(recording)
+      await Promise.race([listener.line('READY', 35000), recorder.done.then(result => { throw new Error(classifyTraceFailure(result)) })])
+      if (!recorder.alive()) throw new Error('RECORDER_EXITED')
+      recording.ready_at_ms = Date.now()
+      return recording
+    } catch (error) {
+      if (recording) await stopTraceChild(recording.recorder).catch(() => {})
+      throw error
+    } finally { await stopTraceChild(listener, 1000).catch(() => {}) }
+  }
+  stop(recording: IosRecording, timeout?: number) { return stopTraceChild(recording.recorder, timeout) }
+  async monitor(device: string, app: IosApp, recording: IosRecording) {
+    const current = await this.resolve(device, app.app_id)
+    if (current.pid !== app.pid || current.executable !== app.executable || current.started_at !== app.started_at) throw new Error('APP_IDENTITY_CHANGED')
+    try { if (await traceSize(recording.file) > IOS_TRACE_MAX_BYTES) throw new Error('STORAGE_LIMIT') }
+    catch (error) { if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) throw error }
+  }
+  validate(recording: IosRecording, device: string, app: IosApp) { return validateArtifact(recording.file, device, app, this.spawn) }
+}

package/src/observe/ios-trace/notification.ts

@@ -0,0 +1,30 @@
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { getXcrunCmd } from '../../utils/ios/utils.js'
+import { traceCommand, spawnTrace, stopTraceChild, type TraceSpawn, type OwnedTraceChild } from './process.js'
+
+// A private per-session listener avoids requiring a third-party notification utility.
+const source = `#include <notify.h>
+#include <dispatch/dispatch.h>
+#include <stdio.h>
+#include <stdlib.h>
+int main(int argc, char **argv) {
+  if (argc != 2) return 2;
+  int token;
+  if (notify_register_dispatch(argv[1], &token, dispatch_get_main_queue(), ^(int t) {
+    puts("READY"); fflush(stdout); notify_cancel(t); exit(0);
+  }) != NOTIFY_STATUS_OK) return 3;
+  puts("ARMED"); fflush(stdout); dispatch_main();
+}`
+export async function prepareNotification(directory: string, spawn: TraceSpawn = spawnTrace) {
+  const file = path.join(directory, 'notification.c'), binary = path.join(directory, 'notification')
+  await fs.writeFile(file, source, { mode: 0o600 })
+  await traceCommand(getXcrunCmd(), ['clang', '-fblocks', file, '-o', binary], 30000, spawn)
+  await fs.chmod(binary, 0o700)
+  return binary
+}
+export async function listenNotification(binary: string, name: string, spawn: TraceSpawn = spawnTrace): Promise<OwnedTraceChild> {
+  const listener = spawn(binary, [name], 40000)
+  try { await listener.line('ARMED', 5000); return listener }
+  catch (error) { await stopTraceChild(listener, 1000).catch(() => {}); throw error }
+}

package/src/observe/ios-trace/process.ts

@@ -0,0 +1,82 @@
+import { spawn, type ChildProcess } from 'node:child_process'
+
+export interface TraceCommandResult { code: number | null; output: string; timedOut: boolean }
+export interface OwnedTraceChild {
+  done: Promise<TraceCommandResult>
+  alive(): boolean
+  signal(signal: NodeJS.Signals): void
+  line(text: string, timeout: number): Promise<void>
+}
+export type TraceSpawn = (command: string, args: string[], timeout: number) => OwnedTraceChild
+const MAX_OUTPUT = 64 * 1024
+
+export const spawnTrace: TraceSpawn = (command, args, timeout) => {
+  const child: ChildProcess = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] })
+  let output = '', settled = false, timedOut = false
+  const waiters = new Set<() => void>()
+  let force: ReturnType<typeof setTimeout> | undefined
+  const terminate = () => {
+    if (settled) return
+    child.kill('SIGTERM')
+    force ??= setTimeout(() => { if (!settled) child.kill('SIGKILL') }, 1000)
+    force.unref()
+  }
+  const timer = setTimeout(() => { timedOut = true; terminate() }, timeout)
+  timer.unref()
+  const done = new Promise<TraceCommandResult>(resolve => {
+    const finish = (code: number | null) => {
+      if (settled) return
+      settled = true; clearTimeout(timer); if (force) clearTimeout(force)
+      for (const wake of waiters) wake()
+      resolve({ code, output, timedOut })
+    }
+    child.on('error', () => finish(null))
+    child.on('close', finish)
+    const data = (chunk: Buffer) => {
+      output = (output + chunk.toString()).slice(-MAX_OUTPUT)
+      for (const wake of waiters) wake()
+    }
+    child.stdout?.on('data', data); child.stderr?.on('data', data)
+  })
+  return {
+    done, alive: () => !settled && child.exitCode === null && child.signalCode === null,
+    signal: signal => { if (!settled) child.kill(signal) },
+    line: (text, ms) => new Promise<void>((resolve, reject) => {
+      const deadline = setTimeout(() => { waiters.delete(check); reject(new Error('READINESS_TIMEOUT')) }, ms)
+      const check = () => {
+        if (output.split(/\r?\n/).includes(text)) { clearTimeout(deadline); waiters.delete(check); resolve() }
+        else if (settled) { clearTimeout(deadline); waiters.delete(check); reject(new Error('RECORDER_EXITED')) }
+      }
+      waiters.add(check); check()
+    })
+  }
+}
+
+export async function traceCommand(command: string, args: string[], timeout = 10000, spawn: TraceSpawn = spawnTrace) {
+  const result = await spawn(command, args, timeout).done
+  if (result.code !== 0 || result.timedOut) throw new Error(result.timedOut ? 'ACTION_TIMEOUT' : 'COMMAND_FAILED')
+  return result.output.trim()
+}
+export async function stopTraceChild(child: OwnedTraceChild, timeout = 30000) {
+  if (child.alive()) child.signal('SIGINT')
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const result = await Promise.race([
+    child.done,
+    new Promise<null>(resolve => { timer = setTimeout(() => resolve(null), timeout) })
+  ])
+  if (timer) clearTimeout(timer)
+  if (result) return result
+  child.signal('SIGKILL')
+  let forceTimer: ReturnType<typeof setTimeout> | undefined
+  await Promise.race([child.done, new Promise<void>(resolve => { forceTimer = setTimeout(resolve, 1000) })])
+  if (forceTimer) clearTimeout(forceTimer)
+  throw new Error('ACTION_TIMEOUT')
+}
+
+export function classifyTraceFailure(result: TraceCommandResult): string {
+  if (result.timedOut) return 'ACTION_TIMEOUT'
+  if (/permission|not permitted|authoriz|privacy|access denied/i.test(result.output)) return 'PROFILING_PERMISSION_REQUIRED'
+  if (/cannot find process|process.*not.*found/i.test(result.output)) return 'APP_NOT_RUNNING'
+  if (/disconnect|device.*unavailable/i.test(result.output)) return 'TARGET_DISCONNECTED'
+  return 'RECORDER_EXITED'
+}