mobile-debug-mcp 0.33.0 → 0.34.0

package/dist/server/tool-handlers.js

@@ -1,4 +1,10 @@
-import { withEvidence, currentEvidenceActionId, validateActionRef, markEvidenceVerification, refreshJourneyEvidence, completeJourneyVerification } from '../observe/evidence.js';
+import { handleDebugger } from './debugger-handlers.js';
+import { debuggerContracts } from './debugger-schema.js';
+import { debuggerSessions } from '../debugger/sessions.js';
+import { withDebuggerGuard, guardDispatched } from '../debugger/guard.js';
+import { systemTraces, TraceError } from '../observe/system-trace.js';
+import { systemTraceTools, traceTargetSchema, traceStartSchema, traceControlSchema } from './system-trace-schema.js';
+import { currentEvidenceCorrelationId, bindSystemTrace, withEvidence, currentEvidenceActionId, validateActionRef, markEvidenceVerification, refreshJourneyEvidence, completeJourneyVerification } from '../observe/evidence.js';
 import { measure, withTiming } from '../utils/timing.js';
 import { randomUUID } from 'node:crypto';
 import { runWithBudget } from '../utils/operation-budget.js';
@@ -16,6 +22,7 @@ import { ToolsNetwork } from '../network/index.js';
 import { getSystemStatus } from '../system/index.js';
 import { recordObservationConsumer, recordObservationEvent, withObservationContext } from '../observe/performance-metrics.js';
 import { buildActionExecutionResult, captureActionFingerprint, getArrayArg, getBooleanArg, getNumberArg, getObjectArg, getStringArg, inferGenericFailure, inferScrollFailure, requireBooleanArg, requireNumberArg, requireObjectArg, requireStringArg, wrapResponse, wrapToolError } from './common.js';
+const systemTraceToolNames = new Set(systemTraceTools.map(tool => tool.name));
 function interactionControls(args) {
     const verificationMode = getStringArg(args, 'verificationMode') ?? 'full';
     const responseMode = getStringArg(args, 'responseMode') ?? 'debug';
@@ -56,7 +63,7 @@ function correlatedHandler(name, handler, action = false, journey = false) {
                 return await handler(args);
             }
             catch (error) {
-                return wrapToolError(name, error);
+                return error instanceof TraceError ? { ...wrapResponse({ error: { tool: name, code: error.code, message: error.message } }), isError: true } : wrapToolError(name, error);
             }
         });
         const item = result.content.find(item => item.type === 'text');
