mobile-debug-mcp 0.33.0 → 0.34.0

package/dist/debugger/worker.js

@@ -0,0 +1,165 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFile, mkdtemp, chmod, rm } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { detectJavaHome } from '../utils/java.js';
+const exec = promisify(execFile);
+const operations = new AsyncLocalStorage();
+export function withDebuggerBudget(timeout, signal, operation) {
+    return operations.run({ deadline: performance.now() + timeout, signal }, operation);
+}
+export function debuggerRemaining(fallback) {
+    const context = operations.getStore();
+    if (context?.signal?.aborted)
+        throw new DebuggerError('DEBUGGER_CANCELLED');
+    const remaining = Math.floor((context?.deadline ?? Infinity) - performance.now());
+    if (remaining <= 0)
+        throw new DebuggerError('DEBUGGER_TIMEOUT');
+    return Math.min(fallback, remaining);
+}
+export function debuggerSignal() { return operations.getStore()?.signal; }
+export function nativeError(error, fallback) {
+    if (error instanceof DebuggerError)
+        return error;
+    if (debuggerSignal()?.aborted)
+        return new DebuggerError('DEBUGGER_CANCELLED');
+    if (error?.killed)
+        return new DebuggerError('DEBUGGER_TIMEOUT');
+    return new DebuggerError(fallback);
+}
+export class DebuggerError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+export const workerSource = fileURLToPath(new URL('../../worker/DebuggerWorker.java', import.meta.url));
+let compiled;
+export async function prepareWorker() {
+    compiled ??= (async () => {
+        const home = await detectJavaHome({ quiet: true });
+        const java = home ? path.join(home, 'bin', 'java') : 'java';
+        const javac = home ? path.join(home, 'bin', 'javac') : 'javac';
+        const version = await exec(java, ['-version'], { timeout: debuggerRemaining(5000), signal: debuggerSignal() });
+        const major = Number(/version "(\d+)/.exec(version.stderr)?.[1]);
+        if (!(major >= 17))
+            throw new DebuggerError('DEBUGGER_UNSUPPORTED');
+        const source = await readFile(workerSource);
+        const key = createHash('sha256').update(source).update(version.stderr).digest('hex').slice(0, 16);
+        const directory = await mkdtemp(path.join(os.tmpdir(), `mobile-debug-jdi-${key}-`));
+        await chmod(directory, 0o700);
+        try {
+            await exec(javac, ['--release', '17', '--add-modules', 'jdk.jdi', '-d', directory, workerSource], { timeout: debuggerRemaining(15000), signal: debuggerSignal(), maxBuffer: 1024 * 1024 });
+        }
+        catch (e) {
+            await rm(directory, { recursive: true, force: true });
+            throw nativeError(e, 'DEBUGGER_UNSUPPORTED');
+        }
+        return { java, directory };
+    })().catch(error => { compiled = undefined; throw error; });
+    return compiled;
+}
+export class JdiWorker {
+    child;
+    pending = new Map();
+    sequence = 0;
+    dead = false;
+    exited;
+    constructor(java, directory, onEvent) {
+        this.child = spawn(java, ['-Xmx128m', '--add-modules', 'jdk.jdi', '-cp', directory, 'DebuggerWorker'], { stdio: ['pipe', 'pipe', 'pipe'] });
+        let buffer = '';
+        const fail = () => {
+            if (this.dead)
+                return;
+            this.dead = true;
+            for (const request of this.pending.values()) {
+                clearTimeout(request.timer);
+                request.reject(new DebuggerError('DEBUGGER_WORKER_FAILED'));
+            }
+            this.pending.clear();
+            onEvent({ event: 'worker_failed' });
+        };
+        this.exited = new Promise(resolve => { this.child.once('exit', () => { fail(); resolve(); }); this.child.once('error', () => { fail(); resolve(); }); });
+        this.child.stdin.on('error', fail);
+        this.child.stderr.resume(); // Never copy worker data or VM diagnostics into MCP stdout/logs.
+        this.child.stdout.setEncoding('utf8');
+        this.child.stdout.on('data', (chunk) => {
+            buffer += chunk;
+            if (Buffer.byteLength(buffer) > 2 * 1024 * 1024) {
+                fail();
+                this.child.kill('SIGKILL');
+                return;
+            }
+            let end;
+            while ((end = buffer.indexOf('\n')) >= 0) {
+                const line = buffer.slice(0, end);
+                buffer = buffer.slice(end + 1);
+                try {
+                    if (Buffer.byteLength(line) > 1024 * 1024)
+                        throw new Error('IPC_LIMIT');
+                    const msg = JSON.parse(line);
+                    if (msg.event)
+                        onEvent(msg);
+                    else {
+                        const request = this.pending.get(msg.id);
+                        if (!request)
+                            continue;
+                        clearTimeout(request.timer);
+                        this.pending.delete(msg.id);
+                        if (msg.error)
+                            request.reject(new DebuggerError(msg.error.code ?? 'DEBUGGER_WORKER_FAILED'));
+                        else
+                            request.resolve(msg.result);
+                    }
+                }
+                catch {
+                    fail();
+                    this.child.kill('SIGKILL');
+                    return;
+                }
+            }
+        });
+    }
+    call(command, args = {}, timeout = 10000) {
+        if (this.dead)
+            return Promise.reject(new DebuggerError('DEBUGGER_WORKER_FAILED'));
+        try {
+            timeout = Math.min(timeout, debuggerRemaining(timeout));
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+        const id = ++this.sequence;
+        const message = JSON.stringify({ ...args, command, id }) + '\n';
+        if (Buffer.byteLength(message) > 1024 * 1024)
+            return Promise.reject(new DebuggerError('INVALID_ARGUMENT'));
+        return new Promise((resolve, reject) => {
+            const signal = debuggerSignal();
+            const abort = () => { this.pending.delete(id); clearTimeout(timer); reject(new DebuggerError('DEBUGGER_CANCELLED')); };
+            const done = () => signal?.removeEventListener('abort', abort);
+            const timer = setTimeout(() => { this.pending.delete(id); done(); reject(new DebuggerError('DEBUGGER_TIMEOUT')); }, timeout);
+            this.pending.set(id, { resolve: value => { done(); resolve(value); }, reject: error => { done(); reject(error); }, timer });
+            signal?.addEventListener('abort', abort, { once: true });
+            this.child.stdin.write(message);
+        });
+    }
+    async close() {
+        this.child.stdin.end();
+        const kill = setTimeout(() => this.child.kill('SIGKILL'), 2000);
+        try {
+            await this.exited;
+        }
+        finally {
+            clearTimeout(kill);
+        }
+    }
+}
+export async function createWorker(onEvent) {
+    const { java, directory } = await prepareWorker();
+    return new JdiWorker(java, directory, onEvent);
+}

package/dist/interact/index.js

@@ -1,3 +1,4 @@
+import { checkDebuggerGuard } from '../debugger/guard.js';
 import { currentReadinessWait, observeReadinessWait, isDeviceUnavailable } from '../observe/readiness.js';
 import { readinessDelay } from '../observe/readiness-service.js';
 import { isConditionBlocked } from './conditional-action.js';
@@ -1912,6 +1913,7 @@ export class ToolsInteract {
                             }
                         }
                         catch (e) {
+                            checkDebuggerGuard();
                             console.error('Error scoring element:', e);
                         }
                     }
