mobile-debug-mcp 0.32.4 → 0.34.0

package/dist/observe/recording.js

@@ -0,0 +1,165 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { mkdir, readdir, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execCmd } from '../utils/exec.js';
+import { getAdbCmd } from '../utils/android/utils.js';
+import { resolveTargetDevice } from '../utils/resolve-device.js';
+const recordings = new Map();
+const activeDevices = new Map();
+const adb = (deviceId, args, timeout = 15000) => execCmd(getAdbCmd(), ['-s', deviceId, ...args], { timeout });
+const tool = (name, args, timeout = 30000) => execCmd(name, args, { timeout });
+const swiftScript = fileURLToPath(new URL('../../scripts/recording-frames.swift', import.meta.url));
+async function swiftDecode(video, directory, startMs, endMs) {
+    const result = await tool('xcrun', ['swift', swiftScript, video, directory, String(startMs), String(endMs)], 120000);
+    if (result.exitCode !== 0)
+        throw new Error(`Swift frame decoder failed: ${result.stderr}`);
+    return JSON.parse(result.stdout);
+}
+function positiveInteger(value, name, max) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > max)
+        throw new Error(`${name} must be an integer from 1 to ${max}`);
+    return value;
+}
+async function probe(video) {
+    let result;
+    try {
+        result = await tool('ffprobe', ['-v', 'error', '-select_streams', 'v:0', '-show_entries', 'stream=width,height,nb_frames:format=duration', '-of', 'json', video]);
+    }
+    catch (error) {
+        if (process.platform !== 'darwin')
+            throw error;
+        const metadata = await swiftDecode(video, path.join(path.dirname(video), 'metadata'), 1, 0);
+        const { frames: _frames, ...rest } = metadata;
+        return rest;
+    }
+    if (result.exitCode !== 0)
+        throw new Error(`ffprobe failed: ${result.stderr || 'ffprobe is required for recording metadata and frame extraction'}`);
+    const data = JSON.parse(result.stdout);
+    const stream = data.streams?.[0];
+    if (!stream)
+        throw new Error('Recording contains no video stream');
+    const frames = await frameTimes(video);
+    return { durationMs: Math.round(Number(data.format.duration) * 1000), resolution: { width: stream.width, height: stream.height }, frameCount: frames.length, frameTimestampsMs: frames };
+}
+async function frameTimes(video) {
+    const result = await tool('ffprobe', ['-v', 'error', '-select_streams', 'v:0', '-show_entries', 'frame=best_effort_timestamp_time', '-of', 'json', video], 60000);
+    if (result.exitCode !== 0)
+        throw new Error(`ffprobe failed: ${result.stderr || 'ffprobe is required'}`);
+    return (JSON.parse(result.stdout).frames ?? []).map((frame) => Math.round(Number(frame.best_effort_timestamp_time) * 1000)).filter((value) => Number.isFinite(value));
+}
+export async function startScreenRecording(deviceId, maxDurationSeconds = 15) {
+    if (deviceId !== undefined && (typeof deviceId !== 'string' || !deviceId))
+        throw new Error('deviceId must be a nonempty string');
+    const durationLimit = positiveInteger(maxDurationSeconds, 'maxDurationSeconds', 180);
+    const device = await resolveTargetDevice({ platform: 'android', deviceId: deviceId });
+    if (activeDevices.has(device.id))
+        throw new Error(`A recording is already active for device ${device.id}`);
+    const id = randomUUID();
+    const directory = path.join(tmpdir(), 'mobile-debug-mcp-recordings', id);
+    const remote = `/sdcard/mobile-debug-mcp-${id}.mp4`;
+    await mkdir(directory, { recursive: true });
+    let finish;
+    const finished = new Promise(resolve => { finish = resolve; });
+    const child = spawn(getAdbCmd(), ['-s', device.id, 'shell', 'screenrecord', '--time-limit', String(durationLimit), remote], { stdio: 'ignore' });
+    const timer = setTimeout(() => { void stopScreenRecording(id).catch(() => undefined); }, (durationLimit + 2) * 1000);
+    timer.unref();
+    const recording = { id, deviceId: device.id, remote, directory, video: path.join(directory, 'recording.mp4'), startedAt: new Date().toISOString(), durationLimit, process: child, timer, state: 'recording', finished, finish };
+    recordings.set(id, recording);
+    activeDevices.set(device.id, id);
+    child.once('close', () => { finish(); if (recording.state === 'recording')
+        void stopScreenRecording(id).catch(() => undefined); });
+    child.once('error', () => { finish(); if (recording.state === 'recording')
+        void stopScreenRecording(id).catch(() => undefined); });
+    return { recordingId: id, deviceId: device.id, startedAt: recording.startedAt, maxDurationSeconds: durationLimit };
+}
+export async function stopScreenRecording(recordingId) {
+    const recording = typeof recordingId === 'string' ? recordings.get(recordingId) : undefined;
+    if (!recording)
+        throw new Error('Unknown recordingId');
+    if (recording.stopPromise)
+        return recording.stopPromise;
+    recording.state = 'stopping';
+    clearTimeout(recording.timer);
+    recording.stopPromise = (async () => {
+        try {
+            if (recording.process.exitCode === null) {
+                const processes = await adb(recording.deviceId, ['shell', 'ps', '-A', '-o', 'PID,ARGS']).catch(() => null);
+                const pid = processes?.stdout.split('\n').find(line => line.includes('screenrecord') && line.includes(recording.remote))?.trim().match(/^\d+/)?.[0];
+                if (pid)
+                    await adb(recording.deviceId, ['shell', 'kill', '-2', pid]).catch(() => undefined);
+            }
+            await Promise.race([recording.finished, new Promise(resolve => setTimeout(resolve, 3000))]);
+            if (recording.process.exitCode === null)
+                recording.process.kill('SIGKILL');
+            const pulled = await adb(recording.deviceId, ['pull', recording.remote, recording.video], 30000);
+            if (pulled.exitCode !== 0)
+                throw new Error(`Could not pull recording: ${pulled.stderr}`);
+            if ((await stat(recording.video)).size === 0)
+                throw new Error('Recording is empty');
+            let metadata;
+            try {
+                metadata = await probe(recording.video);
+            }
+            catch (error) {
+                metadata = { metadataError: String(error), durationMs: null, resolution: null, frameCount: null, frameTimestampsMs: [] };
+            }
+            recording.result = { recordingId: recording.id, deviceId: recording.deviceId, videoPath: recording.video, startedAt: recording.startedAt, stoppedAt: new Date().toISOString(), ...metadata };
+            return recording.result;
+        }
+        finally {
+            await adb(recording.deviceId, ['shell', 'rm', '-f', recording.remote]).catch(() => undefined);
+            activeDevices.delete(recording.deviceId);
+            recording.state = 'stopped';
+            if (!recording.result) {
+                recordings.delete(recording.id);
+                await rm(recording.directory, { recursive: true, force: true }).catch(() => undefined);
+            }
+        }
+    })();
+    return recording.stopPromise;
+}
+export async function extractRecordingFrames(recordingId, startMs, endMs) {
+    const recording = typeof recordingId === 'string' ? recordings.get(recordingId) : undefined;
+    if (!recording || recording.state !== 'stopped' || !recording.result)
+        throw new Error('Unknown or unfinished recordingId');
+    if (typeof startMs !== 'number' || !Number.isInteger(startMs) || startMs < 0 || typeof endMs !== 'number' || !Number.isInteger(endMs) || endMs <= startMs || endMs - startMs > 10000)
+        throw new Error('Window must be 1 to 10000 ms with nonnegative integer timestamps');
+    const directory = path.join(recording.directory, `frames-${startMs}-${endMs}`);
+    await rm(directory, { recursive: true, force: true });
+    await mkdir(directory, { recursive: true });
+    let allTimes;
+    let frames;
+    try {
+        allTimes = await frameTimes(recording.video);
+        const selected = allTimes.filter(time => time >= startMs && time <= endMs);
+        const result = await tool('ffmpeg', ['-v', 'error', '-i', recording.video, '-vf', `select=between(t\,${startMs / 1000}\,${endMs / 1000})`, '-vsync', '0', path.join(directory, '%06d.png')], 60000);
+        if (result.exitCode !== 0)
+            throw new Error(`ffmpeg failed: ${result.stderr || 'ffmpeg is required for frame extraction'}`);
+        const files = (await readdir(directory)).filter(file => file.endsWith('.png')).sort();
+        if (files.length !== selected.length)
+            throw new Error(`Frame count mismatch: ffprobe found ${selected.length}, ffmpeg extracted ${files.length}`);
+        frames = files.map((file, index) => ({ timestampMs: selected[index], path: path.join(directory, file) }));
+    }
+    catch (error) {
+        if (process.platform !== 'darwin')
+            throw error;
+        const decoded = await swiftDecode(recording.video, directory, startMs, endMs);
+        allTimes = decoded.frameTimestampsMs;
+        frames = decoded.frames;
+    }
+    const selected = frames.map(frame => frame.timestampMs);
+    const deltas = allTimes.slice(1).map((time, index) => time - allTimes[index]).filter(delta => delta > 0).sort((a, b) => a - b);
+    const nominalMs = deltas.length ? deltas[Math.floor((deltas.length - 1) / 2)] : null;
+    const gaps = allTimes.slice(1).flatMap((time, index) => nominalMs && time - allTimes[index] > nominalMs * 1.5 && time >= startMs && allTimes[index] <= endMs ? [{ startMs: allTimes[index], endMs: time, durationMs: time - allTimes[index] }] : []);
+    if (selected.length === 0 || selected[0] > startMs + (nominalMs ?? 0) * 1.5)
+        gaps.unshift({ startMs, endMs: selected[0] ?? endMs, durationMs: (selected[0] ?? endMs) - startMs });
+    if (selected.length && selected[selected.length - 1] < endMs - (nominalMs ?? 0) * 1.5)
+        gaps.push({ startMs: selected[selected.length - 1], endMs, durationMs: endMs - selected[selected.length - 1] });
+    return { recordingId, startMs, endMs, frames, frameCount: frames.length, nominalFrameIntervalMs: nominalMs, captureGaps: gaps, continuousCoverage: gaps.length === 0, note: 'Frames are encoded samples. A gap may hide a brief flash; absence cannot be established across gaps.' };
+}
+export async function shutdownRecordings() {
+    await Promise.allSettled([...activeDevices.values()].map(id => stopScreenRecording(id)));
+}