@@ -570,106 +577,125 @@ async function handleRunJourney(args) {
     const steps = parsed.data.steps;
     const device = await resolveTargetDevice({ platform, deviceId: parsed.data.deviceId });
     const deviceId = device.id;
-    return withResolvedDevice(device, async () => {
-        const started = performance.now();
-        const results = [];
-        let stoppedAt = null;
-        let pendingLightStep = null;
-        for (let index = 0; index < steps.length; index++) {
-            const step = steps[index];
-            const requestedVerification = step.verificationMode ?? defaults?.verificationMode ?? 'full';
-            const next = steps[index + 1];
-            const lightCoveredByAssertion = step.type === 'tap' && responseMode === 'compact' && requestedVerification === 'light' && next?.type === 'assert' &&
-                next.assertion?.kind === 'element_visible';
-            const stepStart = performance.now();
-            let result;
-            if (stoppedAt) {
-                results.push({ id: step.id, type: step.type, status: 'not_run', success: false, reason: 'PREVIOUS_STEP_FAILED', result: null, timing: { total_ms: 0 } });
-                continue;
-            }
-            try {
-                if (step.type === 'tap') {
-                    result = payloadOf(await handleTapElement({ ...defaults, ...step, platform, deviceId, responseMode, _journey: true, _stepId: step.id, verificationMode: lightCoveredByAssertion ? 'none' : requestedVerification }));
+    const finishTrace = parsed.data.systemTraceId
+        ? await systemTraces.link(parsed.data.systemTraceId, device, currentEvidenceCorrelationId()) : undefined;
+    if (parsed.data.systemTraceId)
+        bindSystemTrace(parsed.data.systemTraceId);
+    try {
+        return await withResolvedDevice(device, async () => {
+            const started = performance.now();
+            const results = [];
+            let stoppedAt = null;
+            let pendingLightStep = null;
+            for (let index = 0; index < steps.length; index++) {
+                const step = steps[index];
+                if (platform === 'android' && debuggerSessions.paused(deviceId)) {
+                    results.push({ id: step.id, type: step.type, status: 'failed', success: false, result: { success: false, failure_code: 'DEBUGGER_PAUSED', dispatch_started: false, delivery_status: 'not_delivered' } });
+                    stoppedAt = step.id;
+                    break;
                 }
-                else if (step.type === 'wait') {
-                    result = await withObservationContext({ stepId: step.id, purpose: 'target' }, () => ToolsInteract.waitForUIHandler({ selector: step.selector, condition: step.condition ?? 'exists', timeout_ms: step.timeoutMs ?? 5000, poll_interval_ms: step.pollIntervalMs ?? 100, platform, deviceId }));
-                    result = { success: result.status === 'success', ...result };
+                const requestedVerification = step.verificationMode ?? defaults?.verificationMode ?? 'full';
+                const next = steps[index + 1];
+                const lightCoveredByAssertion = step.type === 'tap' && responseMode === 'compact' && requestedVerification === 'light' && next?.type === 'assert' &&
+                    next.assertion?.kind === 'element_visible';
+                const stepStart = performance.now();
+                let result;
+                if (stoppedAt) {
+                    results.push({ id: step.id, type: step.type, status: 'not_run', success: false, reason: 'PREVIOUS_STEP_FAILED', result: null, timing: { total_ms: 0 } });
+                    continue;
                 }
-                else if (step.type === 'assert') {
-                    result = await withObservationContext({ stepId: step.id, purpose: 'assertion' }, () => runWithBudget(step.timeoutMs ?? 5000, async () => {
-                        const assertion = step.assertion;
-                        if (assertion?.kind === 'element_visible')
-                            result = await ToolsInteract.expectElementVisibleHandler({ selector: assertion.selector, timeout_ms: step.timeoutMs ?? 5000, poll_interval_ms: step.pollIntervalMs ?? 100, platform, deviceId });
-                        else if (assertion?.kind === 'element_absent')
-                            result = await expectElementAbsent({ selector: assertion.selector, timeoutMs: step.timeoutMs ?? 5000, pollIntervalMs: step.pollIntervalMs ?? 100, platform, deviceId });
-                        else if (assertion?.kind === 'screen_fingerprint')
-                            result = await expectFingerprint({ fingerprint: assertion.fingerprint, timeoutMs: step.timeoutMs ?? 5000, platform, deviceId });
-                        else if (assertion?.kind === 'state_equals')
-                            result = await ToolsInteract.expectStateHandler({ selector: assertion.selector, element_id: assertion.elementId, property: assertion.property, expected: assertion.expected, platform, deviceId, stabilization_window_ms: step.timeoutMs ?? 5000, poll_interval_ms: step.pollIntervalMs ?? 100, exact_budget: true });
-                        else
-                            result = { success: false, failure_code: 'INVALID_ASSERTION' };
-                        return result;
-                    }));
+                try {
+                    if (step.type === 'tap') {
+                        result = payloadOf(await handleTapElement({ ...defaults, ...step, platform, deviceId, responseMode, _journey: true, _stepId: step.id, verificationMode: lightCoveredByAssertion ? 'none' : requestedVerification }));
+                    }
+                    else if (step.type === 'wait') {
+                        result = await withObservationContext({ stepId: step.id, purpose: 'target' }, () => ToolsInteract.waitForUIHandler({ selector: step.selector, condition: step.condition ?? 'exists', timeout_ms: step.timeoutMs ?? 5000, poll_interval_ms: step.pollIntervalMs ?? 100, platform, deviceId }));
+                        result = { success: result.status === 'success', ...result };
+                    }
+                    else if (step.type === 'assert') {
+                        result = await withObservationContext({ stepId: step.id, purpose: 'assertion' }, () => runWithBudget(step.timeoutMs ?? 5000, async () => {
+                            const assertion = step.assertion;
+                            if (assertion?.kind === 'element_visible')
+                                result = await ToolsInteract.expectElementVisibleHandler({ selector: assertion.selector, timeout_ms: step.timeoutMs ?? 5000, poll_interval_ms: step.pollIntervalMs ?? 100, platform, deviceId });
+                            else if (assertion?.kind === 'element_absent')
+                                result = await expectElementAbsent({ selector: assertion.selector, timeoutMs: step.timeoutMs ?? 5000, pollIntervalMs: step.pollIntervalMs ?? 100, platform, deviceId });
+                            else if (assertion?.kind === 'screen_fingerprint')
+                                result = await expectFingerprint({ fingerprint: assertion.fingerprint, timeoutMs: step.timeoutMs ?? 5000, platform, deviceId });
+                            else if (assertion?.kind === 'state_equals')
+                                result = await ToolsInteract.expectStateHandler({ selector: assertion.selector, element_id: assertion.elementId, property: assertion.property, expected: assertion.expected, platform, deviceId, stabilization_window_ms: step.timeoutMs ?? 5000, poll_interval_ms: step.pollIntervalMs ?? 100, exact_budget: true });
+                            else
+                                result = { success: false, failure_code: 'INVALID_ASSERTION' };
+                            return result;
+                        }));
+                    }
+                    else if (step.type === 'start_app') {
+                        result = payloadOf(await handleStartApp({ ...defaults, platform, deviceId, appId: step.appId, responseMode, _journey: true, _stepId: step.id, verificationMode: step.verificationMode ?? defaults?.verificationMode ?? 'full' }));
+                    }
+                    else {
+                        result = { success: false, failure_code: 'UNSUPPORTED_JOURNEY_STEP' };
+                    }
                 }
-                else if (step.type === 'start_app') {
-                    result = payloadOf(await handleStartApp({ ...defaults, platform, deviceId, appId: step.appId, responseMode, _journey: true, _stepId: step.id, verificationMode: step.verificationMode ?? defaults?.verificationMode ?? 'full' }));
+                catch (error) {
+                    result = { success: false, failure_code: step.type === 'assert' ? 'ASSERTION_TIMEOUT' : 'STEP_FAILED', error: error instanceof Error ? error.message : String(error) };
                 }
-                else {
-                    result = { success: false, failure_code: 'UNSUPPORTED_JOURNEY_STEP' };
+                if (platform === 'android' && debuggerSessions.paused(deviceId)) {
+                    result.success = false;
+                    result.failure_code = 'DEBUGGER_PAUSED';
+                    result.retryable = false;
                 }
-            }
-            catch (error) {
-                result = { success: false, failure_code: step.type === 'assert' ? 'ASSERTION_TIMEOUT' : 'STEP_FAILED', error: error instanceof Error ? error.message : String(error) };
-            }
-            if (step.type === 'assert' && !result?.success && /TIMEOUT/.test(result?.failure_code ?? ''))
-                result.failure_code = 'ASSERTION_TIMEOUT';
-            const success = !!result?.success;
-            if (lightCoveredByAssertion) {
-                result.verification = { mode: 'light', status: success ? 'unavailable' :
-                        (['mismatch', 'unavailable'].includes(result.condition?.status) ? 'not_requested' : 'failed') };
-                if (success) {
-                    result.verification_diagnostic = { code: 'VERIFICATION_UNAVAILABLE', retryable: true };
-                    pendingLightStep = results.length;
+                if (step.type === 'assert' && !result?.success && /TIMEOUT/.test(result?.failure_code ?? ''))
+                    result.failure_code = 'ASSERTION_TIMEOUT';
+                const success = !!result?.success;
+                if (lightCoveredByAssertion) {
+                    result.verification = { mode: 'light', status: success ? 'unavailable' :
+                            (['mismatch', 'unavailable'].includes(result.condition?.status) ? 'not_requested' : 'failed') };
+                    if (success) {
+                        result.verification_diagnostic = { code: 'VERIFICATION_UNAVAILABLE', retryable: true };
+                        pendingLightStep = results.length;
+                    }
                 }
-            }
-            if (step.type === 'assert' && pendingLightStep !== null) {
-                const pending = results[pendingLightStep].result;
-                if (typeof result?.observed?.matched_count === 'number') {
-                    pending.verification.status = 'observed';
-                    if (pending.evidence)
-                        completeJourneyVerification(pending.evidence.action_id);
-                    delete pending.verification_diagnostic;
-                    const delta = ToolsObserve.getLatestStateDelta(platform, deviceId);
-                    if (delta) {
-                        pending.state_delta = delta;
-                        pending.state_delta_available = true;
+                if (step.type === 'assert' && pendingLightStep !== null) {
+                    const pending = results[pendingLightStep].result;
+                    if (typeof result?.observed?.matched_count === 'number') {
+                        pending.verification.status = 'observed';
+                        if (pending.evidence)
+                            completeJourneyVerification(pending.evidence.action_id);
+                        delete pending.verification_diagnostic;
+                        const delta = ToolsObserve.getLatestStateDelta(platform, deviceId);
+                        if (delta) {
+                            pending.state_delta = delta;
+                            pending.state_delta_available = true;
+                        }
                     }
+                    pendingLightStep = null;
                 }
-                pendingLightStep = null;
-            }
-            if (responseMode === 'compact' && ['wait', 'assert'].includes(step.type))
-                result = {
-                    success, ...(result.failure_code ? { failure_code: result.failure_code } : {}),
-                    ...(result.error?.code ? { failure_code: result.error.code } : {}),
-                    ...(result.observed?.matched_count !== undefined ? { matched_count: result.observed.matched_count } : {}),
-                    ...(result.observed_fingerprint !== undefined ? { matched: success } : {}),
-                    ...(result.actual_state ? { observed: result.actual_state } : {})
-                };
-            results.push({ id: step.id, type: step.type, status: success ? 'passed' : 'failed', success, result, timing: { total_ms: performance.now() - stepStart } });
-            if (!success)
-                stoppedAt = step.id;
-        }
-        const failureSnapshot = stoppedAt && captureOnFailure && responseMode === 'debug'
-            ? await ToolsObserve.captureDebugSnapshotHandler({ platform, deviceId, includeScreenshot: false }).catch(() => null) : undefined;
-        const componentTiming = {};
-        for (const step of results)
-            for (const [key, value] of Object.entries(step.result?.timing ?? {})) {
-                if (key !== 'total_ms' && typeof value === 'number')
-                    componentTiming[key] = (componentTiming[key] ?? 0) + value;
+                if (responseMode === 'compact' && ['wait', 'assert'].includes(step.type))
+                    result = {
+                        success, ...(result.failure_code ? { failure_code: result.failure_code } : {}),
+                        ...(result.error?.code ? { failure_code: result.error.code } : {}),
+                        ...(result.observed?.matched_count !== undefined ? { matched_count: result.observed.matched_count } : {}),
+                        ...(result.observed_fingerprint !== undefined ? { matched: success } : {}),
+                        ...(result.actual_state ? { observed: result.actual_state } : {})
+                    };
+                results.push({ id: step.id, type: step.type, status: success ? 'passed' : 'failed', success, result, timing: { total_ms: performance.now() - stepStart } });
+                if (!success)
+                    stoppedAt = step.id;
             }
-        refreshJourneyEvidence(results);
-        return wrapResponse({ success: stoppedAt === null, stopped_at_step_id: stoppedAt, steps: results, ...(failureSnapshot ? { failure_snapshot: failureSnapshot } : {}), timing: responseMode === 'compact' ? { total_ms: performance.now() - started } : { ...componentTiming, total_ms: performance.now() - started } }, responseMode === 'debug');
-    });
+            const failureSnapshot = stoppedAt && captureOnFailure && responseMode === 'debug'
+                ? await ToolsObserve.captureDebugSnapshotHandler({ platform, deviceId, includeScreenshot: false }).catch(() => null) : undefined;
+            const componentTiming = {};
+            for (const step of results)
+                for (const [key, value] of Object.entries(step.result?.timing ?? {})) {
+                    if (key !== 'total_ms' && typeof value === 'number')
+                        componentTiming[key] = (componentTiming[key] ?? 0) + value;
+                }
+            refreshJourneyEvidence(results);
+            return wrapResponse({ ...(finishTrace ? { system_trace: await finishTrace() } : {}), success: stoppedAt === null, stopped_at_step_id: stoppedAt, steps: results, ...(failureSnapshot ? { failure_snapshot: failureSnapshot } : {}), timing: responseMode === 'compact' ? { total_ms: performance.now() - started } : { ...componentTiming, total_ms: performance.now() - started } }, responseMode === 'debug');
+        });
+    }
+    finally {
+        await finishTrace?.();
+    }
 }
 async function executeSwipe(args) {
     const platform = getStringArg(args, 'platform') ?? 'android';
@@ -808,7 +834,38 @@ async function handleGetNetworkActivity(args) {
     const result = await ToolsNetwork.getNetworkActivity({ platform, deviceId });
     return wrapResponse(result);
 }
+async function handleSystemTrace(name, args) {
+    const schema = name === 'start_system_trace' ? traceStartSchema : name === 'get_system_trace_capabilities' ? traceTargetSchema : traceControlSchema;
+    const parsed = schema.safeParse(args);
+    if (!parsed.success)
+        throw new TraceError('INVALID_ARGUMENT');
+    if (name === 'get_system_trace_capabilities' || name === 'start_system_trace') {
+        const target = parsed.data;
+        if (target.platform !== 'android') {
+            if (name === 'start_system_trace')
+                throw new TraceError('UNSUPPORTED_PLATFORM');
+            return wrapResponse({ supported: false, backend: 'perfetto', device: null, prerequisites: {}, reasons: ['UNSUPPORTED_PLATFORM'], enabled_sources: [], unavailable_categories: [], limitations: ['Android only'] });
+        }
+        let device;
+        try {
+            device = await resolveTargetDevice(target);
+        }
+        catch {
+            if (name === 'start_system_trace')
+                throw new TraceError('TRACE_UNSUPPORTED');
+            return wrapResponse({ supported: false, backend: 'perfetto', device: null, prerequisites: { device: false }, reasons: ['DEVICE_UNAVAILABLE'], enabled_sources: [], unavailable_categories: [], limitations: ['An authorised Android device is required'] });
+        }
+        if (name === 'get_system_trace_capabilities')
+            return wrapResponse(await systemTraces.capabilities(device.id));
+        const result = await systemTraces.start(device.id, target.durationMs);
+        return { ...wrapResponse(result), ...(result.state === 'failed' ? { isError: true } : {}) };
+    }
+    const operation = name === 'stop_system_trace' ? 'stop' : name === 'cancel_system_trace' ? 'cancel' : 'status';
+    const result = await systemTraces.control(parsed.data.traceId, operation);
+    return { ...wrapResponse(result), ...(['failed', 'cancelled'].includes(result.state) ? { isError: true } : {}) };
+}
 export const toolHandlers = {
+    ...Object.fromEntries(systemTraceTools.map(({ name }) => [name, (args) => handleSystemTrace(name, args)])),
     get_app_readiness: async (args) => {
         const parsed = readinessSchema.safeParse(args);
         if (!parsed.success)
@@ -860,7 +917,9 @@ export const toolHandlers = {
 for (const name of ['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'read_log_stream', 'run_journey', 'adjust_control']) {
     toolHandlers[name] = correlatedHandler(name, toolHandlers[name], name === 'adjust_control', name === 'run_journey');
 }
-export async function handleToolCall(name, args = {}) {
+export async function handleToolCall(name, args = {}, signal) {
+    if (Object.hasOwn(debuggerContracts, name))
+        return handleDebugger(name, args, signal);
     const handler = toolHandlers[name];
     if (!handler)
         throw new Error(`Unknown tool: ${name}`);
@@ -882,10 +941,58 @@ export async function handleToolCall(name, args = {}) {
     };
     return withTiming(measured, async () => {
         try {
-            validateExpectedState(name, args);
-            return addTiming(await handler(args));
+            if (!systemTraceToolNames.has(name))
+                validateExpectedState(name, args);
+            const guarded = ['start_app', 'terminate_app', 'restart_app', 'reset_app_data', 'install_app', 'build_and_install', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back', 'adjust_control', 'run_journey', 'wait_for_ui', 'wait_for_ui_change', 'wait_for_screen_change', 'expect_screen', 'expect_element_visible', 'expect_state'].includes(name);
+            if (guarded && args.platform !== 'ios' && debuggerSessions.hasActiveSessions()) {
+                const device = await resolveTargetDevice({ platform: 'android', deviceId: args.deviceId });
+                return withResolvedDevice(device, () => withDebuggerGuard('android', device.id, async () => {
+                    const before = debuggerSessions.paused(device.id);
+                    if (before)
+                        return wrapResponse({ success: false, failure_code: 'DEBUGGER_PAUSED', delivery_status: 'not_delivered', dispatch_started: false, debugger: before });
+                    let response;
+                    try {
+                        response = await handler(args);
+                    }
+                    catch (error) {
+                        if (!debuggerSessions.paused(device.id))
+                            throw error;
+                        response = wrapResponse({ success: false });
+                    }
+                    const pause = debuggerSessions.paused(device.id);
+                    if (pause) {
+                        const item = response.content.find(item => item.type === 'text');
+                        if (item?.text) {
+                            const payload = JSON.parse(item.text);
+                            Object.assign(payload, { success: false, failure_code: 'DEBUGGER_PAUSED', retryable: false,
+                                dispatch_started: guardDispatched(), delivery_status: payload.success ? 'delivered' : guardDispatched() ? 'unknown' : 'not_delivered',
+                                verification: { status: 'blocked', reason: 'DEBUGGER_PAUSED' }, debugger: pause });
+                            item.text = JSON.stringify(payload);
+                        }
+                    }
+                    return addTiming(response);
+                }));
+            }
+            const response = await handler(args);
+            if (['capture_screenshot', 'get_ui_tree', 'get_screen_fingerprint', 'capture_debug_snapshot', 'get_logs', 'get_current_screen', 'read_log_stream'].includes(name) && args.platform !== 'ios') {
+                const item = response.content.find(item => item.type === 'text');
+                if (item?.text) {
+                    try {
+                        const payload = JSON.parse(item.text);
+                        const device = payload.device ?? payload.evidence?.device;
+                        const id = device?.id ?? args.deviceId;
+                        const pause = id && device?.platform !== 'ios' ? debuggerSessions.paused(String(id)) : null;
+                        if (pause)
+                            item.text = JSON.stringify({ ...payload, debugger: pause });
+                    }
+                    catch { /* Non-JSON observation */ }
+                }
+            }
+            return addTiming(response);
         }
         catch (error) {
+            if (error instanceof TraceError)
+                return { ...wrapResponse({ error: { tool: name, code: error.code, message: error.message } }), isError: true };
             console.error(`Error executing tool ${name}:`, error);
             return addTiming(wrapToolError(name, error));
         }

package/dist/server-core.js

@@ -6,7 +6,7 @@ import { handleToolCall } from './server/tool-handlers.js';
 export { wrapResponse, toolDefinitions, handleToolCall };
 export const serverInfo = {
     name: 'mobile-debug-mcp',
-    version: '0.33.0'
+    version: '0.34.0'
 };
 export function createServer() {
     const server = new Server(serverInfo, {
@@ -27,9 +27,9 @@ export function createServer() {
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: toolDefinitions
     }));
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         const { name, arguments: args } = request.params;
-        return handleToolCall(name, args);
+        return handleToolCall(name, args, extra.signal);
     });
     return server;
 }

package/dist/server.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { debuggerSessions } from './debugger/sessions.js';
+import { systemTraces } from './observe/system-trace.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createServer } from './server-core.js';
 import { getSystemStatus } from './system/index.js';
@@ -9,6 +11,38 @@ if (process.env.MOBILE_DEBUG_MCP_STARTUP_HEALTHCHECK === '1') {
     }).catch((e) => console.warn('[startup] healthcheck failed:', e instanceof Error ? e.message : String(e)));
 }
 const transport = new StdioServerTransport();
+let shuttingDown = false;
+async function shutdown() {
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    const deadline = setTimeout(() => { console.error('System trace shutdown cleanup timed out; owned device captures remain duration-bounded.'); process.exit(1); }, 10000);
+    let exitCode = 0;
+    try {
+        const [remaining, debuggers] = await Promise.all([systemTraces.shutdown(), debuggerSessions.shutdown()]);
+        if (debuggers.length) {
+            exitCode = 1;
+            console.error('Debugger shutdown cleanup incomplete', debuggers.map(s => s.cleanup));
+        }
+        if (remaining.length) {
+            exitCode = 1;
+            console.error('System trace shutdown cleanup incomplete:', remaining.map(s => ({ trace_id: s.trace_id, device: s.device, cleanup: s.cleanup })));
+        }
+        await server.close();
+    }
+    catch {
+        exitCode = 1;
+        console.error('Server shutdown cleanup failed.');
+    }
+    finally {
+        clearTimeout(deadline);
+        process.exit(exitCode);
+    }
+}
+server.onclose = () => { void shutdown(); };
+process.stdin.on('end', () => { void shutdown(); });
+process.on('SIGINT', () => { void shutdown(); });
+process.on('SIGTERM', () => { void shutdown(); });
 async function main() {
     await server.connect(transport);
 }

package/dist/system/index.js

@@ -221,7 +221,7 @@ function buildAndroidPlatform(android, hostSupported) {
         },
         providers: {
             adb: { available: adbAvailable, selected: true, tool: 'adb' },
-            jdwp: { available: adbAvailable && android.devices > 0, selected: false, tool: 'adb' }
+            jdwp: { available: false, selected: false, tool: 'adb', probeRequired: 'get_debugger_capabilities' }
         },
         capabilities: {
             device_discovery: {
@@ -255,9 +255,10 @@ function buildAndroidPlatform(android, hostSupported) {
                 blockingFailure: logAvailable ? null : adbFailure ?? envFailure
             },
             debug: {
-                availability: adbAvailable && android.devices > 0,
-                selectedProvider: adbAvailable && android.devices > 0 ? 'JDWP' : null,
-                blockingFailure: adbAvailable && android.devices > 0 ? null : deviceFailure ?? adbFailure ?? envFailure
+                probeRequired: 'get_debugger_capabilities',
+                availability: false,
+                selectedProvider: null,
+                blockingFailure: deviceFailure ?? adbFailure ?? envFailure
             }
         },
         devices: deviceEntries,

package/dist/utils/exec.js

@@ -1,9 +1,11 @@
+import { checkDebuggerGuard } from '../debugger/guard.js';
 import { remainingBudget } from './operation-budget.js';
 import { spawn } from 'child_process';
 export async function execCmd(cmd, args, opts = {}) {
     const { env, cwd, shell } = opts;
     const timeout = remainingBudget(opts.timeout ?? 0);
     return new Promise((resolve, reject) => {
+        checkDebuggerGuard();
         const child = spawn(cmd, args, { env: { ...process.env, ...(env || {}) }, cwd, shell });
         let stdout = '';
         let stderr = '';

package/dist/utils/java.js

@@ -25,17 +25,19 @@ function javaVersionOf(javaBin) {
         return undefined;
     }
 }
-export async function detectJavaHome() {
+export async function detectJavaHome(options = {}) {
+    const debug = (...args) => { if (!options.quiet)
+        console.debug(...args); };
     try {
         // 1) Honor explicit ANDROID_STUDIO_JDK env (highest priority)
         const envStudio = process.env.ANDROID_STUDIO_JDK || process.env.ANDROID_STUDIO_JBR;
         if (envStudio && existsSync(path.join(envStudio, 'bin', 'java'))) {
             const v = javaVersionOf(path.join(envStudio, 'bin', 'java'));
             if (isJavaVersionAcceptable(v)) {
-                console.debug('[java.detect] Using ANDROID_STUDIO_JDK from env:', envStudio);
+                debug('[java.detect] Using ANDROID_STUDIO_JDK from env:', envStudio);
                 return envStudio;
             }
-            console.debug('[java.detect] ANDROID_STUDIO_JDK present but java -version did not match expected versions');
+            debug('[java.detect] ANDROID_STUDIO_JDK present but java -version did not match expected versions');
         }
         // 2) Android Studio JBR candidates (prefer these over JAVA_HOME)
         const jbrCandidates = [
@@ -53,7 +55,7 @@ export async function detectJavaHome() {
             if (existsSync(javaBin)) {
                 const v = javaVersionOf(javaBin);
                 if (isJavaVersionAcceptable(v)) {
-                    console.debug('[java.detect] Found Android Studio JBR at:', p);
+                    debug('[java.detect] Found Android Studio JBR at:', p);
                     return p;
                 }
             }
@@ -64,13 +66,13 @@ export async function detectJavaHome() {
                 const javaBin = path.join(process.env.JAVA_HOME, 'bin', 'java');
                 const v = javaVersionOf(javaBin);
                 if (isJavaVersionAcceptable(v)) {
-                    console.debug('[java.detect] Using JAVA_HOME from env:', process.env.JAVA_HOME);
+                    debug('[java.detect] Using JAVA_HOME from env:', process.env.JAVA_HOME);
                     return process.env.JAVA_HOME;
                 }
-                console.debug('[java.detect] Existing JAVA_HOME does not appear to be acceptable Java (17/21), will search');
+                debug('[java.detect] Existing JAVA_HOME does not appear to be acceptable Java (17/21), will search');
             }
             catch {
-                console.debug('[java.detect] Failed to validate existing JAVA_HOME, searching for JDK');
+                debug('[java.detect] Failed to validate existing JAVA_HOME, searching for JDK');
             }
         }
         // 4) macOS explicit path for JDK 17
@@ -84,7 +86,7 @@ export async function detectJavaHome() {
                 return out17;
         }
         catch (e) {
-            console.debug('[java.detect] /usr/libexec/java_home -v 17 failed: ' + String(e));
+            debug('[java.detect] /usr/libexec/java_home -v 17 failed: ' + String(e));
         }
         try {
             const out21 = execSync('/usr/libexec/java_home -v 21', { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
@@ -92,7 +94,7 @@ export async function detectJavaHome() {
                 return out21;
         }
         catch (e) {
-            console.debug('[java.detect] /usr/libexec/java_home -v 21 failed: ' + String(e));
+            debug('[java.detect] /usr/libexec/java_home -v 21 failed: ' + String(e));
         }
         // 6) macOS common JDK locations
         try {
@@ -105,7 +107,7 @@ export async function detectJavaHome() {
             }
         }
         catch (e) {
-            console.debug('[java.detect] listing /Library/Java/JavaVirtualMachines failed: ' + String(e));
+            debug('[java.detect] listing /Library/Java/JavaVirtualMachines failed: ' + String(e));
         }
         // 7) Linux locations
         const linuxCandidates = [
@@ -122,12 +124,12 @@ export async function detectJavaHome() {
                     return p;
             }
             catch (e) {
-                console.debug(`[java.detect] checking linux candidate ${p} failed: ${String(e)}`);
+                debug(`[java.detect] checking linux candidate ${p} failed: ${String(e)}`);
             }
         }
     }
     catch (e) {
-        console.debug('[java.detect] error detecting java home:', e instanceof Error ? e.message : String(e));
+        debug('[java.detect] error detecting java home:', e instanceof Error ? e.message : String(e));
     }
     return undefined;
 }

package/dist/utils/operation-budget.js

@@ -1,3 +1,4 @@
+import { checkDebuggerGuard } from '../debugger/guard.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
 const budgets = new AsyncLocalStorage();
 export function hasFiniteBudget() { return Number.isFinite(budgets.getStore()?.deadline); }
@@ -38,6 +39,7 @@ export async function runWithSeparateBudget(timeoutMs, operation) {
     }
 }
 export function markDispatchStarted() {
+    checkDebuggerGuard(true);
     remainingBudget();
     let budget = budgets.getStore();
     while (budget) {

package/dist/utils/resolve-device.js

@@ -1,3 +1,4 @@
+import { checkDebuggerGuard } from '../debugger/guard.js';
 import { bindEvidenceDevice } from '../observe/evidence.js';
 import { retainConnectedDeviceSnapshots } from '../observe/snapshot-metadata.js';
 import { measure } from './timing.js';
@@ -42,6 +43,7 @@ export function withResolvedDevice(device, operation) {
     return deviceContext.run(device, operation);
 }
 export async function resolveTargetDevice(opts) {
+    checkDebuggerGuard();
     const device = await resolveDevice(opts);
     bindEvidenceDevice(device);
     return device;

package/docs/CHANGELOG.md

@@ -3,6 +3,10 @@
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
 ## Unreleased
+
+## [0.34.0]
+- Added optional Android JDI runtime debugging: explicit device/process attach, source breakpoints/events, bounded stacks and shallow locals, stepping/resume, stale-reference rejection, pause-aware UI guards/readiness, expiry and owned detach/cleanup. Requires a host JDK 17+ and a running debuggable app; evaluation, mutation, native/coroutine and iOS debugging remain unsupported.
+- Added optional bounded Android Perfetto capture with capability/start/status/stop/cancel tools, explicit journey trace linkage, local artifacts, process-ownership checks and retryable cleanup. iOS tracing and automatic trace analysis remain unsupported.
 - Made readiness unit-test polling time deterministic while retaining exact sample-count and timeout assertions, eliminating host timer-rounding flakes.
 - Isolated snapshot unit tests from physical device discovery and native handlers so they run without connected devices. Readiness deadline expiry now retains the last valid observation instead of intermittently resetting loading to unknown.