@@ -1921,6 +1923,7 @@ export class ToolsInteract {
                 }
             }
             catch (e) {
+                checkDebuggerGuard();
                 console.error('Error fetching UI tree:', e);
             }
             if (shouldStop || Date.now() > deadline)
@@ -2023,6 +2026,7 @@ export class ToolsInteract {
             }
         }
         catch (e) {
+            checkDebuggerGuard();
             console.error('Error resolving ancestor:', e);
         }
         if (!best)
@@ -2280,6 +2284,7 @@ export class ToolsInteract {
                         }
                     }
                     catch (e) {
+                        checkDebuggerGuard();
                         // Deadline expiry does not invalidate the last successfully observed state.
                         if (e instanceof Error && e.message === 'ACTION_TIMEOUT')
                             throw e;
@@ -2323,6 +2328,7 @@ export class ToolsInteract {
             }
         }
         catch (err) {
+            checkDebuggerGuard();
             if (!readinessTracker && err instanceof Error && err.message === 'ACTION_TIMEOUT')
                 throw err;
             if (readinessTracker && isDeviceUnavailable(err))
@@ -2397,12 +2403,14 @@ export class ToolsInteract {
                         continue;
                     }
                     catch (e) {
+                        checkDebuggerGuard();
                         console.error('Error confirming fingerprint:', e);
                         continue;
                     }
                 }
             }
             catch (e) {
+                checkDebuggerGuard();
                 console.error('Error getting screen fingerprint:', e);
             }
             await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