package/dist/observe/snapshot-metadata.js

@@ -1,6 +1,14 @@
 import crypto from 'crypto';
 let nextRevision = 1;
+const snapshotSessionId = crypto.randomUUID();
 const snapshotStateByDevice = new Map();
+export function getSnapshotSessionId() { return snapshotSessionId; }
+export function hasSnapshotBaseline(deviceKey, revision) {
+    const state = snapshotStateByDevice.get(deviceKey);
+    const capturedAt = state?.historyTimes.get(revision);
+    return !!state && capturedAt !== undefined && state.history.has(revision) &&
+        Date.now() - capturedAt <= 10 * 60 * 1000 && Date.now() - state.updatedAt <= 10 * 60 * 1000;
+}
 function normalize(value) {
     if (value === null || value === undefined)
         return '';
@@ -135,8 +143,7 @@ export function deriveSnapshotMetadata(deviceKey, tree, source, signatureOverrid
     const oversized = previous?.oversized ?? new Map();
     if (hasValidTree) {
         history.set(revision, currentElements);
-        if (!historyTimes.has(revision))
-            historyTimes.set(revision, Date.now());
+        historyTimes.set(revision, Date.now());
         if ((tree.elements?.length ?? 0) > 500)
             oversized.set(revision, (tree.elements?.length ?? 0) - 500);
     }
@@ -164,6 +171,7 @@ export function deriveSnapshotMetadata(deviceKey, tree, source, signatureOverrid
         updatedAt: Date.now()
     });
     return {
+        snapshot_session_id: snapshotSessionId,
         snapshot_revision: revision,
         captured_at_ms: Date.now(),
         snapshot_delta: hasValidTree ? summarizeSnapshotDelta(previous, currentElementSignatures) : null,

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]); }
+}

