mobile-debug-mcp 0.33.0 → 0.35.0

package/dist/utils/cli/ios/preflight-ios.js

@@ -22,11 +22,10 @@ async function findFirst(root, patterns, maxDepth = 4) {
             console.error('DEBUG findFirst: entries', ents.map(e => e.name));
             for (const e of ents) {
                 const full = path.join(dir, e.name);
-                for (const p of patterns) {
-                    if (e.name.endsWith(p)) {
-                        console.error('DEBUG findFirst: matched', full);
-                        return full;
-                    }
+                const matched = patterns.some(pattern => e.name.endsWith(pattern));
+                if (matched) {
+                    console.error('DEBUG findFirst: matched', full);
+                    return full;
                 }
                 if (e.isDirectory() && depth < maxDepth)
                     queue.push({ dir: full, depth: depth + 1 });
@@ -52,26 +51,7 @@ function startCompanionIfNeeded(companionPath, udid) {
     }
 }
 async function main() {
-    const args = process.argv.slice(2);
-    let projectArg;
-    let udid;
-    let startCompanion = false;
-    let kmpBuild = null;
-    for (let i = 0; i < args.length; i++) {
-        const a = args[i];
-        if (a === '--project' && args[i + 1]) {
-            projectArg = args[i + 1];
-            i++;
-        }
-        else if (a === '--udid' && args[i + 1]) {
-            udid = args[i + 1];
-            i++;
-        }
-        else if (a === '--start-companion')
-            startCompanion = true;
-        else if (!projectArg)
-            projectArg = a;
-    }
+    const { projectArg, udid, startCompanion, kmpBuild } = argumentsForPreflight(process.argv.slice(2));
     const cwd = process.cwd();
     const projectRoot = projectArg ? path.resolve(projectArg) : cwd;
     // If user passed a direct .xcodeproj or .xcworkspace path, accept it as the projectFile
@@ -108,15 +88,8 @@ async function main() {
     // 4) idb_companion
     const companionPath = commandWhich('idb_companion');
     const companionAvailable = !!companionPath;
-    const suggestions = [];
-    if (!projectFile)
-        suggestions.push('Provide correct project path or ensure .xcodeproj/.xcworkspace exists in project dir');
-    if (!kmpFramework)
-        suggestions.push('Run KMP Gradle task to produce Shared.framework before xcodebuild (e.g., :shared:embedAndSignAppleFrameworkForXcode)');
-    if (!idbAvailable)
-        suggestions.push('Ensure idb is in PATH or set MCP_IDB_PATH / IDB_PATH');
-    if (!companionAvailable)
-        suggestions.push('Install idb_companion and ensure it is in PATH');
+    const suggestions = preflightSuggestions(projectFile, kmpFramework, idbAvailable, companionAvailable);
+    const companionInfo = { cmd: companionPath, installed: companionAvailable };
     const result = {
         ok: !!projectFile && !!idbAvailable,
         project: {
@@ -133,10 +106,7 @@ async function main() {
             cmd: idbPath,
             installed: idbAvailable
         },
-        idb_companion: {
-            cmd: companionPath,
-            installed: companionAvailable
-        },
+        idb_companion: companionInfo,
         suggestions
     };
     if (startCompanion && udid) {
@@ -153,3 +123,37 @@ main().catch(e => {
     console.log(JSON.stringify({ ok: false, error: e instanceof Error ? e.message : String(e) }, null, 2));
     process.exit(2);
 });
+function argumentsForPreflight(args) {
+    let projectArg;
+    let udid;
+    let startCompanion = false;
+    const kmpBuild = null;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--project' && args[i + 1]) {
+            projectArg = args[i + 1];
+            i++;
+        }
+        else if (a === '--udid' && args[i + 1]) {
+            udid = args[i + 1];
+            i++;
+        }
+        else if (a === '--start-companion')
+            startCompanion = true;
+        else if (!projectArg)
+            projectArg = a;
+    }
+    return { projectArg, udid, startCompanion, kmpBuild };
+}
+function preflightSuggestions(projectFile, kmpFramework, idbAvailable, companionAvailable) {
+    const suggestions = [];
+    if (!projectFile)
+        suggestions.push('Provide correct project path or ensure .xcodeproj/.xcworkspace exists in project dir');
+    if (!kmpFramework)
+        suggestions.push('Run KMP Gradle task to produce Shared.framework before xcodebuild (e.g., :shared:embedAndSignAppleFrameworkForXcode)');
+    if (!idbAvailable)
+        suggestions.push('Ensure idb is in PATH or set MCP_IDB_PATH / IDB_PATH');
+    if (!companionAvailable)
+        suggestions.push('Install idb_companion and ensure it is in PATH');
+    return suggestions;
+}

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/ios/utils.js

@@ -19,16 +19,14 @@ export function getConfiguredIdbPath() {
             if (!p)
                 continue;
             try {
-                if (fs.existsSync(p)) {
-                    const raw = fs.readFileSync(p, 'utf8');
-                    const json = JSON.parse(raw);
-                    if (json) {
-                        if (json.idbPath)
-                            return json.idbPath;
-                        if (json.IDB_PATH)
-                            return json.IDB_PATH;
-                    }
-                }
+                if (!fs.existsSync(p))
+                    continue;
+                const raw = fs.readFileSync(p, 'utf8');
+                const json = JSON.parse(raw);
+                if (json?.idbPath)
+                    return json.idbPath;
+                if (json?.IDB_PATH)
+                    return json.IDB_PATH;
             }
             catch { }
         }
@@ -214,18 +212,18 @@ export async function getIOSDeviceMetadata(deviceId = "booted") {
                 const devicesMap = data.devices || {};
                 for (const runtime in devicesMap) {
                     const devices = devicesMap[runtime];
-                    if (Array.isArray(devices)) {
-                        for (const device of devices) {
-                            if (deviceId === "booted" || device.udid === deviceId) {
-                                resolve({
-                                    platform: "ios",
-                                    id: device.udid,
-                                    osVersion: parseRuntimeName(runtime),
-                                    model: device.name,
-                                    simulator: true,
-                                });
-                                return;
-                            }
+                    if (!Array.isArray(devices))
+                        continue;
+                    for (const device of devices) {
+                        if (deviceId === "booted" || device.udid === deviceId) {
+                            resolve({
+                                platform: "ios",
+                                id: device.udid,
+                                osVersion: parseRuntimeName(runtime),
+                                model: device.name,
+                                simulator: true,
+                            });
+                            return;
                         }
                     }
                 }
@@ -257,36 +255,37 @@ export async function listIOSDevices(appId) {
                             const bmap = bdata.devices || {};
                             for (const rt in bmap) {
                                 const devs = bmap[rt];
-                                if (Array.isArray(devs))
-                                    for (const d of devs)
-                                        bootedSet.add(d.udid);
+                                if (!Array.isArray(devs))
+                                    continue;
+                                for (const d of devs)
+                                    bootedSet.add(d.udid);
                             }
                         }
                         catch { }
                     }
                     for (const runtime in devicesMap) {
                         const devices = devicesMap[runtime];
-                        if (Array.isArray(devices)) {
-                            for (const device of devices) {
-                                const info = {
-                                    platform: 'ios',
-                                    id: device.udid,
-                                    osVersion: parseRuntimeName(runtime),
-                                    model: device.name,
-                                    simulator: true,
-                                    booted: bootedSet.has(device.udid)
-                                };
-                                if (appId) {
-                                    // check if installed
-                                    const p = execCommand(['simctl', 'get_app_container', device.udid, appId, 'data'], device.udid)
-                                        .then(() => { info.appInstalled = true; })
-                                        .catch(() => { info.appInstalled = false; })
-                                        .then(() => { out.push(info); });
-                                    checks.push(p);
-                                }
-                                else {
-                                    out.push(info);
-                                }
+                        if (!Array.isArray(devices))
+                            continue;
+                        for (const device of devices) {
+                            const info = {
+                                platform: 'ios',
+                                id: device.udid,
+                                osVersion: parseRuntimeName(runtime),
+                                model: device.name,
+                                simulator: true,
+                                booted: bootedSet.has(device.udid)
+                            };
+                            if (appId) {
+                                // check if installed
+                                const p = execCommand(['simctl', 'get_app_container', device.udid, appId, 'data'], device.udid)
+                                    .then(() => { info.appInstalled = true; })
+                                    .catch(() => { info.appInstalled = false; })
+                                    .then(() => { out.push(info); });
+                                checks.push(p);
+                            }
+                            else {
+                                out.push(info);
                             }
                         }
                     }

package/dist/utils/java.js

@@ -25,52 +25,36 @@ 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');
-        }
-        // 2) Android Studio JBR candidates (prefer these over JAVA_HOME)
-        const jbrCandidates = [
-            '/Applications/Android Studio.app/Contents/jbr',
-            '/Applications/Android Studio.app/Contents/jbr/Contents/Home',
-            '/Applications/Android Studio Preview.app/Contents/jbr',
-            '/Applications/Android Studio Preview.app/Contents/jbr/Contents/Home',
-            '/Applications/Android Studio Preview 2022.3.app/Contents/jbr',
-            '/Applications/Android Studio Preview 2022.3.app/Contents/jbr/Contents/Home',
-            '/Applications/Android Studio Preview 2023.1.app/Contents/jbr',
-            '/Applications/Android Studio Preview 2023.1.app/Contents/jbr/Contents/Home'
-        ];
-        for (const p of jbrCandidates) {
-            const javaBin = path.join(p, 'bin', 'java');
-            if (existsSync(javaBin)) {
-                const v = javaVersionOf(javaBin);
-                if (isJavaVersionAcceptable(v)) {
-                    console.debug('[java.detect] Found Android Studio JBR at:', p);
-                    return p;
-                }
-            }
+            debug('[java.detect] ANDROID_STUDIO_JDK present but java -version did not match expected versions');
         }
+        const jbr = findStudioJava(debug);
+        if (jbr)
+            return jbr;
         // 3) If JAVA_HOME set, validate it (accept 17 or 21)
         if (process.env.JAVA_HOME) {
             try {
                 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 +68,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,42 +76,76 @@ 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 {
-            const homes = execSync('ls -1 /Library/Java/JavaVirtualMachines || true', { stdio: ['ignore', 'pipe', 'inherit'] }).toString().split(/\r?\n/).filter(Boolean);
-            for (const h of homes) {
-                if (h.toLowerCase().includes('17') || h.toLowerCase().includes('jdk-17') || h.toLowerCase().includes('21') || h.toLowerCase().includes('jdk-21')) {
-                    const candidate = `/Library/Java/JavaVirtualMachines/${h}/Contents/Home`;
-                    return candidate;
-                }
+        const commonHome = findMacJavaHome(debug);
+        if (commonHome)
+            return commonHome;
+        return findLinuxJavaHome(debug);
+    }
+    catch (e) {
+        debug('[java.detect] error detecting java home:', e instanceof Error ? e.message : String(e));
+    }
+    return undefined;
+}
+function findStudioJava(debug) {
+    // 2) Android Studio JBR candidates (prefer these over JAVA_HOME)
+    const jbrCandidates = [
+        '/Applications/Android Studio.app/Contents/jbr',
+        '/Applications/Android Studio.app/Contents/jbr/Contents/Home',
+        '/Applications/Android Studio Preview.app/Contents/jbr',
+        '/Applications/Android Studio Preview.app/Contents/jbr/Contents/Home',
+        '/Applications/Android Studio Preview 2022.3.app/Contents/jbr',
+        '/Applications/Android Studio Preview 2022.3.app/Contents/jbr/Contents/Home',
+        '/Applications/Android Studio Preview 2023.1.app/Contents/jbr',
+        '/Applications/Android Studio Preview 2023.1.app/Contents/jbr/Contents/Home'
+    ];
+    for (const p of jbrCandidates) {
+        const javaBin = path.join(p, 'bin', 'java');
+        if (existsSync(javaBin)) {
+            const v = javaVersionOf(javaBin);
+            if (isJavaVersionAcceptable(v)) {
+                debug('[java.detect] Found Android Studio JBR at:', p);
+                return p;
             }
         }
-        catch (e) {
-            console.debug('[java.detect] listing /Library/Java/JavaVirtualMachines failed: ' + String(e));
-        }
-        // 7) Linux locations
-        const linuxCandidates = [
-            '/usr/lib/jvm/java-17-openjdk-amd64',
-            '/usr/lib/jvm/java-17-openjdk',
-            '/usr/lib/jvm/zulu17',
-            '/usr/lib/jvm/temurin-17-jdk',
-            '/usr/lib/jvm/temurin-21-jdk',
-            '/usr/lib/jvm/java-21-openjdk-amd64'
-        ];
-        for (const p of linuxCandidates) {
-            try {
-                if (existsSync(p))
-                    return p;
-            }
-            catch (e) {
-                console.debug(`[java.detect] checking linux candidate ${p} failed: ${String(e)}`);
+    }
+    return undefined;
+}
+function findMacJavaHome(debug) {
+    // 6) macOS common JDK locations
+    try {
+        const homes = execSync('ls -1 /Library/Java/JavaVirtualMachines || true', { stdio: ['ignore', 'pipe', 'inherit'] }).toString().split(/\r?\n/).filter(Boolean);
+        for (const h of homes) {
+            if (h.toLowerCase().includes('17') || h.toLowerCase().includes('jdk-17') || h.toLowerCase().includes('21') || h.toLowerCase().includes('jdk-21')) {
+                const candidate = `/Library/Java/JavaVirtualMachines/${h}/Contents/Home`;
+                return candidate;
             }
         }
     }
     catch (e) {
-        console.debug('[java.detect] error detecting java home:', e instanceof Error ? e.message : String(e));
+        debug('[java.detect] listing /Library/Java/JavaVirtualMachines failed: ' + String(e));
+    }
+    return undefined;
+}
+function findLinuxJavaHome(debug) {
+    // 7) Linux locations
+    const linuxCandidates = [
+        '/usr/lib/jvm/java-17-openjdk-amd64',
+        '/usr/lib/jvm/java-17-openjdk',
+        '/usr/lib/jvm/zulu17',
+        '/usr/lib/jvm/temurin-17-jdk',
+        '/usr/lib/jvm/temurin-21-jdk',
+        '/usr/lib/jvm/java-21-openjdk-amd64'
+    ];
+    for (const p of linuxCandidates) {
+        try {
+            if (existsSync(p))
+                return p;
+        }
+        catch (e) {
+            debug(`[java.detect] checking linux candidate ${p} failed: ${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;
@@ -64,6 +66,9 @@ async function resolveDevice(opts) {
             throw new Error(`Device '${deviceId}' not found for platform ${platform}`);
         return found;
     }
+    return selectDevice(devices, platform, appId, prefer);
+}
+function selectDevice(devices, platform, appId, prefer) {
     let candidates = devices.slice();
     if (prefer === "physical")
         candidates = candidates.filter(d => !d.simulator);
@@ -97,8 +102,7 @@ async function resolveDevice(opts) {
             return candidates[0];
         }
         const list = candidates.map(d => ({ id: d.id, platform: d.platform, osVersion: d.osVersion, model: d.model, simulator: d.simulator, appInstalled: d.appInstalled }));
-        const err = new Error(`Multiple matching devices found: ${JSON.stringify(list, null, 2)}`);
-        err.devices = list;
+        const err = Object.assign(new Error(`Multiple matching devices found: ${JSON.stringify(list, null, 2)}`), { devices: list });
         throw err;
     }
     throw new Error(`No devices found for platform ${platform}`);

package/dist/utils/ui/index.js

@@ -73,36 +73,11 @@ export function computeScreenFingerprint(tree, current, platform, limit = 50) {
 }
 export async function scrollToElementShared(opts) {
     const { selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId, fetchTree, swipe, stabilizationDelayMs = 350 } = opts;
-    const matchElement = (el) => {
-        if (!el)
-            return false;
-        if (selector.text !== undefined && selector.text !== el.text)
-            return false;
-        if (selector.resourceId !== undefined && selector.resourceId !== el.resourceId)
-            return false;
-        if (selector.contentDesc !== undefined && selector.contentDesc !== el.contentDescription)
-            return false;
-        if (selector.className !== undefined && selector.className !== el.type)
-            return false;
-        return true;
-    };
-    const isVisible = (el, resolution) => {
-        if (!el)
-            return false;
-        if (el.visible === false)
-            return false;
-        if (!el.bounds || !resolution || !resolution.width || !resolution.height)
-            return (el.visible === undefined ? true : !!el.visible);
-        const [left, top, right, bottom] = el.bounds;
-        const withinY = bottom > 0 && top < resolution.height;
-        const withinX = right > 0 && left < resolution.width;
-        return withinX && withinY;
-    };
     const findVisibleMatch = (elements, resolution) => {
         if (!Array.isArray(elements))
             return null;
         for (const e of elements) {
-            if (matchElement(e) && isVisible(e, resolution))
+            if (matchElement(selector, e) && isVisible(e, resolution))
                 return e;
         }
         return null;
@@ -169,3 +144,28 @@ export async function scrollToElementShared(opts) {
     }
     return { success: false, reason: 'Element not found after scrolling', scrollsPerformed: scrollsPerformed };
 }
+function matchElement(selector, el) {
+    if (!el)
+        return false;
+    if (selector.text !== undefined && selector.text !== el.text)
+        return false;
+    if (selector.resourceId !== undefined && selector.resourceId !== el.resourceId)
+        return false;
+    if (selector.contentDesc !== undefined && selector.contentDesc !== el.contentDescription)
+        return false;
+    if (selector.className !== undefined && selector.className !== el.type)
+        return false;
+    return true;
+}
+function isVisible(el, resolution) {
+    if (!el)
+        return false;
+    if (el.visible === false)
+        return false;
+    if (!el.bounds || !resolution || !resolution.width || !resolution.height)
+        return (el.visible === undefined ? true : !!el.visible);
+    const [left, top, right, bottom] = el.bounds;
+    const withinY = bottom > 0 && top < resolution.height;
+    const withinX = right > 0 && left < resolution.width;
+    return withinX && withinY;
+}

package/docs/CHANGELOG.md

@@ -1,8 +1,56 @@
 # Changelog
 
+[Documentation](README.md)
+
+Entries describe their release at the time it was recorded. Historical source
+paths and commands may have moved; use the [contribution guide](../CONTRIBUTING.md)
+and [tool reference](tools/TOOLS.md) for the current checkout.
+
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
 ## Unreleased
+
+## [0.35.0]
+
+- Updated the agent plugin to `0.0.4`, pinned to MCP `0.35.0`.
+
+- Added an opt-in isolated Android coroutine debugger assessment fixture for
+  suspension, dispatcher changes, nested work, stepping and cancellation, with
+  explicit local dependencies. This does not add coroutine reconstruction.
+- Added an opt-in isolated Kotlin debugger validation journey for named locals
+  before/after assignment, compiler scope tables, stale references and app recovery.
+  This adds evidence and regression coverage without changing debugger behaviour.
+- Added opt-in debugger `responseMode: "compact"` to omit repeated target metadata
+  from routine commands while retaining diagnostics, execution state and cleanup.
+  Existing full responses remain the default; discovery and state stay complete.
+- Android debugger failures now include bounded, sanitized stage/reason diagnostics
+  and static recovery guidance while preserving error codes. Capability probes
+  report ordered prerequisite diagnostics; terminal summaries retain failure evidence.
+  Raw stderr, exception messages and app locals are excluded from diagnostics.
+
+- **Runtime requirement:** Node.js 22 or newer is now required. Updated Sharp,
+  Zod and transitive dependencies to clear the dependency audit findings; CI
+  configuration now uses Node 22. Public tool definitions remain unchanged.
+- Split observation, snapshot, iOS build, Android utility and system diagnostic
+  responsibilities into typed services. Removed all 136 legacy quality exceptions;
+  production source meets the default size, complexity, nesting and explicit-any
+  limits. Added screenshot encoding and snapshot log normalization regressions.
+
+- Split server handlers by capability, share target/execution-control contracts, and inject clocks into interaction polling services while preserving tool contracts. Added deterministic timing tests and an Android labelled-slider convergence journey.
+
+- Added ArchUnitTS architecture checks to lint and CI for shared contracts, server boundaries, pure interaction calculations and runtime dependency cycles. Negative controls cover NodeNext resolution, aliases, dynamic imports and re-exports.
+
+- Group interaction services by adjustment, targeting, waits and assertions; separate server schemas and handlers, and place log-derived network observations under `observe/network`. Tool contracts and behaviour are unchanged.
+
+- Reduced `ToolsInteract` to a typed composition facade within the enforced class budget. Extracted adjustment, candidate resolution, synchronization and assertion services without new legacy exceptions, and added an isolated Android interaction journey plus a permanent default-budget regression check.
+
+- Added code-quality gates to lint and CI for source/class/function size, complexity, nesting, explicit `any`, and interaction/runtime import boundaries. Legacy exceptions have per-symbol ceilings that cannot grow unnoticed.
+- Extracted typed UI/control helpers, bounded handle storage, action-result construction and capability-specific tool definitions; clarified and typed debugger session operations and worker protocol messages while retaining public tool contracts.
+- Fixed the debugger device check to fingerprint Java sources in `src/debugger/java/` after the worker relocation.
+
+## [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.
 

package/docs/README.md

@@ -0,0 +1,38 @@
+# Documentation
+
+Mobile Debug MCP provides tools for building, controlling, and inspecting Android
+and iOS apps. Start with the [project README](../README.md) for requirements,
+installation, and client configuration.
+
+## Choose a starting point
+
+- **New to the server?** See the [project overview and installation options](../README.md#start-here).
+- **Looking up a tool?** Use the [tool reference](tools/TOOLS.md) for inputs,
+  responses, examples, and shared interaction principles.
+- **Troubleshooting setup?** Check [environment diagnostics](tools/system.md) and
+  the [tool path settings](../README.md#environment-setup).
+- **Investigating an app failure?** Start with [observations](tools/observe.md)
+  and [evidence correlation](tools/correlated-evidence.md). For deeper Android
+  investigation, use [system traces](tools/system-traces.md) or the
+  [runtime debugger](tools/debugger.md).
+- **Installing a client plugin?** See [client installation](../README.md#agent-plugin)
+  and the [plugin guide](../agent-plugin/README.md) for packaging and versioning.
+
+## Contributing
+
+- [Contribution guide](../CONTRIBUTING.md): local setup, validation, and documentation conventions.
+- [Code structure and quality checks](code-structure.md): module ownership, enforced limits, and existing debt.
+- [Development process](specs/process.md): maintenance and feature workflows.
+- [Agent entrypoint](../AGENTS.md) and [repository skills](../.agents/skills/README.md).
+
+## Design and evidence
+
+- [Design records](specs/): feature intent, specifications, and dated verification
+  records, grouped by feature.
+- [Changelog](CHANGELOG.md): release history.
+- [Benchmark index](benchmarks/README.md): reproducible performance checks and recorded limits.
+
+The tool reference describes the current checkout. Specifications record design
+intent and may contain earlier contracts; approval alone does not establish that
+a feature shipped. Verification records describe the named build and environment,
+not every supported platform or the currently published npm package.

package/docs/benchmarks/README.md

@@ -0,0 +1,18 @@
+# Benchmarks
+
+[Documentation](../README.md)
+
+Use these guides to run a benchmark or inspect its recorded results. Each
+benchmark has one directory containing its instructions, report, and supporting
+data. Generated filenames are retained so the harness can update them directly.
+
+These reports describe particular builds and devices. Passing a smoke check does
+not establish a performance improvement, and Android timings do not establish
+iOS latency.
+
+| Benchmark | Protocol | Recorded results | Design |
+| --- | --- | --- | --- |
+| Interaction latency | [Run the benchmark](interaction-latency/README.md) | [Android measurements](interaction-latency/final.md), [iOS interaction validation](interaction-latency/ios-validation.md) | [018](../specs/018-interaction-latency-and-batched-journeys/spec.md) |
+| UI-tree observation | [Run the paired benchmark](ui-tree-performance/README.md) | [Comparison and limitations](ui-tree-performance/comparison.md) | [019](../specs/019-ui-tree-observation-performance/spec.md) |
+
+Fixture instructions: [latency journey app](../../test/fixtures/latency-journey-app/README.md).