@@ -2519,6 +2527,7 @@ export class ToolsInteract {
                 }
             }
             catch (error) {
+                checkDebuggerGuard();
                 if (readinessTracker && !String(error).includes('READINESS_'))
                     readinessTracker.unavailable();
                 if (readinessTracker && isDeviceUnavailable(error))
@@ -3039,6 +3048,7 @@ export class ToolsInteract {
             }
         }
         catch (err) {
+            checkDebuggerGuard();
             try {
                 console.warn('waitForUI: failed to get baseline data (non-fatal):', err instanceof Error ? err.message : String(err));
             }
@@ -3093,10 +3103,12 @@ export class ToolsInteract {
                         }
                     }
                     catch (err) {
+                        checkDebuggerGuard();
                         console.error('waitForUI(ui) find error:', err);
                     }
                 }
                 catch (err) {
+                    checkDebuggerGuard();
                     console.error('waitForUI(ui) outer error:', err);
                 }
             }
@@ -3130,6 +3142,7 @@ export class ToolsInteract {
                     }
                 }
                 catch (err) {
+                    checkDebuggerGuard();
                     console.error('waitForUI(log) error:', err);
                 }
             }
@@ -3158,6 +3171,7 @@ export class ToolsInteract {
                     }
                 }
                 catch (err) {
+                    checkDebuggerGuard();
                     console.error('waitForUI(screen) error:', err);
                 }
             }
@@ -3182,6 +3196,7 @@ export class ToolsInteract {
                     }
                 }
                 catch (err) {
+                    checkDebuggerGuard();
                     console.error('waitForUI(idle) error:', err);
                 }
             }
@@ -3199,6 +3214,7 @@ export class ToolsInteract {
                 snapshot = await Obs.ToolsObserve.captureDebugSnapshotHandler({ reason: `wait_for_ui timeout for ${type}`, includeLogs: true, platform, deviceId });
             }
             catch (err) {
+                checkDebuggerGuard();
                 snapshot = { error: err instanceof Error ? err.message : String(err) };
             }
         }

package/dist/observe/evidence.js

@@ -52,6 +52,13 @@ export function validateActionRef(value) {
             throw new Error('INVALID_ARGUMENT: invalid actionRef');
     return { sessionId: ref.sessionId, actionId: ref.actionId };
 }
