mobile-debug-mcp 0.34.0 → 0.36.0

package/dist/observe/ios-trace/artifact.js

@@ -0,0 +1,63 @@
+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 } from './process.js';
+export const IOS_TRACE_MAX_BYTES = 256 * 1024 * 1024;
+export async function traceSize(root, secure = false) {
+    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;
+}
+export function validateToc(xml, device, app) {
+    if (XMLValidator.validate(xml) !== true)
+        throw new Error('INVALID_TOC');
+    const parsed = new XMLParser({ ignoreAttributes: false }).parse(xml);
+    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, device, app, spawn = 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', kind: (await fs.stat(file)).isDirectory() ? 'directory' : 'file',
+            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/dist/observe/ios-trace/capabilities.js

@@ -0,0 +1,86 @@
+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, spawnTrace } from './process.js';
+import { prepareNotification } from './notification.js';
+export const IOS_TEMPLATES = ['System Trace', 'Time Profiler', 'Animation Hitches', 'Hangs'];
+export async function resolveIosApp(device, appId, spawn = spawnTrace) {
+    const run = (args) => 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, appId, template = 'Time Profiler', spawn = spawnTrace, host = process.platform) {
+    const result = {
+        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, fn, recovery) => {
+        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));
+        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/dist/observe/ios-trace/native.js

@@ -0,0 +1,93 @@
+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 } from './capabilities.js';
+import { prepareNotification, listenNotification } from './notification.js';
+import { spawnTrace, stopTraceChild, classifyTraceFailure } from './process.js';
+import { traceSize, validateArtifact, IOS_TRACE_MAX_BYTES } from './artifact.js';
+export class IosTraceNative {
+    spawn;
+    children = new Set();
+    recorders = new Set();
+    closing = false;
+    constructor(spawn = 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, appId, template) { return iosCapabilities(device, appId, template, this.spawn); }
+    resolve(device, app) { return resolveIosApp(device, app, this.spawn); }
+    async storage(directory) {
+        const stat = await fs.statfs(directory);
+        if (stat.bavail * stat.bsize < 1024 * 1024 * 1024)
+            throw new Error('STORAGE_LIMIT');
+    }
+    async start(device, app, directory, duration, own) {
+        await this.storage(directory);
+        const binary = await prepareNotification(directory, this.spawn);
+        return this.startRecorder(device, app, directory, duration, binary, own);
+    }
+    async startRecorder(device, app, directory, duration, binary, own) {
+        const name = 'tools.mobiledebug.trace.' + randomUUID();
+        const listener = await listenNotification(binary, name, this.spawn);
+        let recording;
+        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, timeout) { return stopTraceChild(recording.recorder, timeout); }
+    async monitor(device, app, recording) {
+        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, device, app) { return validateArtifact(recording.file, device, app, this.spawn); }
+}

package/dist/observe/ios-trace/notification.js

@@ -0,0 +1,35 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { getXcrunCmd } from '../../utils/ios/utils.js';
+import { traceCommand, spawnTrace, stopTraceChild } 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, spawn = 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, name, spawn = spawnTrace) {
+    const listener = spawn(binary, [name], 40000);
+    try {
+        await listener.line('ARMED', 5000);
+        return listener;
+    }
+    catch (error) {
+        await stopTraceChild(listener, 1000).catch(() => { });
+        throw error;
+    }
+}

package/dist/observe/ios-trace/process.js

@@ -0,0 +1,98 @@
+import { spawn } from 'node:child_process';
+const MAX_OUTPUT = 64 * 1024;
+export const spawnTrace = (command, args, timeout) => {
+    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let output = '', settled = false, timedOut = false;
+    const waiters = new Set();
+    let force;
+    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(resolve => {
+        const finish = (code) => {
+            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) => {
+            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((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, args, timeout = 10000, spawn = 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, timeout = 30000) {
+    if (child.alive())
+        child.signal('SIGINT');
+    let timer;
+    const result = await Promise.race([
+        child.done,
+        new Promise(resolve => { timer = setTimeout(() => resolve(null), timeout); })
+    ]);
+    if (timer)
+        clearTimeout(timer);
+    if (result)
+        return result;
+    child.signal('SIGKILL');
+    let forceTimer;
+    await Promise.race([child.done, new Promise(resolve => { forceTimer = setTimeout(resolve, 1000); })]);
+    if (forceTimer)
+        clearTimeout(forceTimer);
+    throw new Error('ACTION_TIMEOUT');
+}
+export function classifyTraceFailure(result) {
+    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/dist/observe/ios-trace/sessions.js

@@ -0,0 +1,244 @@
+import { classifyTraceFailure } from './process.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 } from './native.js';
+const reasonFor = (error, fallback) => {
+    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 {
+    native;
+    time;
+    sessions = new Map();
+    closing = false;
+    constructor(native = new IosTraceNative(), time = {
+        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
+    }) {
+        this.native = native;
+        this.time = time;
+    }
+    get(id) {
+        this.prune();
+        const s = this.sessions.get(id);
+        if (!s)
+            throw new TraceError('TRACE_NOT_FOUND');
+        return s;
+    }
+    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);
+    }
+    serial(s, fn) {
+        const promise = s.queue.then(fn);
+        s.queue = promise.catch(() => { });
+        return promise;
+    }
+    snapshot(s) { return structuredClone(s.result); }
+    fail(s, reason) {
+        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, appId, 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 = {
+            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 = { 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);
+        });
+    }
+    schedule(s) {
+        if (s.result.state !== 'recording')
+            return;
+        s.timer = this.time.schedule(() => {
+            void this.serial(s, () => this.poll(s)).finally(() => this.schedule(s)).catch(() => { });
+        }, 1000);
+    }
+    async poll(s) {
+        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, op, timeout) {
+        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);
+        });
+    }
+    async finalise(s, op, preserveFailure = false, timeout) {
+        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);
+        }
+    }
+    async discardOversized(s) {
+        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 */ }
+    }
+    async finishRecorder(s, op, timeout) {
+        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');
+    }
+    async finishArtifact(s) {
+        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, device, correlation) {
+        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;
+            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;
+        await Promise.race([Promise.allSettled(active.map(s => this.control(s.result.trace_id, 'cancel', 8000))),
+            new Promise(resolve => { timer = setTimeout(resolve, 9000); })]);
+        if (timer)
+            clearTimeout(timer);
+        return active.filter(s => s.result.cleanup.status !== 'complete').map(s => this.snapshot(s));
+    }
+}