mobile-debug-mcp 0.35.0 → 0.36.0

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'
+}

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

@@ -0,0 +1,204 @@
+import { classifyTraceFailure } from './process.js'
+import type { TraceClock } from '../system-trace.js'
+import { TraceError } from '../system-trace-error.js'
+import { promises as fs } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { evidenceSessionId } from '../evidence.js'
+import { IosTraceNative, type IosRecording } from './native.js'
+import type { IosApp, IosTarget } from './capabilities.js'
+import type { validateArtifact } from './artifact.js'
+
+export interface IosTraceResult {
+  trace_id: string; session_id: string; device: IosTarget; backend: 'xctrace'
+  state: 'starting' | 'recording' | 'stopping' | 'completed' | 'cancelled' | 'failed'
+  reason: string | null; recovery: string | null; completion_reason: 'requested' | 'duration_limit' | 'cancelled' | 'error' | null
+  capture_started_at_ms: number | null; capture_completed_at_ms: number | null; recording_ready_at_ms: number | null
+  app_id: string; pid: number | null; executable: string | null; template: 'Time Profiler'
+  artifact: Awaited<ReturnType<typeof validateArtifact>> | null
+  cleanup: { status: 'pending' | 'complete' | 'failed'; remaining_resources: string[] }
+  warnings: string[]; correlation_ids: string[]; clock_alignment: 'unknown'
+}
+interface Session {
+  result: IosTraceResult; directory?: string; app?: IosApp; recording?: IosRecording
+  timer?: ReturnType<typeof setTimeout>; deadline: number; terminal?: number; discard: boolean
+  queue: Promise<unknown>; linked: Set<string>; partial: Set<string>; recorderOk?: boolean; monitorFailures?: number
+}
+const reasonFor = (error: unknown, fallback: string) => {
+  const code = error instanceof Error ? error.message : ''
+  return ['STORAGE_LIMIT', 'APP_IDENTITY_CHANGED', 'ACTION_TIMEOUT', 'READINESS_TIMEOUT', 'RECORDER_EXITED', 'PROFILING_PERMISSION_REQUIRED', 'APP_NOT_RUNNING', 'TARGET_DISCONNECTED'].includes(code) ? code : fallback
+}
+export class IosTraceSessions {
+  private sessions = new Map<string, Session>()
+  private closing = false
+  constructor(private native = new IosTraceNative(), private time: TraceClock = {
+    wall: Date.now, mono: () => performance.now(), sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+    schedule: (fn, ms) => { const timer = setTimeout(fn, ms); timer.unref(); return timer }, clear: clearTimeout
+  }) {}
+  private get(id: string) {
+    this.prune(); const s = this.sessions.get(id)
+    if (!s) throw new TraceError('TRACE_NOT_FOUND')
+    return s
+  }
+  private prune() {
+    const terminal = [...this.sessions.values()].filter(s => s.terminal !== undefined && s.result.cleanup.status === 'complete')
+    for (const [index, s] of terminal.entries()) if (this.time.mono() - s.terminal! >= 600000 || index < terminal.length - 100) this.sessions.delete(s.result.trace_id)
+  }
+  private serial<T>(s: Session, fn: () => Promise<T>) {
+    const promise = s.queue.then(fn); s.queue = promise.catch(() => {}); return promise
+  }
+  private snapshot(s: Session) { return structuredClone(s.result) }
+  private fail(s: Session, reason: string) {
+    s.result.state = 'failed'; s.result.reason = reason; s.result.completion_reason = 'error'
+    s.result.recovery = reason === 'PROFILING_PERMISSION_REQUIRED' ? 'Grant the required profiling permission through the macOS or Xcode UI, then explicitly start a new capture.' : reason === 'TRACE_ARTIFACT_FAILED' ? 'Retry stop to validate the finalised owned artifact, or cancel to discard.' : 'Check target, app and profiling permissions; cancel the owned session before retrying start.'
+    for (const id of s.linked) s.partial.add(id)
+  }
+  async start(device: IosTarget, appId: string, duration = 30000) {
+    this.prune()
+    const active = [...this.sessions.values()].filter(s => s.result.cleanup.status !== 'complete')
+    if (this.closing || active.length >= 4 || active.some(s => s.result.device.id === device.id)) throw new TraceError('TRACE_BUSY')
+    if (!Number.isInteger(duration) || duration < 1000 || duration > 120000) throw new TraceError('INVALID_ARGUMENT')
+    const result: IosTraceResult = {
+      trace_id: randomUUID(), session_id: evidenceSessionId(), device: structuredClone(device), backend: 'xctrace', state: 'starting',
+      reason: null, recovery: null, completion_reason: null, capture_started_at_ms: null, capture_completed_at_ms: null,
+      recording_ready_at_ms: null, app_id: appId, pid: null, executable: null, template: 'Time Profiler', artifact: null,
+      cleanup: { status: 'pending', remaining_resources: [] }, warnings: [], correlation_ids: [], clock_alignment: 'unknown'
+    }
+    const s: Session = { result, deadline: Infinity, discard: false, queue: Promise.resolve(), linked: new Set(), partial: new Set() }
+    this.sessions.set(result.trace_id, s)
+    return this.serial(s, async () => {
+      try {
+        s.directory = await fs.mkdtemp(path.join(os.tmpdir(), 'mobile-debug-ios-trace-'))
+        await fs.chmod(s.directory, 0o700)
+        s.result.cleanup.remaining_resources = [s.directory]
+        s.app = await this.native.resolve(device.id, appId)
+        s.result.pid = s.app.pid; s.result.executable = s.app.executable
+        if (this.closing) throw new TraceError('TRACE_BUSY')
+        s.result.capture_started_at_ms = this.time.wall()
+        s.deadline = Infinity
+        s.recording = await this.native.start(device.id, s.app, s.directory, duration, recording => { s.recording = recording; if (this.closing) recording.recorder.signal('SIGINT') })
+        if (this.closing) throw new Error('READINESS_TIMEOUT')
+        s.deadline = this.time.mono() + duration
+        s.result.recording_ready_at_ms = s.recording.ready_at_ms
+        s.result.state = 'recording'
+        this.schedule(s)
+        void s.recording.recorder.done.then(() => this.control(result.trace_id, 'status')).catch(() => {})
+      } catch (error) {
+        this.fail(s, reasonFor(error, 'TRACE_START_FAILED')); s.discard = true
+        await this.finalise(s, 'cancel', true)
+      }
+      return this.snapshot(s)
+    })
+  }
+  private schedule(s: Session) {
+    if (s.result.state !== 'recording') return
+    s.timer = this.time.schedule(() => {
+      void this.serial(s, () => this.poll(s)).finally(() => this.schedule(s)).catch(() => {})
+    }, 1000)
+  }
+  private async poll(s: Session) {
+    if (s.result.state !== 'recording' || !s.recording || !s.app) return
+    try {
+      await this.native.monitor(s.result.device.id, s.app, s.recording)
+      s.monitorFailures = 0
+    } catch (error) {
+      const reason = error instanceof Error && error.message === 'COMMAND_FAILED'
+        ? 'COMMAND_FAILED' : reasonFor(error, 'TRACE_MONITOR_FAILED')
+      const definitive = ['STORAGE_LIMIT', 'APP_IDENTITY_CHANGED', 'APP_NOT_RUNNING'].includes(reason)
+      s.monitorFailures = (s.monitorFailures ?? 0) + 1
+      if (definitive || s.monitorFailures >= 3) {
+        this.fail(s, reason); s.discard = true
+        await this.finalise(s, 'cancel', true)
+        return
+      }
+    }
+    if (this.time.mono() >= s.deadline || !s.recording.recorder.alive()) await this.finalise(s, 'duration')
+  }
+  async control(id: string, op: 'status' | 'stop' | 'cancel' | 'duration', timeout?: number) {
+    const s = this.get(id)
+    return this.serial(s, async () => {
+      if (s.result.cleanup.status === 'complete') return this.snapshot(s)
+      if (op === 'status' && s.result.state === 'recording' && s.recording?.recorder.alive() && this.time.mono() < s.deadline) {
+        await this.poll(s); return this.snapshot(s)
+      }
+      await this.finalise(s, op === 'status' ? 'duration' : op, false, timeout)
+      return this.snapshot(s)
+    })
+  }
+  private async finalise(s: Session, op: string, preserveFailure = false, timeout?: number) {
+    if (s.timer) { this.time.clear(s.timer); s.timer = undefined }
+    if (op === 'cancel') s.discard = true
+    if (!preserveFailure) s.result.state = 'stopping'
+    for (const id of s.linked) s.partial.add(id)
+    try {
+      await this.finishRecorder(s, op, timeout)
+      s.result.capture_completed_at_ms ??= this.time.wall()
+      await this.finishArtifact(s)
+      s.result.cleanup = { status: 'complete', remaining_resources: [] }; s.terminal = this.time.mono()
+      if (!preserveFailure) {
+        s.result.state = s.discard ? 'cancelled' : 'completed'; s.result.reason = s.discard ? 'TRACE_CANCELLED' : null; s.result.recovery = null
+        s.result.completion_reason = s.discard ? 'cancelled' : op === 'duration' ? 'duration_limit' : 'requested'
+      }
+    } catch (error) {
+      this.fail(s, reasonFor(error, s.recording?.recorder.alive() ? 'TRACE_STOP_FAILED' : 'TRACE_ARTIFACT_FAILED'))
+      s.result.cleanup.status = 'failed'
+      if (s.result.reason === 'STORAGE_LIMIT' && !s.recording?.recorder.alive()) await this.discardOversized(s)
+    }
+  }
+  private async discardOversized(s: Session) {
+    try {
+      if (s.directory) await fs.rm(s.directory, { recursive: true, force: true })
+      s.result.cleanup = { status: 'complete', remaining_resources: [] }; s.terminal = this.time.mono()
+    } catch { /* retain failed cleanup and owned path for cancel retry */ }
+  }
+  private async finishRecorder(s: Session, op: string, timeout?: number) {
+    if (!s.recording || s.recorderOk !== undefined) return
+    const ended = await this.native.stop(s.recording, timeout)
+    s.recorderOk = ended.code === 0 && !ended.timedOut
+    if (ended.output.includes('[Warning]')) s.result.warnings = ['INSTRUMENTS_RUN_WARNING: one or more Instruments warnings; coverage may be incomplete.']
+    if (!s.recorderOk && !s.discard) throw new Error(classifyTraceFailure(ended))
+    if (op === 'duration' && !ended.output.includes('Reached specified time limit') && this.time.mono() < s.deadline && !s.discard) throw new Error('RECORDER_EXITED')
+  }
+  private async finishArtifact(s: Session) {
+    if (!s.discard && !s.result.artifact) {
+      if (!s.recording || !s.app || !s.recorderOk) throw new Error('RECORDER_EXITED')
+      s.result.artifact = await this.native.validate(s.recording, s.result.device.id, s.app)
+    }
+    if (s.discard && s.directory) await fs.rm(s.directory, { recursive: true, force: true })
+    else if (s.directory) await Promise.all(['notification', 'notification.c'].map(p => fs.rm(path.join(s.directory!, p), { force: true })))
+  }
+  async link(id: string, device: { platform: string; id: string }, correlation: string) {
+    const s = this.get(id)
+    if (device.platform !== 'ios' || device.id !== s.result.device.id) throw new TraceError('TRACE_NOT_FOUND')
+    const status = await this.control(id, 'status')
+    if (status.state !== 'recording') throw new TraceError('TRACE_NOT_FOUND')
+    return this.serial(s, async () => {
+      if (s.result.state !== 'recording' || !s.recording?.recorder.alive() || this.time.mono() >= s.deadline) throw new TraceError('TRACE_NOT_FOUND')
+      if (!s.result.correlation_ids.includes(correlation)) {
+        if (s.result.correlation_ids.length >= 1000) throw new TraceError('TRACE_BUSY')
+        s.result.correlation_ids.push(correlation)
+      }
+      s.linked.add(correlation)
+      let finished: Promise<{ trace_id: string; coverage: string; clock_alignment: string }> | undefined
+      return () => finished ??= (async () => {
+        let active = false
+        try { active = (await this.control(id, 'status')).state === 'recording' } catch { /* unknown is partial */ }
+        s.linked.delete(correlation)
+        return { trace_id: id, coverage: !active || s.partial.has(correlation) ? 'partial' : 'covered', clock_alignment: 'unknown' }
+      })()
+    })
+  }
+  async shutdown() {
+    this.closing = true
+    this.native.shutdown()
+    const active = [...this.sessions.values()].filter(s => s.result.cleanup.status !== 'complete')
+    // Signal immediately even when an in-flight start/validation owns the serial queue.
+    for (const s of active) s.recording?.recorder.signal('SIGINT')
+    let timer: ReturnType<typeof setTimeout> | undefined
+    await Promise.race([Promise.allSettled(active.map(s => this.control(s.result.trace_id, 'cancel', 8000))),
+      new Promise<void>(resolve => { timer = setTimeout(resolve, 9000) })])
+    if (timer) clearTimeout(timer)
+    return active.filter(s => s.result.cleanup.status !== 'complete').map(s => this.snapshot(s))
+  }
+}