+export function evidenceSessionId() { return sessionId; }
+export function currentEvidenceCorrelationId() { return context.getStore()?.correlationId; }
+export function bindSystemTrace(traceId) {
+    const current = context.getStore();
+    if (current)
+        current.systemTraceId = traceId;
+}
 export function currentEvidenceActionId() { return context.getStore()?.action?.id; }
 export function bindEvidenceDevice(device) {
     const current = context.getStore();
@@ -222,7 +229,7 @@ function assemble(current) {
         dispatch_started_at_ms: action?.dispatchStart?.wall ?? null,
         dispatch_completed_at_ms: action?.dispatchEnd?.wall ?? null,
         verification_completed_at_ms: current.verification?.wall ?? action?.verification?.wall ?? null,
-        observations, trace_context: { supported: false, trace_id: null, markers: [] }
+        observations, trace_context: { supported: !!current.systemTraceId, trace_id: current.systemTraceId ?? null, markers: [] }
     };
 }
 export async function withEvidence(options, operation) {
@@ -231,7 +238,7 @@ export async function withEvidence(options, operation) {
     const id = randomUUID();
     const record = options.action ? { id, correlationId: parent?.correlationId ?? id, device: null,
         dispatchStart: null, dispatchEnd: null, verification: null, completed: null } : options.ref?.sessionId === sessionId ? active.get(options.ref.actionId) ?? history.get(options.ref.actionId) ?? null : null;
-    const current = { correlationId: options.action ? record.correlationId : options.journey ? id : randomUUID(),
+    const current = { systemTraceId: parent?.systemTraceId, correlationId: options.action ? record.correlationId : options.journey ? id : randomUUID(),
         action: record, ref: options.ref, device: null, start: stamp(), end: null, verification: null, observations: [], children: [], isAction: !!options.action };
     if (options.action && record)
         active.set(id, record);

package/dist/observe/readiness-service.js

@@ -1,3 +1,4 @@
+import { pausedReadiness } from '../debugger/guard.js';
 import { resolveTargetDevice, withResolvedDevice } from '../utils/resolve-device.js';
 import { remainingBudget, runWithBudget } from '../utils/operation-budget.js';
 import { ToolsObserve } from './index.js';
@@ -32,6 +33,7 @@ export async function getAppReadiness(args, wait = false) {
     let device = null;
     let tracker = new ReadinessTracker(args.platform ?? 'android', args.deviceId ?? '');
     let failureCode;
+    let debugPause = null;
     await runWithBudget(args.timeoutMs ?? (wait ? 30000 : 15000), async () => {
         try {
             device = await resolve(args);
@@ -41,6 +43,11 @@ export async function getAppReadiness(args, wait = false) {
                 let count = 0;
                 while (wait || count < 2) {
                     remainingBudget();
+                    debugPause = device.platform === 'android' ? pausedReadiness(device.id) : null;
+                    if (debugPause) {
+                        failureCode = wait ? 'DEBUGGER_PAUSED' : undefined;
+                        return;
+                    }
                     const captureStarted = Date.now();
                     try {
                         const tree = await ToolsObserve.getUITreeHandler({ platform: device.platform, deviceId: device.id });
@@ -78,6 +85,8 @@ export async function getAppReadiness(args, wait = false) {
             failureCode = !expired && (!device || isDeviceUnavailable(error)) ? 'DEVICE_UNAVAILABLE' : wait ? 'READINESS_TIMEOUT' : 'READINESS_UNAVAILABLE';
         }
     });
+    if (debugPause)
+        return { success: !wait, device, readiness: debugPause, elapsed_ms: performance.now() - started, ...(wait ? { failure_code: 'DEBUGGER_PAUSED' } : {}) };
     const state = tracker.summary.state;
     const success = !failureCode && (wait ? state === 'settled' : state !== 'unknown');
     return { success, device, readiness: tracker.summary, elapsed_ms: performance.now() - started,

package/dist/observe/readiness.js

@@ -1,7 +1,8 @@
+import { pausedReadiness } from '../debugger/guard.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { remainingBudget } from '../utils/operation-budget.js';
 import { computeSnapshotSignature, getSnapshotSessionId } from './snapshot-metadata.js';
-const baselineLimitations = ['NORMALIZED_UI_ONLY', 'FOREGROUND_APP_UNVERIFIED', 'UNRESPONSIVE_SIGNAL_UNSUPPORTED', 'DEBUGGER_SIGNAL_UNSUPPORTED'];
+const baselineLimitations = ['NORMALIZED_UI_ONLY', 'FOREGROUND_APP_UNVERIFIED', 'UNRESPONSIVE_SIGNAL_UNSUPPORTED'];
 const capabilities = { loading: true, transitioning: true, settled: true, unresponsive: false, debugger_paused: false };
 export function isDeviceUnavailable(error) {
     return /device.*(?:not found|offline|disconnected)|no devices found|READINESS_DEVICE_UNAVAILABLE/i.test(String(error));
@@ -12,20 +13,21 @@ export class ReadinessTracker {
     stabilityMs;
     signature = null;
     stableSince = 0;
-    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, 'INSUFFICIENT_SAMPLES'], capabilities: { ...capabilities }
-    };
+    summary;
     constructor(platform, deviceId, stabilityMs = 500) {
         this.platform = platform;
         this.deviceId = deviceId;
         this.stabilityMs = stabilityMs;
+        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' }
+        };
     }
     unavailable(code = 'OBSERVATION_FAILED') {
         this.signature = null;
         this.summary = { ...this.summary, state: 'unknown', basis: 'insufficient', stable_for_ms: 0,
-            sample_count: this.summary.sample_count + 1, limitations: [...baselineLimitations, code],
+            sample_count: this.summary.sample_count + 1, limitations: [...baselineLimitations, this.platform === 'android' ? '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;
     }
@@ -34,6 +36,11 @@ export class ReadinessTracker {
         return this.summary;
     }
     observe(tree, acquisitionStartedAtMs, now = performance.now()) {
+        const paused = this.platform === 'android' ? pausedReadiness(this.deviceId) : null;
+        if (paused) {
+            this.summary = paused;
+            return this.summary;
+        }
         if (tree?.error)
             return this.unavailable('OBSERVATION_FAILED');
         if (!tree || tree.device?.platform !== this.platform || tree.device?.id !== this.deviceId ||
@@ -60,7 +67,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, ...(state === 'unknown' ? ['INSUFFICIENT_SAMPLES'] : [])], capabilities: { ...capabilities }
+            limitations: [...baselineLimitations, this.platform === 'android' ? 'MANAGED_DEBUGGER_ONLY' : 'DEBUGGER_SIGNAL_UNSUPPORTED', ...(state === 'unknown' ? ['INSUFFICIENT_SAMPLES'] : [])], capabilities: { ...capabilities, debugger_paused: this.platform === 'android' }
         };
         return this.summary;
     }

package/dist/observe/system-trace-android.js

@@ -0,0 +1,135 @@
+import { execCmd } from '../utils/exec.js';
+import { getAdbCmd } from '../utils/android/utils.js';
+export const TRACE_MAX_BYTES = 32 * 1024 * 1024;
+export const TRACE_CATEGORIES = ['sched', 'freq', 'idle', 'am', 'wm', 'gfx', 'view', 'input'];
+// Encode only this fixed preset using the public Perfetto proto field numbers:
+// https://github.com/google/perfetto/tree/main/protos/perfetto/config
+// Avoid --txt (explicitly unstable), arbitrary configuration and extra tooling.
+function varint(n) {
+    const bytes = [];
+    do {
+        const byte = n % 128;
+        n = Math.floor(n / 128);
+        bytes.push(byte | (n ? 128 : 0));
+    } while (n);
+    return Buffer.from(bytes);
+}
+const uint = (field, n) => Buffer.concat([varint(field * 8), varint(n)]);
+const message = (field, value) => {
+    const bytes = Buffer.isBuffer(value) ? value : Buffer.from(value);
+    return Buffer.concat([varint(field * 8 + 2), varint(bytes.length), bytes]);
+};
+export function traceConfig(duration, categories) {
+    const ftrace = Buffer.concat(categories.map(cat => message(2, cat)));
+    const source = Buffer.concat([message(1, 'linux.ftrace'), message(100, ftrace)]);
+    return Buffer.concat([
+        message(1, Buffer.concat([uint(1, 16384), uint(4, 1)])),
+        message(2, message(1, source)), uint(3, duration), uint(8, 1), uint(10, TRACE_MAX_BYTES)
+    ]);
+}
+const quote = (value) => `'${value.replace(/'/g, `'"'"'`)}'`;
+function ownedPath(remote) {
+    if (!/^\/data\/misc\/perfetto-traces\/mcp-[0-9a-f-]{36}\.perfetto-trace$/.test(remote))
+        throw new Error('Invalid owned trace path');
+}
+export class AndroidTraceNative {
+    execute;
+    constructor(execute = execCmd) {
+        this.execute = execute;
+    }
+    async command(device, args, timeout = 10000) {
+        const result = await this.execute(getAdbCmd(), ['-s', device, ...args], { timeout });
+        if (result.exitCode !== 0)
+            throw new Error(result.stderr === 'ACTION_TIMEOUT' ? 'ACTION_TIMEOUT' : 'ADB_TRACE_COMMAND_FAILED');
+        return result.stdout;
+    }
+    shell(device, script, timeout) {
+        return this.command(device, ['shell', 'sh', '-c', quote(script)], timeout);
+    }
+    async capabilities(deviceId) {
+        const checks = {};
+        const probe = async (name, fn) => { try {
+            checks[name] = await fn();
+        }
+        catch {
+            checks[name] = false;
+        } };
+        let help = '', categories = '';
+        await probe('android_api_29', async () => Number(await this.command(deviceId, ['shell', 'getprop', 'ro.build.version.sdk'])) >= 29);
+        await probe('perfetto', async () => { const result = await this.execute(getAdbCmd(), ['-s', deviceId, 'shell', 'perfetto', '--help'], { timeout: 10000 }); help = result.stdout + result.stderr; return [0, 1].includes(result.exitCode) && help.includes('Usage: perfetto') && help.includes('--background-wait') && help.includes('--config'); });
+        await probe('tracing_service', async () => { await this.command(deviceId, ['shell', 'perfetto', '--query']); return true; });
+        await probe('writable_storage', async () => { await this.shell(deviceId, 'test -w /data/misc/perfetto-traces'); return true; });
+        await probe('process_identity', async () => { await this.shell(deviceId, 'command -v pidof >/dev/null && test -r /proc/self/stat && test -r /proc/self/cmdline'); return true; });
+        await probe('base64', async () => (await this.shell(deviceId, "printf YQ== | base64 -d")) === 'a');
+        await probe('required_categories', async () => {
+            categories = await this.command(deviceId, ['shell', 'atrace', '--list_categories']);
+            return ['sched', 'input'].every(c => new RegExp(`^\\s*${c}\\s+-`, 'm').test(categories));
+        });
+        const enabled = TRACE_CATEGORIES.filter(c => new RegExp(`^\\s*${c}\\s+-`, 'm').test(categories));
+        return { supported: Object.values(checks).every(Boolean), backend: 'perfetto', device: { platform: 'android', id: deviceId },
+            prerequisites: checks, reasons: Object.keys(checks).filter(k => !checks[k]), enabled_sources: enabled,
+            unavailable_categories: TRACE_CATEGORIES.filter(c => !enabled.includes(c)), limitations: [
+                'Device-wide scheduling and system annotations may contain sensitive information.',
+                'Host times are not aligned with device trace clocks; source availability varies.',
+                'A server crash can leave a bounded trace file on the device for manual removal.'
+            ] };
+    }
+    async start(device, remote, duration, categories) {
+        ownedPath(remote);
+        const encoded = traceConfig(duration, categories).toString('base64');
+        await this.shell(device, `umask 077; printf %s ${quote(encoded)} | base64 -d | perfetto --background-wait -c - -o ${quote(remote)}`, 35000);
+    }
+    // Scan only shell-owned readable processes. Exact output argv + executable name
+    // binds ownership even if start acknowledgement/PID output was lost.
+    async find(device, remote) {
+        ownedPath(remote);
+        const output = await this.shell(device, `pids=$(pidof perfetto); rc=$?
+      [ "$rc" -le 1 ] || exit 1
+      for pid in $pids; do
+      p=/proc/$pid
+      [ -d "$p" ] || continue
+      [ -r "$p/cmdline" ] || { [ ! -d "$p" ] && continue; exit 1; }
+      cmd=$(tr '\\000' '\\n' < "$p/cmdline" 2>/dev/null) || { [ ! -d "$p" ] && continue; exit 1; }
+      printf '%s\\n' "$cmd" | grep -Fx ${quote(remote)} >/dev/null || continue
+      first=$(printf '%s\\n' "$cmd" | head -n 1)
+      case "$first" in perfetto|/system/bin/perfetto) ;; *) continue ;; esac
+      stat=$(cat "$p/stat" 2>/dev/null) || { [ ! -d "$p" ] && continue; exit 1; }
+      rest=\${stat##*) }
+      state=$(printf '%s\\n' "$rest" | awk '{print $1}')
+      [ "$state" = Z ] && continue
+      start=$(printf '%s\\n' "$rest" | awk '{print $20}')
+      printf '%s %s\\n' "\${p##*/}" "$start"
+    done`);
+        if (!output)
+            return null;
+        const match = /^(\d+) (\d+)$/.exec(output);
+        if (!match)
+            throw new Error('TRACE_PROCESS_IDENTITY_UNAVAILABLE');
+        return { pid: Number(match[1]), startTime: match[2] };
+    }
+    async stop(device, remote, owner) {
+        ownedPath(remote);
+        if (!Number.isSafeInteger(owner.pid) || owner.pid <= 1 || !/^\d+$/.test(owner.startTime))
+            throw new Error('TRACE_PROCESS_IDENTITY_UNAVAILABLE');
+        // Recheck start time and argv in the same shell immediately before signal.
+        await this.shell(device, `p=/proc/${owner.pid}
+      [ -d "$p" ] || exit 0
+      stat=$(cat "$p/stat") || exit 1
+      rest=\${stat##*) }
+      [ "$(printf '%s\\n' "$rest" | awk '{print $20}')" = ${quote(owner.startTime)} ] || exit 1
+      cmd=$(tr '\\000' '\\n' < "$p/cmdline") || exit 1
+      first=$(printf '%s\\n' "$cmd" | head -n 1)
+      case "$first" in perfetto|/system/bin/perfetto) ;; *) exit 1 ;; esac
+      printf '%s\\n' "$cmd" | grep -Fx ${quote(remote)} >/dev/null || exit 1
+      kill -TERM ${owner.pid}`);
+    }
+    async pull(device, remote, local) {
+        ownedPath(remote);
+        // Reject oversized output before initiating transfer as well as afterwards.
+        const size = Number(await this.command(device, ['shell', 'stat', '-c', '%s', remote]));
+        if (!Number.isSafeInteger(size) || size <= 0 || size > TRACE_MAX_BYTES)
+            throw new Error('TRACE_ARTIFACT_SIZE_INVALID');
+        await this.command(device, ['pull', remote, local], 30000);
+    }
+    async remove(device, remote) { ownedPath(remote); await this.command(device, ['shell', 'rm', '-f', remote]); }
+}