mobile-debug-mcp 0.35.0 → 0.37.0

package/dist/debugger/sessions.js

@@ -1,11 +1,13 @@
 import { atStage, classify, diagnostic } from './diagnostics.js';
 import { registerDebuggerPauseProvider } from './guard.js';
+import { IOSDebugNative } from './ios.js';
+import { createIOSWorker, prepareIOSWorker, iosCapabilities, iosLimitations } from './ios-worker.js';
 import { randomUUID } from 'node:crypto';
 import { AndroidDebugNative } from './android.js';
 import { createWorker, prepareWorker, DebuggerError, withDebuggerBudget, debuggerRemaining } from './worker.js';
 export const debuggerCapabilities = { attach: true, breakpoints: true, stacks: true, locals: true, step: true, resume: true,
     evaluation: false, mutation: false, coroutines: false, native: false };
-const limitations = ['JAVA_KOTLIN_BYTECODE_ONLY', 'DEBUG_METADATA_REQUIRED', 'SHALLOW_LOCALS', 'ALL_THREADS_SUSPEND', 'DEVICE_WIDE_UI_GUARD'];
+export const androidLimitations = ['JAVA_KOTLIN_BYTECODE_ONLY', 'DEBUG_METADATA_REQUIRED', 'SHALLOW_LOCALS', 'ALL_THREADS_SUSPEND', 'DEVICE_WIDE_UI_GUARD'];
 export function debuggerExpiry(created, activity, pausedAt, now) {
     return pausedAt !== undefined && now - pausedAt >= 60000 ? 'pause_limit' : now - activity >= 300000 ? 'idle_limit' : now - created >= 1800000 ? 'session_limit' : null;
 }