package/src/observe/readiness-service.ts

@@ -35,7 +35,7 @@ export async function getAppReadiness(args: Target & { timeoutMs?: number; stabi
         let count = 0
         while (wait || count < 2) {
           remainingBudget()
-          debugPause = device!.platform === 'android' ? pausedReadiness(device!.id) : null
+          debugPause = pausedReadiness(device!.id, device!.platform)
           if (debugPause) { failureCode = wait ? 'DEBUGGER_PAUSED' : undefined; return }
           const captureStarted = Date.now()
           try {

package/src/observe/readiness.ts

@@ -21,7 +21,7 @@ export class ReadinessTracker {
     this.summary = {
       state: 'unknown', scope: 'device_ui', basis: 'insufficient', captured_at_ms: null,
       sample_count: 0, stable_for_ms: 0, snapshot_session_id: null, snapshot_revision: null,
-      evidence: [], limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', 'INSUFFICIENT_SAMPLES'], capabilities: { ...capabilities, debugger_paused: this.platform === 'android' }
+      evidence: [], limitations: [...baselineLimitations, ['android', 'ios'].includes(this.platform) ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', 'INSUFFICIENT_SAMPLES'], capabilities: { ...capabilities, debugger_paused: ['android', 'ios'].includes(this.platform) }
     }
 
   }
@@ -30,7 +30,7 @@ export class ReadinessTracker {
     this.signature = null
     this.summary = {
       ...this.summary, state: 'unknown', basis: 'insufficient', stable_for_ms: 0,
-      sample_count: this.summary.sample_count + 1, limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', code],
+      sample_count: this.summary.sample_count + 1, limitations: [...baselineLimitations, ['android', 'ios'].includes(this.platform) ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', code],
       evidence: [...this.summary.evidence, { code, source: 'ui_tree', captured_at_ms: null, snapshot_revision: null }].slice(-8)
     }
     return this.summary
@@ -42,7 +42,7 @@ export class ReadinessTracker {
   }
 
   observe(sample: unknown, acquisitionStartedAtMs: number, now = performance.now()): ReadinessSummary {
-    const paused = this.platform === 'android' ? pausedReadiness(this.deviceId) : null
+    const paused = pausedReadiness(this.deviceId, this.platform)
     if (paused) { this.summary = paused; return this.summary }
     const tree = sample as GetUITreeResponse | null | undefined
     if (tree?.error) return this.unavailable('OBSERVATION_FAILED')
@@ -64,7 +64,7 @@ export class ReadinessTracker {
       captured_at_ms: tree.captured_at_ms, snapshot_session_id: tree.snapshot_session_id, snapshot_revision: tree.snapshot_revision,
       sample_count: this.summary.sample_count + 1, stable_for_ms: stableFor,
       evidence: [...this.summary.evidence, { code, source: 'ui_tree', captured_at_ms: tree.captured_at_ms, snapshot_revision: tree.snapshot_revision }].slice(-8),
-      limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', ...(state === 'unknown' ? ['INSUFFICIENT_SAMPLES'] : [])], capabilities: { ...capabilities, debugger_paused: this.platform === 'android' }
+      limitations: [...baselineLimitations, ['android', 'ios'].includes(this.platform) ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', ...(state === 'unknown' ? ['INSUFFICIENT_SAMPLES'] : [])], capabilities: { ...capabilities, debugger_paused: ['android', 'ios'].includes(this.platform) }
     }
     return this.summary
   }

package/src/observe/system-trace-error.ts

@@ -0,0 +1,3 @@
+export class TraceError extends Error {
+  constructor(public code: string) { super(code) }
+}

package/src/observe/system-trace-router.ts

@@ -0,0 +1,61 @@
+import { TraceError } from './system-trace-error.js'
+import type { SystemTraceSessions, TraceResult } from './system-trace.js'
+import { IosTraceSessions, type IosTraceResult } from './ios-trace/sessions.js'
+import { IosTraceNative } from './ios-trace/native.js'
+import type { IosTemplate } from './ios-trace/capabilities.js'
+
+interface Route { platform: 'android' | 'ios'; device: string; active: boolean; touched: number }
+export class SystemTraceRouter {
+  private routes = new Map<string, Route>()
+  private pending = new Set<string>()
+  private closing = false
+  constructor(private android: SystemTraceSessions, private ios = new IosTraceSessions(), private native = new IosTraceNative()) {}
+  capabilities(device: string) { return this.android.capabilities(device) }
+  iosCapabilities(device: string, appId?: string, template?: IosTemplate) { return this.native.capabilities(device, appId, template) }
+  private backend(platform: string) { return platform === 'ios' ? this.ios : this.android }
+  private track(result: TraceResult | IosTraceResult) {
+    this.routes.set(result.trace_id, { platform: result.device.platform, device: result.device.id,
+      active: result.cleanup.status !== 'complete', touched: performance.now() })
+    const terminal = [...this.routes.entries()].filter(([, r]) => !r.active)
+    for (const [index, [id, r]] of terminal.entries()) if (performance.now() - r.touched > 600000 || index < terminal.length - 100) this.routes.delete(id)
+    return result
+  }
+  async start(device: string, duration?: number, ios?: { appId: string; template?: IosTemplate }) {
+    if (this.closing) throw new TraceError('TRACE_BUSY')
+    // Refresh automatically finalised reservations without trusting cached state.
+    await Promise.all([...this.routes.entries()].filter(([, r]) => r.active).map(async ([id, r]) => {
+      try { this.track(await this.backend(r.platform).control(id, 'status')) }
+      catch { /* uncertain cleanup continues to reserve capacity */ }
+    }))
+    const key = (ios ? 'ios:' : 'android:') + device
+    const active = [...this.routes.values()].filter(r => r.active)
+    if (this.closing || this.pending.has(key) || active.some(r => r.platform + ':' + r.device === key) || active.length + this.pending.size >= 4) throw new TraceError('TRACE_BUSY')
+    this.pending.add(key)
+    try {
+      if (!ios) return this.track(await this.android.start(device, duration))
+      const cap = await this.native.capabilities(device, ios.appId, ios.template)
+      if (!cap.supported || !cap.device) throw new TraceError('TRACE_UNSUPPORTED')
+      if (this.closing) throw new TraceError('TRACE_BUSY')
+      return this.track(await this.ios.start(cap.device, ios.appId, duration))
+    } finally { this.pending.delete(key) }
+  }
+  async control(id: string, operation: 'status' | 'stop' | 'cancel' | 'duration') {
+    const route = this.routes.get(id)
+    if (!route) throw new TraceError('TRACE_NOT_FOUND')
+    return this.track(await this.backend(route.platform).control(id, operation))
+  }
+  async link(id: string, device: { platform: string; id: string }, correlation: string) {
+    const route = this.routes.get(id)
+    if (!route || route.platform !== device.platform || route.device !== device.id) throw new TraceError('TRACE_NOT_FOUND')
+    return this.backend(route.platform).link(id, device, correlation)
+  }
+  async shutdown() {
+    this.closing = true
+    this.native.shutdown()
+    const results = await Promise.allSettled([this.android.shutdown(), this.ios.shutdown()])
+    if (results.some(result => result.status === 'rejected')) throw new TraceError('TRACE_STOP_FAILED')
+    const remaining: (TraceResult | IosTraceResult)[] = []
+    for (const result of results) if (result.status === 'fulfilled') remaining.push(...result.value)
+    return remaining
+  }
+}