package/dist/observe/system-trace.js

@@ -0,0 +1,285 @@
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { AndroidTraceNative, TRACE_MAX_BYTES } from './system-trace-android.js';
+import { evidenceSessionId } from './evidence.js';
+import { runWithBudget, remainingBudget } from '../utils/operation-budget.js';
+export class TraceError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+const clock = {
+    wall: Date.now, mono: () => performance.now(), sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+    schedule: (fn, ms) => { const t = setTimeout(fn, ms); t.unref(); return t; }, clear: clearTimeout
+};
+export class SystemTraceSessions {
+    native;
+    time;
+    sessions = new Map();
+    closing = false;
+    constructor(native = new AndroidTraceNative(), time = clock) {
+        this.native = native;
+        this.time = time;
+    }
+    prune() {
+        const terminal = [...this.sessions.values()].filter(s => s.terminalAt !== undefined && s.result.cleanup.status === 'complete');
+        for (const s of terminal)
+            if (this.time.mono() - s.terminalAt >= 600000)
+                this.sessions.delete(s.result.trace_id);
+        const remaining = terminal.filter(s => this.sessions.has(s.result.trace_id));
+        for (const s of remaining.slice(0, Math.max(0, remaining.length - 100)))
+            this.sessions.delete(s.result.trace_id);
+    }
+    get(id) { this.prune(); const s = this.sessions.get(id); if (!s)
+        throw new TraceError('TRACE_NOT_FOUND'); return s; }
+    snapshot(s) { return structuredClone(s.result); }
+    serial(s, fn) {
+        const result = s.queue.then(fn);
+        s.queue = result.catch(() => { });
+        return result;
+    }
+    async capabilities(device) { return this.native.capabilities(device); }
+    async start(device, duration = 30000) {
+        if (!Number.isInteger(duration) || duration < 1000 || duration > 120000)
+            throw new TraceError('INVALID_ARGUMENT');
+        this.prune();
+        const reserved = [...this.sessions.values()].filter(s => s.result.cleanup.status !== 'complete');
+        if (this.closing || reserved.length >= 4 || reserved.some(s => s.result.device.id === device))
+            throw new TraceError('TRACE_BUSY');
+        const id = randomUUID();
+        const result = { trace_id: id, session_id: evidenceSessionId(), device: { platform: 'android', id: device }, backend: 'perfetto',
+            state: 'starting', reason: null, completion_reason: null, capture_started_at_ms: null, capture_completed_at_ms: null,
+            artifact: null, cleanup: { status: 'pending', remaining_resources: [] }, correlation_ids: [], enabled_sources: [], unavailable_categories: [] };
+        const s = { result, remote: `/data/misc/perfetto-traces/mcp-${id}.perfetto-trace`, owner: null, stopped: true,
+            discard: false, deadline: Infinity, queue: Promise.resolve(), linked: new Set(), partial: new Set() };
+        this.sessions.set(id, s);
+        return this.serial(s, async () => {
+            let cap;
+            try {
+                cap = await this.native.capabilities(device);
+            }
+            catch {
+                this.fail(s, 'TRACE_UNSUPPORTED');
+                this.clean(s);
+                return this.snapshot(s);
+            }
+            s.result.enabled_sources = cap.enabled_sources;
+            s.result.unavailable_categories = cap.unavailable_categories;
+            if (!cap.supported || this.closing) {
+                this.fail(s, this.closing ? 'TRACE_BUSY' : 'TRACE_UNSUPPORTED');
+                this.clean(s);
+                return this.snapshot(s);
+            }
+            s.stopped = false;
+            s.result.cleanup.remaining_resources = [s.remote, 'device_capture'];
+            // Conservative host bounds include acknowledgement latency, not exact device start.
+            s.result.capture_started_at_ms = this.time.wall();
+            s.deadline = this.time.mono() + duration;
+            try {
+                await this.native.start(device, s.remote, duration, cap.enabled_sources);
+                s.owner = await this.native.find(device, s.remote);
+                s.result.state = 'recording';
+                s.timer = this.time.schedule(() => { void this.control(id, 'duration').catch(() => { }); }, Math.max(0, s.deadline - this.time.mono()));
+            }
+            catch (error) {
+                s.discard = true;
+                this.fail(s, this.code(error, 'TRACE_START_FAILED'));
+                try {
+                    await this.halt(s);
+                    await this.remove(s);
+                }
+                catch {
+                    s.result.cleanup.status = 'failed';
+                }
+            }
+            return this.snapshot(s);
+        });
+    }
+    code(error, fallback) { return error instanceof Error && error.message === 'ACTION_TIMEOUT' ? 'ACTION_TIMEOUT' : fallback; }
+    fail(s, reason) {
+        s.result.state = 'failed';
+        s.result.reason = reason;
+        s.result.completion_reason = 'error';
+        s.terminalAt = this.time.mono();
+    }
+    clean(s) {
+        s.result.cleanup = { status: 'complete', remaining_resources: [] };
+        s.terminalAt = this.time.mono();
+        this.prune();
+    }
+    async halt(s) {
+        if (s.stopped)
+            return;
+        const deadline = this.time.mono() + 10000;
+        await runWithBudget(10000, async () => {
+            const found = await this.native.find(s.result.device.id, s.remote);
+            if (found) {
+                if (s.owner && (s.owner.pid !== found.pid || s.owner.startTime !== found.startTime))
+                    throw new TraceError('TRACE_STOP_FAILED');
+                s.owner ??= found;
+                try {
+                    await this.native.stop(s.result.device.id, s.remote, s.owner);
+                }
+                catch (error) {
+                    // Natural expiry can win between identity lookup and SIGTERM. Only
+                    // confirmed absence permits finalisation; unreadable/reused identity fails.
+                    if (await this.native.find(s.result.device.id, s.remote))
+                        throw error;
+                }
+                while (await this.native.find(s.result.device.id, s.remote)) {
+                    if (this.time.mono() >= deadline)
+                        throw new TraceError('ACTION_TIMEOUT');
+                    remainingBudget();
+                    await this.time.sleep(100);
+                }
+            }
+        });
+        s.stopped = true;
+        s.result.capture_completed_at_ms = this.time.wall();
+        s.result.cleanup.remaining_resources = [s.remote];
+        for (const linked of s.linked)
+            s.partial.add(linked);
+    }
+    async remove(s) {
+        if (!s.stopped)
+            throw new TraceError('TRACE_STOP_FAILED');
+        await this.native.remove(s.result.device.id, s.remote);
+        if (s.local && !s.result.artifact) {
+            await fs.rm(s.local, { recursive: true, force: true });
+            s.local = undefined;
+        }
+        this.clean(s);
+    }
+    async artifact(s) {
+        if (s.result.artifact)
+            return;
+        s.local ??= await fs.mkdtemp(path.join(os.tmpdir(), 'mobile-debug-trace-'));
+        const local = s.local;
+        const partial = path.join(local, 'capture.partial');
+        try {
+            await fs.chmod(s.local, 0o700);
+            await this.native.pull(s.result.device.id, s.remote, partial);
+            const stat = await fs.stat(partial);
+            if (!stat.isFile() || stat.size <= 0 || stat.size > TRACE_MAX_BYTES)
+                throw new TraceError('TRACE_ARTIFACT_FAILED');
+            await fs.chmod(partial, 0o600);
+            const target = path.join(s.local, `${s.result.trace_id}.perfetto-trace`);
+            await fs.rename(partial, target);
+            s.result.artifact = { path: target, format: 'perfetto', size_bytes: stat.size };
+        }
+        catch (error) {
+            try {
+                await fs.rm(local, { recursive: true, force: true });
+                s.local = undefined;
+            }
+            catch {
+                s.result.cleanup.remaining_resources = [s.remote, local];
+            }
+            throw error;
+        }
+    }
+    async control(id, operation) {
+        const s = this.get(id);
+        return this.serial(s, async () => {
+            if (s.result.cleanup.status === 'complete')
+                return this.snapshot(s);
+            if (operation === 'status' && s.result.state === 'recording') {
+                try {
+                    if (await this.native.find(s.result.device.id, s.remote) && this.time.mono() < s.deadline)
+                        return this.snapshot(s);
+                }
+                catch (error) {
+                    this.fail(s, this.code(error, 'TRACE_STOP_FAILED'));
+                    s.result.cleanup.status = 'failed';
+                    return this.snapshot(s);
+                }
+            }
+            if (s.timer) {
+                this.time.clear(s.timer);
+                s.timer = undefined;
+            }
+            if (operation === 'cancel')
+                s.discard = true;
+            const hadStartFailure = s.discard && s.result.state === 'failed' && operation !== 'cancel';
+            s.result.state = 'stopping';
+            s.result.cleanup.status = 'pending';
+            try {
+                await this.halt(s);
+            }
+            catch (error) {
+                this.fail(s, this.code(error, 'TRACE_STOP_FAILED'));
+                s.result.cleanup.status = 'failed';
+                return this.snapshot(s);
+            }
+            if (!s.discard) {
+                try {
+                    await this.artifact(s);
+                }
+                catch (error) {
+                    this.fail(s, this.code(error, 'TRACE_ARTIFACT_FAILED'));
+                    s.result.cleanup.status = 'failed';
+                    return this.snapshot(s);
+                }
+            }
+            try {
+                await this.remove(s);
+            }
+            catch {
+                this.fail(s, 'TRACE_STOP_FAILED');
+                s.result.cleanup.status = 'failed';
+                return this.snapshot(s);
+            }
+            if (hadStartFailure)
+                s.result.state = 'failed';
+            else {
+                s.result.state = s.discard ? 'cancelled' : 'completed';
+                s.result.reason = s.discard ? 'TRACE_CANCELLED' : null;
+                s.result.completion_reason = s.discard ? 'cancelled' : operation === 'duration' || this.time.mono() >= s.deadline ? 'duration_limit' : 'requested';
+            }
+            return this.snapshot(s);
+        });
+    }
+    async link(id, device, correlation) {
+        const s = this.get(id);
+        if (device.platform !== 'android' || device.id !== s.result.device.id)
+            throw new TraceError('TRACE_NOT_FOUND');
+        const status = await this.control(id, 'status');
+        if (device.platform !== 'android' || device.id !== status.device.id || status.state !== 'recording')
+            throw new TraceError('TRACE_NOT_FOUND');
+        // Validate again after the asynchronous status call: stop/cancel may have won.
+        return this.serial(s, async () => {
+            if (s.result.state !== 'recording' || 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 finish;
+            return () => finish ??= (async () => {
+                let recording = false;
+                try {
+                    recording = (await this.control(id, 'status')).state === 'recording';
+                }
+                catch { /* Unavailable state cannot establish complete coverage. */ }
+                s.linked.delete(correlation);
+                return { trace_id: id, coverage: !recording || s.partial.has(correlation) || this.time.mono() >= s.deadline ? 'partial' : 'covered',
+                    clock_alignment: 'unknown' };
+            })();
+        });
+    }
+    async shutdown() {
+        this.closing = true;
+        // Independent device cleanup in parallel under one overall deadline.
+        return runWithBudget(10000, async () => {
+            await Promise.allSettled([...this.sessions.values()].filter(s => s.result.cleanup.status !== 'complete').map(s => this.control(s.result.trace_id, 'cancel')));
+            return [...this.sessions.values()].filter(s => s.result.cleanup.status !== 'complete').map(s => this.snapshot(s));
+        });
+    }
+}
+export const systemTraces = new SystemTraceSessions();

package/dist/server/common.js

@@ -1,5 +1,7 @@
+import { currentEvidenceActionId } from '../observe/evidence.js';
 import { recordTiming } from '../utils/timing.js';
 import { ToolsObserve } from '../observe/index.js';
+import { isConditionBlocked } from '../interact/conditional-action.js';
 export const DEFAULT_MAX_RECOVERY_ATTEMPTS = 3;
 export const DEFAULT_MAX_RETRY_DEPTH = 3;
 export function wrapResponse(data, includeSerializationTiming = true) {
@@ -62,10 +64,15 @@ export function getArrayArg(args, key) {
 }
 let actionSequence = 0;
 export function nextActionId(actionType, timestamp) {
+    const current = currentEvidenceActionId();
+    if (current)
+        return current;
     actionSequence += 1;
     return `${actionType}_${timestamp}_${actionSequence}`;
 }
 export async function captureActionFingerprint(platform, deviceId) {
+    if (isConditionBlocked())
+        return null;
     if (!platform)
         return null;
     try {
@@ -235,6 +242,8 @@ function mapFailureCodeToFailureClass(code) {
         case 'STALE_REFERENCE':
             return 'TargetResolutionFailure';
         case 'ELEMENT_NOT_INTERACTABLE':
+        case 'PRECONDITION_FAILED':
+        case 'PRECONDITION_UNAVAILABLE':
         case 'ACTION_TIMEOUT':
             return 'ExecutionFailure';
         case 'TIMEOUT':