@@ -13,13 +15,17 @@ export class DebuggerSessions {
     native;
     workerFactory;
     prerequisite;
+    options;
     sessions = new Map();
     closing = false;
-    constructor(native = new AndroidDebugNative(), workerFactory = createWorker, prerequisite = prepareWorker) {
+    constructor(native = new AndroidDebugNative(), workerFactory = createWorker, prerequisite = prepareWorker, options = {}) {
         this.native = native;
         this.workerFactory = workerFactory;
         this.prerequisite = prerequisite;
+        this.options = options;
     }
+    get platform() { return this.options.platform ?? 'android'; }
+    get workerResource() { return this.platform === 'ios' ? 'lldb_worker' : 'jdi_worker'; }
     prune() {
         const terminal = [...this.sessions.values()].filter(s => s.terminalAt !== undefined && s.cleanup.status === 'complete');
         for (const s of terminal)
@@ -42,9 +48,10 @@ export class DebuggerSessions {
         const success = payload.success ?? (!['failed', 'disconnected'].includes(s.state) && s.cleanup.status !== 'failed');
         const code = s.cleanup.status === 'failed' ? 'DEBUGGER_CLEANUP_FAILED' : s.state === 'disconnected' ? 'DEBUGGER_DISCONNECTED' : s.reason?.match(/^[A-Z_]+$/) ? s.reason : 'DEBUGGER_WORKER_FAILED';
         return structuredClone({ success, ...(!success ? { error: { code, message: code, retryable: false, diagnostic: s.cleanup.status === 'failed' ? diagnostic('cleanup', 'operation_failed') : s.diagnostic ?? diagnostic('unknown', 'unknown') } } : {}), debug_session_id: s.id,
-            device: { platform: 'android', id: s.device }, target: s.target, state: s.state, captured_at_ms: Date.now(),
-            capabilities: debuggerCapabilities, limitations, cleanup: s.cleanup, reason: s.reason, stop: s.stop, ...payload });
+            device: { platform: this.platform, id: s.device }, target: s.target, state: s.state, captured_at_ms: Date.now(),
+            capabilities: this.options.capabilities ?? debuggerCapabilities, limitations: this.options.limitations ?? androidLimitations, cleanup: s.cleanup, reason: s.reason, stop: s.stop, ...payload });
     }
+    owns(id) { return this.sessions.has(id); }
     summary(id) { return this.result(this.get(id)); }
     hasActiveSessions() { return [...this.sessions.values()].some(s => s.cleanup.status !== 'complete'); }
     paused(device) { const s = [...this.sessions.values()].find(s => s.device === device && s.state === 'paused'); return s ? this.result(s) : null; }
@@ -77,13 +84,13 @@ export class DebuggerSessions {
             s.events.shift();
     }
     async capabilities(device, app, pid) {
-        const prerequisites = { jdk: false, device: false, process: false };
+        const prerequisites = { [this.platform === 'ios' ? 'lldb' : 'jdk']: false, device: false, process: false };
         let candidates = [];
         const reasons = [];
         const diagnostics = [];
         try {
             await atStage('prerequisite', 'DEBUGGER_UNSUPPORTED', () => this.prerequisite());
-            prerequisites.jdk = true;
+            prerequisites[this.platform === 'ios' ? 'lldb' : 'jdk'] = true;
         }
         catch (e) {
             if (e instanceof DebuggerError && ['DEBUGGER_TIMEOUT', 'DEBUGGER_CANCELLED'].includes(e.code))
@@ -106,9 +113,9 @@ export class DebuggerSessions {
             reasons.push(e instanceof DebuggerError ? e.code : 'DEVICE_UNAVAILABLE');
             diagnostics.push(classify(e, 'target_resolution', 'DEVICE_UNAVAILABLE').diagnostic ?? diagnostic('target_resolution', 'unknown'));
         }
-        return { success: true, debug_session_id: null, device: { platform: 'android', id: device }, target: null, state: null,
+        return { success: true, debug_session_id: null, device: { platform: this.platform, id: device }, target: null, state: null,
             captured_at_ms: Date.now(), supported: Object.values(prerequisites).every(Boolean), prerequisites, candidates,
-            ...(diagnostics.length ? { diagnostics } : {}), capabilities: debuggerCapabilities, reasons, limitations, cleanup: { status: 'complete', remaining_resources: [] } };
+            ...(diagnostics.length ? { diagnostics } : {}), capabilities: this.options.capabilities ?? debuggerCapabilities, reasons, limitations: this.options.limitations ?? androidLimitations, cleanup: { status: 'complete', remaining_resources: [] } };
     }
     async attach(device, app, pid, timeout = 10000) {
         this.prune();
@@ -144,16 +151,20 @@ export class DebuggerSessions {
                 if (candidates.length > 1)
                     throw new DebuggerError('PROCESS_AMBIGUOUS');
                 s.target = candidates[0];
-                stage = 'forwarding';
-                s.port = await atStage('forwarding', 'DEBUGGER_ATTACH_FAILED', () => this.native.forward(device, s.target.pid));
-                remaining();
-                s.cleanup.remaining_resources.push(`forward:tcp:${s.port}`);
+                if (this.platform === 'android') {
+                    stage = 'forwarding';
+                    s.port = await atStage('forwarding', 'DEBUGGER_ATTACH_FAILED', () => this.native.forward(device, s.target.pid));
+                    remaining();
+                    s.cleanup.remaining_resources.push(`forward:tcp:${s.port}`);
+                }
                 stage = 'worker_start';
                 s.worker = await atStage('worker_start', 'DEBUGGER_ATTACH_FAILED', () => this.workerFactory(event => this.event(s, event)));
                 remaining();
-                s.cleanup.remaining_resources.push('jdi_worker');
+                s.cleanup.remaining_resources.push(this.workerResource);
+                if (this.platform === 'ios')
+                    await atStage('target_resolution', 'DEBUGGER_ATTACH_FAILED', () => this.native.identity(device, s.target));
                 stage = 'attach';
-                await atStage('attach', 'DEBUGGER_ATTACH_FAILED', () => s.worker.call('attach', { port: s.port, timeoutMs: remaining() }, remaining()));
+                await atStage('attach', 'DEBUGGER_ATTACH_FAILED', () => s.worker.call('attach', { port: s.port, ...(this.platform === 'ios' ? { pid: s.target.pid, executablePath: s.target.executable_path } : {}), timeoutMs: remaining() }, remaining()));
                 stage = 'target_resolution';
                 await atStage('target_resolution', 'DEBUGGER_ATTACH_FAILED', () => this.native.identity(device, s.target));
                 remaining();
@@ -204,7 +215,7 @@ export class DebuggerSessions {
                     s.worker = undefined;
                 }
                 catch {
-                    remaining.push('jdi_worker');
+                    remaining.push(this.workerResource);
                 }
             }
             if (s.port !== undefined && s.target) {
@@ -252,6 +263,8 @@ export class DebuggerSessions {
     assertCommandTarget(s, command, args) {
         if (!s.worker || ['detaching', 'detached', 'disconnected', 'failed'].includes(s.state))
             throw new DebuggerError('DEBUGGER_DISCONNECTED', s.diagnostic ?? diagnostic('command', 'unavailable'));
+        if (command === 'set' && (this.platform === 'ios' ? typeof args.sourceFile !== 'string' || args.className !== undefined : typeof args.className !== 'string' || args.sourceFile !== undefined))
+            throw new DebuggerError('INVALID_ARGUMENT');
         if (['stack', 'locals', 'step', 'resume'].includes(command)) {
             if (args.stopId !== s.stop?.stop_id)
                 throw new DebuggerError('DEBUGGER_STALE_REFERENCE');
@@ -268,6 +281,7 @@ export class DebuggerSessions {
         if (command === 'state' && (s.cleanup.status === 'complete' || ['detaching', 'detached', 'disconnected', 'failed'].includes(s.state)))
             return this.result(s);
         this.assertCommandTarget(s, command, args);
+        const previous = { state: s.state, stop: s.stop, pausedAt: s.pausedAt };
         if (command === 'step' || command === 'resume') {
             s.state = 'running';
             s.stop = null;
@@ -278,6 +292,8 @@ export class DebuggerSessions {
             return this.result(s, command === 'state' ? { breakpoints: data.breakpoints } : { result: data });
         }
         catch (e) {
+            if (['step', 'resume'].includes(command) && s.state === 'running' && s.stop === null && e instanceof DebuggerError && ['INVALID_ARGUMENT', 'DEBUGGER_STALE_REFERENCE'].includes(e.code))
+                Object.assign(s, previous);
             return this.handleCommandError(s, command, classify(e, 'command', 'DEBUGGER_WORKER_FAILED'));
         }
     }
@@ -301,4 +317,5 @@ export class DebuggerSessions {
     async shutdown() { this.closing = true; await Promise.allSettled([...this.sessions.values()].filter(s => s.cleanup.status !== 'complete').map(s => this.serial(s, () => this.cleanup(s, true)))); return [...this.sessions.values()].filter(s => s.cleanup.status !== 'complete').map(s => this.result(s)); }
 }
 export const debuggerSessions = new DebuggerSessions();
-registerDebuggerPauseProvider(device => debuggerSessions.paused(device));
+export const iosDebuggerSessions = new DebuggerSessions(new IOSDebugNative(), createIOSWorker, prepareIOSWorker, { platform: 'ios', capabilities: iosCapabilities, limitations: iosLimitations });
+registerDebuggerPauseProvider((device, platform = 'android') => (platform === 'ios' ? iosDebuggerSessions : debuggerSessions).paused(device));

package/dist/debugger/worker.js

@@ -63,7 +63,7 @@ export async function prepareWorker() {
     return compiled;
 }
 function commandStage(command) { return command === 'attach' ? 'attach' : command === 'detach' ? 'cleanup' : 'command'; }
-export class JdiWorker {
+export class DebuggerProcess {
     onEvent;
     child;
     pending = new Map();
@@ -72,9 +72,9 @@ export class JdiWorker {
     failure;
     replied = false;
     exited;
-    constructor(java, directory, onEvent) {
+    constructor(java, directory, onEvent, launch) {
         this.onEvent = onEvent;
-        this.child = spawn(java, ['-Xmx128m', '--add-modules', 'jdk.jdi', '-cp', directory, 'DebuggerWorker'], { stdio: ['pipe', 'pipe', 'pipe'] });
+        this.child = spawn(java, launch?.args ?? ['-Xmx128m', '--add-modules', 'jdk.jdi', '-cp', directory, 'DebuggerWorker'], { stdio: ['pipe', 'pipe', 'pipe'], ...(launch ? { env: launch.env } : {}) });
         let buffer = '';
         this.exited = new Promise(resolve => { this.child.once('exit', () => { this.fail('process_exited'); resolve(); }); this.child.once('error', () => { this.fail('spawn_failed'); resolve(); }); });
         this.child.stdin.on('error', () => this.fail('write_failed'));
@@ -172,5 +172,7 @@ export class JdiWorker {
 }
 export async function createWorker(onEvent) {
     const { java, directory } = await prepareWorker();
-    return new JdiWorker(java, directory, onEvent);
+    return new DebuggerProcess(java, directory, onEvent);
 }
+// Compatibility export for existing JDI transport callers/tests.
+export { DebuggerProcess as JdiWorker };

package/dist/interact/index.js

@@ -105,11 +105,21 @@ export class ToolsInteract {
         const { interact, resolved } = await ToolsInteract.getInteractionService(platform, deviceId);
         return await interact.tap(x, y, resolved.id, timeoutMs);
     }
+    static _getResolvedElement(elementId, platform, deviceId) {
+        const resolved = ToolsInteract._resolvedUiElements.get(elementId);
+        if (!resolved || (platform && resolved.platform !== platform) || (deviceId && resolved.deviceId !== deviceId))
+            return null;
+        return resolved;
+    }
+    static getResolvedElementTarget(elementId, platform, deviceId) {
+        const resolved = ToolsInteract._getResolvedElement(elementId, platform, deviceId);
+        return resolved ? { platform: resolved.platform, deviceId: resolved.deviceId } : null;
+    }
     static async tapElementHandler({ elementId, verificationMode = 'full', timeoutMs, platform, deviceId, freshTree }) {
         const actionType = 'tap_element';
         const selector = { elementId };
-        const resolved = ToolsInteract._resolvedUiElements.get(elementId);
-        if (!resolved || (platform && resolved.platform !== platform) || (deviceId && resolved.deviceId !== deviceId)) {
+        const resolved = ToolsInteract._getResolvedElement(elementId, platform, deviceId);
+        if (!resolved) {
             return ToolsInteract._actionFailure(actionType, selector, null, 'STALE_REFERENCE', true, null);
         }
         const fingerprintBefore = verificationMode === 'full' ? await ToolsInteract._captureFingerprint(resolved.platform, resolved.deviceId) : null;

package/dist/interact/waits/ui-change-wait.js

@@ -1,7 +1,7 @@
 import { systemClock } from '../../runtime/clock.js';
 import { remainingBudget } from '../../utils/operation-budget.js';
 import { checkDebuggerGuard } from '../../debugger/guard.js';
-import { observeReadinessWait, isDeviceUnavailable } from '../../observe/readiness.js';
+import { observeReadinessWait, observeReadinessDeviceWait, isDeviceUnavailable } from '../../observe/readiness.js';
 import { readinessDelay } from '../../observe/readiness-service.js';
 import { _buildUiChangeSignatures, _summarizeUiChangeDelta, _matchesUiChange, _uiChangeSignaturesEqual } from './ui-change-helpers.js';
 import { createChangeWait, changeResult } from './ui-change-state.js';
@@ -26,12 +26,19 @@ function changed(s, signatures) {
         s.since = s.clock.now();
     }
     const stable = s.since === null ? 0 : s.clock.now() - s.since;
-    return (s.stability === 0 || stable >= s.stability) && (!s.tracker || s.tracker.summary.state === 'settled');
+    return (s.stability === 0 || stable >= s.stability) && (!s.tracker || s.tracker.ready);
 }
 async function sample(s, deps) {
     if (s.tracker)
         remainingBudget();
     const started = s.clock.now(), a = s.input;
+    await observeReadinessDeviceWait();
+    if (s.tracker?.deviceReadiness.input_ready === false) {
+        s.candidate = null;
+        s.change = null;
+        s.since = null;
+        return null;
+    }
     const tree = await deps.observe({ platform: a.platform, deviceId: a.deviceId });
     observeReadinessWait(tree, started);
     const scoped = deps.scope(tree, a.scope, a.target);

package/dist/interact/waits/ui-wait.js

@@ -1,12 +1,13 @@
 import { systemClock } from '../../runtime/clock.js';
+import { benchmarkStage } from '../../utils/benchmark-metrics.js';
 import { remainingBudget } from '../../utils/operation-budget.js';
 import { checkDebuggerGuard } from '../../debugger/guard.js';
-import { observeReadinessWait, isDeviceUnavailable } from '../../observe/readiness.js';
+import { observeReadinessWait, observeReadinessDeviceWait, isDeviceUnavailable } from '../../observe/readiness.js';
 import { readinessDelay } from '../../observe/readiness-service.js';
 import { matchingElements, evaluateCondition } from './ui-wait-condition.js';
 import { createUIWait, validateUIWait, waitObserved, waitFailure } from './ui-wait-state.js';
 async function delay(s, ms) {
-    await (s.tracker && s.clock === systemClock ? readinessDelay(ms) : s.clock.sleep(ms));
+    await benchmarkStage('poll_sleep_ms', () => s.tracker && s.clock === systemClock ? readinessDelay(ms) : s.clock.sleep(ms));
 }
 function acceptObservation(s, tree, now) {
     const age = typeof tree?.captured_at_ms === 'number' ? now - tree.captured_at_ms : null;
@@ -15,7 +16,7 @@ function acceptObservation(s, tree, now) {
         return null;
     }
     s.stable++;
-    if (s.stable < (s.args.singleObservation ? 1 : 2) || (s.tracker && s.tracker.summary.state !== 'settled'))
+    if (s.stable < (s.args.singleObservation ? 1 : 2) || (s.tracker && !s.tracker.ready))
         return null;
     return { status: 'success', ...(s.args.singleObservation ? { _tree: tree } : {}), matched: s.count,
         element: s.element, metrics: { latency_ms: now - s.start, poll_count: s.polls, attempts: s.attempts }, requested: s.requested, observed: waitObserved(s, true) };
@@ -50,6 +51,9 @@ async function poll(s, deps) {
     s.polls++;
     try {
         const started = s.clock.now(), a = s.args;
+        await observeReadinessDeviceWait();
+        if (s.tracker?.deviceReadiness.input_ready === false)
+            return null;
         const tree = await deps.observe({ platform: a.platform, deviceId: a.deviceId });
         observeReadinessWait(tree, started);
         if (a.resolveTapTarget && tree?.error && /ACTION_TIMEOUT|timed out/i.test(String(tree.error)))

package/dist/manage/index.js

@@ -1,3 +1,4 @@
+import { validAppId } from '../utils/app-installation.js';
 import { promises as fs } from 'fs';
 import path from 'path';
 import { resolveTargetDevice, listDevices } from '../utils/resolve-device.js';
@@ -313,6 +314,8 @@ export class ToolsManage {
         }
     }
     static async listDevicesHandler({ platform, appId }) {
+        if (appId !== undefined && !validAppId(appId))
+            throw new Error('Invalid appId');
         const devices = await listDevices(platform, appId);
         return { devices };
     }

package/dist/manage/ios.js

@@ -1,3 +1,4 @@
+import { checkDebuggerGuard } from '../debugger/guard.js';
 import { buildIOS } from './ios/build.js';
 import { evidenceDispatch } from '../observe/evidence.js';
 import { hasFiniteBudget, markDispatchStarted, remainingBudget, runWithBudget } from '../utils/operation-budget.js';
@@ -156,6 +157,7 @@ export class iOSManage {
 }
 async function installWithIdb(toInstall, deviceId) {
     await new Promise((resolve, reject) => {
+        checkDebuggerGuard(true);
         const proc = spawn(getIdbCmd(), ['install', toInstall, '--udid', deviceId]);
         let stderr = '';
         proc.stderr.on('data', d => stderr += d.toString());

package/dist/observe/device-readiness.js

@@ -0,0 +1,116 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { pausedReadiness } from '../debugger/guard.js';
+import { execCmd } from '../utils/exec.js';
+import { getAdbCmd } from '../utils/android/commands.js';
+import { getXcrunCmd } from '../utils/ios/utils.js';
+import { remainingBudget } from '../utils/operation-budget.js';
+import { benchmarkStage } from '../utils/benchmark-metrics.js';
+export function unknownDeviceReadiness(code) {
+    return { wakefulness: 'unknown', lock_state: 'unknown', input_ready: null, blockers: [], evidence: [], limitations: code ? [code] : [] };
+}
+function values(text, pattern) { return [...text.matchAll(pattern)].map(match => match[1]); }
+function unique(items) { return items.length > 0 && new Set(items).size === 1 ? items[0] : null; }
+export function parseAndroidPower(text) {
+    // Later vendor/debug sections can repeat mWakefulness as a numeric enum.
+    // Classify only the named current-state section when its boundary is present.
+    const main = text.split('Power Manager State:')[1];
+    if (main?.includes('Settings and Configuration:'))
+        text = main.split('Settings and Configuration:')[0];
+    const wake = unique(values(text, /^\s*mWakefulness=(\w+)\s*$/gm));
+    const changing = unique(values(text, /^\s*mWakefulnessChanging=(true|false)\s*$/gm));
+    if (!wake || !changing)
+        return 'unknown';
+    if (changing === 'true')
+        return 'transitioning';
+    return wake === 'Awake' ? 'awake' : ['Asleep', 'Dozing'].includes(wake) ? 'asleep' : 'unknown';
+}
+export function parseAndroidLock(text) {
+    const section = text.split(/\bKeyguardServiceDelegate\s*\n/)[1];
+    if (!section)
+        return 'unknown';
+    const showing = unique(values(section, /^\s*(?:showing|mIsShowing)=(true|false)\s*$/gm));
+    return showing === 'true' ? 'locked' : showing === 'false' ? 'unlocked' : 'unknown';
+}
+export function finishDeviceReadiness(state) {
+    if (state.wakefulness === 'asleep')
+        state.blockers.push('DEVICE_ASLEEP');
+    if (state.wakefulness === 'transitioning')
+        state.blockers.push('DEVICE_TRANSITIONING');
+    if (state.lock_state === 'locked')
+        state.blockers.push('DEVICE_LOCKED');
+    state.blockers = [...new Set(state.blockers)];
+    state.input_ready = state.blockers.length ? false : null;
+    return state;
+}
+export function parseIosLock(text) {
+    try {
+        const data = JSON.parse(text);
+        if (data.error?.domain === 'com.apple.dt.CoreDeviceError' && data.error.code === 1001 &&
+            data.error.userInfo?.CapabilityFeatureIdentifier?.string === 'com.apple.coredevice.feature.getlockstate')
+            return 'unsupported';
+        // Successful response semantics require runtime validation before classification.
+    }
+    catch { /* Non-JSON output supplies no state evidence. */ }
+    return 'unknown';
+}
+const probes = new AsyncLocalStorage();
+export function withDeviceReadinessProbe(probe, operation) { return probes.run(probe, operation); }
+const nativeProbe = (command, args, timeout) => execCmd(command, args, { timeout });
+export async function observeDeviceReadiness(device, probe = probes.getStore() ?? nativeProbe) {
+    return benchmarkStage('device_readiness_ms', () => observe(device, probe));
+}
+async function observe(device, probe) {
+    const state = unknownDeviceReadiness();
+    if (!device?.id || !['android', 'ios'].includes(device.platform) || ['booted', 'default'].includes(device.id))
+        return unknownDeviceReadiness('DEVICE_TARGET_UNAVAILABLE');
+    const paused = pausedReadiness(device.id, device.platform);
+    if (paused) {
+        state.blockers.push('DEBUGGER_PAUSED');
+        state.evidence.push({ code: 'DEBUGGER_PAUSED', source: 'debugger', captured_at_ms: paused.captured_at_ms });
+        return finishDeviceReadiness(state);
+    }
+    if (device.platform === 'android') {
+        await androidProbe(state, device.id, 'power', probe);
+        await androidProbe(state, device.id, 'window', probe);
+    }
+    else {
+        state.limitations.push('DEVICE_WAKEFULNESS_UNVERIFIED');
+        try {
+            const timeout = remainingBudget(1000);
+            // CoreDevice requires a CLI timeout of at least five seconds; the parent
+            // subprocess deadline still caps this read at one second.
+            const result = await probe(getXcrunCmd(), ['devicectl', 'device', 'info', 'lockState', '--device', device.id, '--timeout', '5', '--json-output', '-'], timeout);
+            remainingBudget();
+            state.lock_state = parseIosLock(result.stdout);
+            if (state.lock_state === 'unsupported')
+                state.evidence.push({ code: 'DEVICE_LOCK_SIGNAL_UNSUPPORTED', source: 'coredevice', captured_at_ms: Date.now() });
+            else
+                state.limitations.push('DEVICE_LOCK_OBSERVATION_UNAVAILABLE');
+        }
+        catch {
+            state.limitations.push('DEVICE_LOCK_OBSERVATION_FAILED');
+        }
+    }
+    return finishDeviceReadiness(state);
+}
+async function androidProbe(state, id, kind, probe) {
+    try {
+        const timeout = remainingBudget(1000);
+        const result = await probe(getAdbCmd(), ['-s', id, 'shell', 'dumpsys', kind, ...(kind === 'window' ? ['policy'] : [])], timeout);
+        remainingBudget();
+        if (result.exitCode !== 0)
+            throw new Error('PROBE_FAILED');
+        const value = kind === 'power' ? parseAndroidPower(result.stdout) : parseAndroidLock(result.stdout);
+        if (kind === 'power')
+            state.wakefulness = value;
+        else
+            state.lock_state = value;
+        if (value === 'unknown')
+            state.limitations.push(kind === 'power' ? 'DEVICE_WAKEFULNESS_UNVERIFIED' : 'DEVICE_LOCK_STATE_UNVERIFIED');
+        else
+            state.evidence.push({ code: `DEVICE_${value.toUpperCase()}`, source: `android_${kind}`, captured_at_ms: Date.now() });
+    }
+    catch {
+        state.limitations.push(kind === 'power' ? 'DEVICE_POWER_OBSERVATION_FAILED' : 'DEVICE_LOCK_OBSERVATION_FAILED');
+    }
+}

package/dist/observe/evidence.js

@@ -217,11 +217,21 @@ export function refreshJourneyEvidence(steps) {
         const child = current.children.find(c => c.action?.id === previous?.action_id);
         if (child && step.result)
             step.result.evidence = assemble(child);
+        else if (previous?.observations && step.result) {
+            const ids = new Set(previous.observations.map(o => o.evidence_id));
+            step.result.evidence = assemble({ ...current, observations: current.observations.filter(o => ids.has(o.value.evidence_id)) });
+        }
     }
 }
 export function completeJourneyVerification(actionId) {
     const child = context.getStore()?.children.find(c => c.action?.id === actionId);
     if (child?.action) {
+        const parent = context.getStore();
+        const completed = child.action.dispatchEnd?.mono;
+        if (completed !== undefined) {
+            const after = parent.observations.filter(o => o.start.mono >= completed && sameDevice(o.value.device, child.action.device));
+            child.observations.push(...after);
+        }
         child.verification = stamp();
         child.action.verification = child.verification;
     }
@@ -317,3 +327,24 @@ function recordCaptureTime(acquisition, result, start) {
         acquisition.reused = source < start.wall;
     }
 }
+export class JourneyStepError extends Error {
+    evidence;
+    constructor(evidence, cause) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+        this.evidence = evidence;
+    }
+}
+/** Retain per-step evidence without changing the parent journey's acquisition flow. */
+export async function withJourneyStepEvidence(operation) {
+    const current = context.getStore();
+    const start = current?.observations.length ?? 0;
+    try {
+        const result = await operation();
+        return { ...result, ...(current ? { evidence: assemble({ ...current, observations: current.observations.slice(start) }) } : {}) };
+    }
+    catch (error) {
+        if (current)
+            throw new JourneyStepError(assemble({ ...current, observations: current.observations.slice(start) }), error);
+        throw error;
+    }
+}

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

@@ -0,0 +1,63 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { XMLParser, XMLValidator } from 'fast-xml-parser';
+import { getXcrunCmd } from '../../utils/ios/utils.js';
+import { traceCommand, spawnTrace } from './process.js';
+export const IOS_TRACE_MAX_BYTES = 256 * 1024 * 1024;
+export async function traceSize(root, secure = false) {
+    const stat = await fs.lstat(root);
+    if (stat.isSymbolicLink() || (!stat.isFile() && !stat.isDirectory()))
+        throw new Error('UNSAFE_ARTIFACT');
+    if (secure)
+        await fs.chmod(root, stat.isDirectory() ? 0o700 : 0o600);
+    if (stat.isFile())
+        return stat.size;
+    let size = 0;
+    for (const name of await fs.readdir(root)) {
+        size += await traceSize(path.join(root, name), secure);
+        if (size > IOS_TRACE_MAX_BYTES)
+            throw new Error('STORAGE_LIMIT');
+    }
+    return size;
+}
+export function validateToc(xml, device, app) {
+    if (XMLValidator.validate(xml) !== true)
+        throw new Error('INVALID_TOC');
+    const parsed = new XMLParser({ ignoreAttributes: false }).parse(xml);
+    const raw = parsed['trace-toc']?.run;
+    if (!raw || Array.isArray(raw))
+        throw new Error('INVALID_TOC');
+    const target = raw.info?.target;
+    if (target?.device?.['@_uuid'] !== device || Number(target.process?.['@_pid']) !== app.pid || raw.info?.summary?.['template-name'] !== 'Time Profiler')
+        throw new Error('ARTIFACT_TARGET_MISMATCH');
+    const processes = raw.processes?.process;
+    if (!(Array.isArray(processes) ? processes : [processes]).some(p => Number(p?.['@_pid']) === app.pid && p?.['@_path'] === app.executable))
+        throw new Error('ARTIFACT_APP_MISMATCH');
+    const tables = raw.data?.table;
+    if (!(Array.isArray(tables) ? tables : [tables]).some(t => t?.['@_schema'] === 'time-sample'))
+        throw new Error('SAMPLE_SCHEMA_MISSING');
+}
+export async function validateArtifact(file, device, app, spawn = spawnTrace) {
+    const size = await traceSize(file, true);
+    if (size <= 0 || size > IOS_TRACE_MAX_BYTES)
+        throw new Error('STORAGE_LIMIT');
+    const toc = path.join(path.dirname(file), 'toc.xml'), samples = path.join(path.dirname(file), 'samples.xml');
+    try {
+        await traceCommand(getXcrunCmd(), ['xctrace', 'export', '--input', file, '--toc', '--output', toc], 15000, spawn);
+        if ((await fs.stat(toc)).size > 1024 * 1024)
+            throw new Error('INVALID_TOC');
+        validateToc(await fs.readFile(toc, 'utf8'), device, app);
+        await traceCommand(getXcrunCmd(), ['xctrace', 'export', '--input', file, '--xpath', '/trace-toc/run[@number="1"]/data/table[@schema="time-sample"]', '--output', samples], 15000, spawn);
+        if ((await fs.stat(samples)).size > IOS_TRACE_MAX_BYTES)
+            throw new Error('STORAGE_LIMIT');
+        const xml = await fs.readFile(samples, 'utf8');
+        if (XMLValidator.validate(xml) !== true || !xml.includes('<trace-query-result>'))
+            throw new Error('INVALID_SAMPLES');
+        const sample_rows = (xml.match(/<row(?:\s|>)/g) ?? []).length;
+        return { path: file, format: 'instruments', kind: (await fs.stat(file)).isDirectory() ? 'directory' : 'file',
+            size_bytes: size, validation: { readable: true, schema: 'time-sample', sample_rows } };
+    }
+    finally {
+        await Promise.all([toc, samples].map(p => fs.rm(p, { force: true })));
+    }
+}

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

@@ -0,0 +1,86 @@
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { getXcrunCmd } from '../../utils/ios/utils.js';
+import { traceCommand, spawnTrace } from './process.js';
+import { prepareNotification } from './notification.js';
+export const IOS_TEMPLATES = ['System Trace', 'Time Profiler', 'Animation Hitches', 'Hangs'];
+export async function resolveIosApp(device, appId, spawn = spawnTrace) {
+    const run = (args) => traceCommand(getXcrunCmd(), args, 10000, spawn);
+    const container = await run(['simctl', 'get_app_container', device, appId, 'app']);
+    if (!path.isAbsolute(container) || !container.endsWith('.app'))
+        throw new Error('APP_IDENTITY_UNAVAILABLE');
+    const output = await run(['simctl', 'spawn', device, 'launchctl', 'list']);
+    const ids = output.split('\n').filter(line => line.includes(`UIKitApplication:${appId}[`))
+        .map(line => Number(line.trim().split(/\s+/)[0])).filter(pid => Number.isSafeInteger(pid) && pid > 1);
+    if (ids.length !== 1)
+        throw new Error('APP_NOT_RUNNING');
+    const executable = await traceCommand('/bin/ps', ['-p', String(ids[0]), '-o', 'comm='], 10000, spawn);
+    if (!executable.startsWith(container + '/') || executable.includes('\n'))
+        throw new Error('APP_IDENTITY_UNAVAILABLE');
+    const started_at = await traceCommand('/bin/ps', ['-p', String(ids[0]), '-o', 'lstart='], 10000, spawn);
+    if (!started_at || started_at.includes('\n'))
+        throw new Error('APP_IDENTITY_UNAVAILABLE');
+    return { app_id: appId, pid: ids[0], executable, started_at };
+}
+export async function iosCapabilities(device, appId, template = 'Time Profiler', spawn = spawnTrace, host = process.platform) {
+    const result = {
+        supported: false, backend: 'xctrace', device: null, xcode_version: null,
+        prerequisites: { host: host === 'darwin' ? 'available' : 'missing', permissions: 'unknown', symbols: 'unknown' },
+        reasons: [], recovery: [], discovered_templates: [], templates: [], app: null,
+        limitations: ['App attachment may include sensitive system metadata, paths, logs and signposts.', 'Permissions and symbolication are not established by discovery.', 'Physical iOS capture is not supported in the initial matrix.']
+    };
+    if (host !== 'darwin') {
+        result.reasons.push('MACOS_REQUIRED');
+        return result;
+    }
+    const probe = async (key, fn, recovery) => {
+        try {
+            await fn();
+            result.prerequisites[key] = 'available';
+        }
+        catch (error) {
+            result.prerequisites[key] = 'missing';
+            result.reasons.push(error instanceof Error && ['APP_NOT_RUNNING', 'APP_IDENTITY_UNAVAILABLE'].includes(error.message) ? error.message : key.toUpperCase() + '_UNAVAILABLE');
+            result.recovery.push(recovery);
+        }
+    };
+    await probe('xcode', async () => { result.xcode_version = await traceCommand(getXcrunCmd(), ['xcodebuild', '-version'], 10000, spawn); }, 'Select a full Xcode installation with xcode-select.');
+    await probe('templates', async () => {
+        const output = await traceCommand(getXcrunCmd(), ['xctrace', 'list', 'templates'], 10000, spawn);
+        result.discovered_templates = output.split('\n').map(s => s.trim()).filter(s => s && !s.startsWith('=='));
+    }, 'Install/select Xcode with Instruments and run xcrun xctrace list templates.');
+    await probe('instruments_targets', async () => {
+        const targets = await traceCommand(getXcrunCmd(), ['xctrace', 'list', 'devices'], 15000, spawn);
+        if (!targets.includes(`(${device})`))
+            throw new Error('TARGET_UNAVAILABLE');
+    }, 'Check xcrun xctrace list devices; use a simulator visible to Instruments.');
+    await probe('target', async () => {
+        const data = JSON.parse(await traceCommand(getXcrunCmd(), ['simctl', 'list', 'devices', '--json'], 10000, spawn));
+        const entries = Object.entries(data.devices).flatMap(([runtime, values]) => values.map(value => ({ ...value, runtime })));
+        const target = entries.find(d => d.udid === device);
+        if (!target || !target.isAvailable || target.state !== 'Booted')
+            throw new Error('TARGET_UNAVAILABLE');
+        result.device = { platform: 'ios', id: target.udid, simulator: true, model: target.name, osVersion: target.runtime.split('iOS-')[1]?.replaceAll('-', '.') ?? target.runtime };
+    }, 'Use an explicit booted simulator UDID. Physical devices and the Mac host are unsupported.');
+    await probe('notification_helper', async () => {
+        const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'mcp-trace-probe-'));
+        try {
+            await prepareNotification(directory, spawn);
+        }
+        finally {
+            await fs.rm(directory, { recursive: true, force: true });
+        }
+    }, 'Allow Xcode clang to compile the local Darwin-notification listener.');
+    if (appId && result.device)
+        await probe('app', async () => { result.app = await resolveIosApp(device, appId, spawn); }, 'Start the requested development app on the selected simulator before tracing.');
+    result.templates = IOS_TEMPLATES.map(name => ({ name,
+        supported: name === 'Time Profiler' && result.discovered_templates.includes(name) && result.device !== null,
+        coverage: name === 'Time Profiler' ? 'CPU samples; bundled Hangs instrument is not independently verified' : name === 'System Trace' ? 'Scheduling coverage unverified' : name === 'Hangs' ? 'Not a standalone template here' : 'Unsupported on tested simulator',
+        reason: name === 'Time Profiler' ? null : 'TEMPLATE_TARGET_UNSUPPORTED'
+    }));
+    if (!result.templates.find(t => t.name === template)?.supported)
+        result.reasons.push('TEMPLATE_TARGET_UNSUPPORTED');
+    result.supported = result.reasons.length === 0;
+    return result;
+}