mobile-debug-mcp 0.32.4 → 0.34.0

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

@@ -75,7 +75,7 @@ export async function isIDBInstalled() {
     if (!cmd)
         return false;
     try {
-        execSync(`${cmd} list-targets --json`, { stdio: ['ignore', 'pipe', 'pipe'], timeout: 5000 });
+        execSync(`${cmd} list-targets --json`, { stdio: ['ignore', 'pipe', 'pipe'], timeout: remainingBudget(5000), killSignal: 'SIGKILL' });
         return true;
     }
     catch (e) {
@@ -197,7 +197,7 @@ export async function findAppBundle(dir) {
 export async function getIOSDeviceMetadata(deviceId = "booted") {
     return new Promise((resolve) => {
         // If deviceId is provided (and not "booted"), attempt to find that device among booted simulators.
-        execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], (err, stdout) => {
+        execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], { timeout: remainingBudget(), killSignal: 'SIGKILL' }, (err, stdout) => {
             const fallback = {
                 platform: "ios",
                 id: deviceId,
@@ -240,7 +240,7 @@ export async function getIOSDeviceMetadata(deviceId = "booted") {
 export async function listIOSDevices(appId) {
     return new Promise((resolve) => {
         // Query all devices and separately query booted devices to mark them
-        execFile(getXcrunCmd(), ['simctl', 'list', 'devices', '--json'], (err, stdout) => {
+        execFile(getXcrunCmd(), ['simctl', 'list', 'devices', '--json'], { timeout: remainingBudget(), killSignal: 'SIGKILL' }, (err, stdout) => {
             if (err || !stdout)
                 return resolve([]);
             try {
@@ -249,7 +249,7 @@ export async function listIOSDevices(appId) {
                 const out = [];
                 const checks = [];
                 // Get booted devices set
-                execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], (err2, stdout2) => {
+                execFile(getXcrunCmd(), ['simctl', 'list', 'devices', 'booted', '--json'], { timeout: remainingBudget(), killSignal: 'SIGKILL' }, (err2, stdout2) => {
                     const bootedSet = new Set();
                     if (!err2 && stdout2) {
                         try {

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); }
@@ -8,14 +9,37 @@ export function runWithBudget(timeoutMs, operation) {
 }
 export function remainingBudget(fallback = 0) {
     const budget = budgets.getStore();
-    if (!budget || !Number.isFinite(budget.deadline))
+    let deadline = budget?.deadline ?? Infinity;
+    for (let ancestor = budget?.parent; ancestor; ancestor = ancestor.parent)
+        deadline = Math.min(deadline, ancestor.deadline);
+    if (!Number.isFinite(deadline))
         return fallback;
-    const remaining = Math.floor(budget.deadline - performance.now());
+    const remaining = Math.floor(deadline - performance.now());
     if (remaining <= 0)
         throw new Error('ACTION_TIMEOUT');
     return fallback > 0 ? Math.min(fallback, remaining) : remaining;
 }
+// Pause only this action's budget. Any enclosing operation still bounds the read.
+export async function runWithSeparateBudget(timeoutMs, operation) {
+    remainingBudget();
+    const action = budgets.getStore();
+    const started = performance.now();
+    const parent = action?.parent;
+    const budget = { deadline: Math.min(parent?.deadline ?? Infinity, started + timeoutMs), dispatchStarted: false, parent };
+    try {
+        return await budgets.run(budget, async () => {
+            const result = await operation();
+            remainingBudget();
+            return result;
+        });
+    }
+    finally {
+        if (action)
+            action.deadline += performance.now() - started;
+    }
+}
 export function markDispatchStarted() {
+    checkDebuggerGuard(true);
     remainingBudget();
     let budget = budgets.getStore();
     while (budget) {

package/dist/utils/resolve-device.js

@@ -1,3 +1,5 @@
+import { checkDebuggerGuard } from '../debugger/guard.js';
+import { bindEvidenceDevice } from '../observe/evidence.js';
 import { retainConnectedDeviceSnapshots } from '../observe/snapshot-metadata.js';
 import { measure } from './timing.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
@@ -37,9 +39,16 @@ export async function listDevices(platform, appId) {
 }
 const deviceContext = new AsyncLocalStorage();
 export function withResolvedDevice(device, operation) {
+    bindEvidenceDevice(device);
     return deviceContext.run(device, operation);
 }
 export async function resolveTargetDevice(opts) {
+    checkDebuggerGuard();
+    const device = await resolveDevice(opts);
+    bindEvidenceDevice(device);
+    return device;
+}
+async function resolveDevice(opts) {
     const { platform, appId, prefer, deviceId } = opts;
     const current = deviceContext.getStore();
     if (current && current.platform === platform && (!deviceId || current.id === deviceId))

package/docs/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 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.
+
+## [0.33.0]
+- Fixed selector taps timing out before one normal Android UI-tree acquisition: a default single lookup now uses the action budget (5 seconds). Selector taps with exists/visible waits resolve actionable containers consistently with clickable waits; hidden/disabled labels remain protected. Acquisition timeouts retain `ACTION_TIMEOUT` instead of reporting a missing element.
+- Added correlated action/observation evidence, explicit `actionRef`, phase/acquisition timestamps, conservative freshness, and bounded metadata history. Journey steps share correlation IDs; snapshot components and stream reads retain their actual device scope. Device log times remain explicitly incomparable with host dispatch times; tracing is unsupported.
+- Added evidence-backed foreground UI readiness observations, bounded readiness waits, and opt-in `requireReady` for existing UI waits. Tree responses include single-sample readiness without extra reads. Unresponsive/debugger-paused signals are explicitly unsupported; iOS probes and metadata reads now respect active operation budgets.
+- Added optional conditional input to `tap`, `tap_element`, `swipe`, Android `type_text`/`press_back`, and journey tap steps. A fresh snapshot check at native dispatch blocks stale or uncheckable expectations and returns condition evidence, including fresh trees in compact failures.
+- Added process-scoped `snapshot_session_id` metadata to UI-tree responses so conditional expectations cannot be reused across server restarts. Successful repeated observations refresh retained revision history timestamps.
+
 ## [0.32.4]
 - Removed the optional Android UI-tree bridge runtime and its APK build tooling. Android UI-tree reads use `uiautomator dump` through ADB.
 

package/docs/specs/020-conditional-actions/intent.md

@@ -0,0 +1,62 @@
+# Intent: conditional actions
+
+Originator: repository maintainer (user in the current conversation).
+Date: 2026-10-29.
+Status: approved.
+
+## Original problem
+
+“Conditional actions: Check expected state immediately before acting; stop and
+return fresh evidence if it changed.”
+
+Source: user request in the current conversation, following adoption of the
+repository development process.
+
+## Desired outcome
+
+An MCP client can make an action conditional on an expected UI state. The server
+checks that expectation against a fresh observation of the same target device
+immediately before dispatching the action. If the expectation no longer holds,
+the server does not dispatch the action and returns fresh evidence so the client
+can reassess its next step.
+
+Affected users and systems: MCP clients/agents, interaction tool dispatch,
+state observation, and Android/iOS adapters for supported actions.
+
+## Observable success criteria
+
+- A matching expectation allows the requested action to proceed normally.
+- A mismatching expectation prevents dispatch and clearly reports that the
+  action was not performed, together with the newly observed state.
+- If the expected state cannot be checked reliably, the action is not dispatched;
+  the response explains the observation failure without inventing evidence.
+- The check and action target the same device.
+- A mismatch does not automatically retry the action or adopt the new state.
+- Existing calls without a condition preserve their behaviour.
+
+## Constraints and exclusions
+
+- Reuse existing action, observation, and response conventions where suitable.
+- Define precise supported conditions, actions, evidence, and platform coverage
+  in the spec after approval of this intent.
+- A pre-dispatch check cannot guarantee the UI remains unchanged between the
+  observation and native input delivery; do not claim atomic device execution.
+- Automatic replanning, rollback, and post-action success verification are
+  outside this feature's scope.
+- Preserve unrelated checkout changes.
+
+## Assumptions and open questions for specification
+
+- Proposed compatibility approach: conditions are optional on supported actions.
+- Determine the initial action set, including whether journey steps are covered.
+- Determine whether expectations use screen identity, element properties,
+  snapshot revisions, or a supported combination.
+- Define fresh mismatch evidence and how it is preserved in compact responses.
+- Existing screen fingerprints deliberately omit some changing values; assess
+  their suitability rather than assuming they detect every relevant state change.
+
+## Approval
+
+Approved by the originator in the current conversation on 2026-10-29: “yes”,
+in direct response to the complete intent summary and linked artifact. Approval
+covers the captured intent; specification approval remains a separate gate.

package/docs/specs/020-conditional-actions/plan.md

@@ -0,0 +1,214 @@
+# Plan: conditional actions
+
+Date: 2026-10-29. Status: complete — implementation and required verification passed.
+Intent: [intent.md](intent.md). Specification: [spec.md](spec.md).
+Both approved by the originator's separate “yes” replies in this conversation;
+the latest approval authorises implementation of spec 020.
+
+## Implementation sequence
+
+- [x] Inspect action wrapping, native input, observation/history, budgets, tests.
+- [x] Add session metadata and retained successful-baseline lookup without changing
+  existing revision semantics or growing history.
+- [x] Add strict condition schema, supported-tool validation, and journey tap wiring.
+- [x] Add a request-scoped asynchronous pre-dispatch guard, pin the device, and
+  isolate the observation budget from the action budget (respecting outer budgets).
+- [x] Integrate at Android/iOS input spawn boundaries; retain failure evidence
+  through adapter errors; defer guarded network-window reset until dispatch.
+- [x] Preserve condition evidence and non-delivery semantics in compact/debug
+  responses, including journey stop and not-checked cases.
+- [x] Add deterministic unit/adapter regression coverage and device journeys.
+- [x] Update public docs/changelog and packaged agent usage guidance; sync/check plugin.
+- [x] Run focused checks, maintainer verification, device suite, and focused device journeys.
+- [x] Review changed code/contracts/callers and record results and limits.
+
+## Expected affected files
+
+- `src/observe/snapshot-metadata.ts`, `src/observe/index.ts`, `src/types.ts`.
+- New shared condition schema/guard modules under `src/` as responsibility requires.
+- `src/utils/operation-budget.ts`, Android/iOS input adapters.
+- `src/server/tool-definitions.ts`, `tool-handlers.ts`, `journey-schema.ts`, `common.ts`.
+- Unit tests under `test/unit/server/`, `test/unit/observe/`, and adapter fixtures.
+- Focused reusable device helper under `test/device/manual/` if explicit simulator
+  selection/state setup makes it unsuitable for automatic generic suite execution.
+- `docs/tools/interact.md`, `observe.md`, `docs/CHANGELOG.md`, `README.md`, and
+  `agent-plugin/skills/mobile-debug-mcp/SKILL.md`.
+
+## Verification mapping
+
+| Spec criteria | Verification |
+| --- | --- |
+| 1, 5, 8 | Real Android/iOS adapter calls using fake binaries; all supported actions, verification modes and response modes; unguarded compatibility tests |
+| 2, 3 | Mutable hierarchy fixture changes text/bounds/enabled/state and changes during target resolution/adapter preparation; assert zero native input and exact final tree |
+| 4 | Session, history expiry/eviction, device mismatch, error/malformed observation, timeout including late completion and child cleanup |
+| 6 | Journey with earlier passed step, blocked conditional tap, later not-run step; both response modes |
+| 7 | Runtime invalid-input matrix and advertised schemas; unsupported tools/steps rejected before any side effects |
+| 9 | Overlapping guarded/unguarded calls and network-window reset spy; condition budget distinct from input budget; outer-budget expiry |
+| 10 | Documentation and focused review against actual implementation |
+
+Commands: focused test files via existing `tsx` runtime, then `npm run verify`,
+`npm run test:device`, and focused device helper against built `dist/` modules.
+Runtime: repository supports Node >=18; record actual Node/toolchain with results.
+No new dependency, migration, helper APK, publication, or service is needed.
+
+## Device routes and readiness
+
+Available during spec reconnaissance: Android 16 `emulator-5554` and booted iOS
+26.4 iPhone Air `F72108FF-C8D6-4C1E-980E-1AE5E5CCD27B`. The physical Pixel is
+excluded from mutation checks. Tool access and fresh trees work on both simulators.
+Before device runs, inspect current state and choose safe system controls; avoid
+interacting with the open Modul8 subscription flow. Use an already-installed
+system Settings app on Android/iOS where possible; no accounts or entitlements.
+
+For each platform on the newly built server:
+
+1. Open system Settings, observe its tree and session/revision, repeat to check a
+   stable baseline, then perform a guarded safe navigation tap and assert destination.
+2. Observe the baseline, navigate to another Settings screen, then send a guarded
+   action with the old expectation; assert non-delivery and returned current tree.
+   Confirm the blocked action has no effect using a fresh state assertion.
+3. Run a journey with an earlier successful wait/assert, an old-revision guarded
+   tap, and a later action. Confirm the tap fails, later step is not run, and state
+   stays unchanged. Repeat relevant compact/debug evidence checks.
+
+Exact selectors depend on the current simulator OS tree and will be recorded
+with results. Restore original foreground apps where practical; do not alter
+settings, app data, or subscriptions. Owner of local prerequisites: current task.
+Unavailable/timeout and last-moment preparation races use controlled fake binaries;
+no forced device disconnect or privileged settings change is needed. This is
+reported as simulated error-path evidence, separate from real-device passes.
+
+## Results
+
+Implementation is present. Node.js v23.11.0 was used locally (the supported
+minimum is >=18; CI's Node 18 run has not been executed locally).
+
+### Automated checks
+
+- Initial `npm run verify`: PASS, including lint, build, unit tests, plugin check.
+- Focused conditional action regression: PASS using production Android/iOS input
+  adapters and controlled fake native binaries. Coverage includes all supported
+  actions, each verification/response mode, late target-preparation changes,
+  mismatches, unavailable/malformed observations, session/history/device rejection,
+  request isolation, native input failure, and journey stop. Complete native
+  observation/input paths also pass with fake ADB/idb, including child-close
+  evidence for condition timeouts. This is simulated platform evidence.
+- Focused schema parity and retention tests: PASS. Advertised JSON schemas are
+  exercised using the existing MCP SDK's validator, alongside runtime schemas.
+  All elements contribute to revision checks beyond the bounded delta history.
+- `npm run sync:agent-plugin`: PASS; no generated manifest differences.
+- Final `npm run verify`: PASS (lint, build, 59 unit-test files, plugin consistency).
+  Log: `/tmp/mobile-debug-conditional-verify-final.log`.
+- Initial `npm run test:device`: FAIL at iOS UI-tree smoke (`Invalid UI tree resolution`) while the original simulator was booting.
+  Android screenshot/log/tree wrappers passed. iOS screenshot wrapper passed;
+  the iOS log wrapper also reported pass but its underlying log retrieval printed
+  `getpwuid_r` / unavailable log-store errors, so this is not evidence of usable
+  iOS logs. These wrappers use automatic device selection; focused tests below
+  pin their simulator explicitly. Full log: `/tmp/mobile-debug-conditional-device-suite.log`.
+
+- Final `npm run test:device`: PASS after the replacement iPhone 17 Pro finished
+  booting. All six Android/iOS screenshot, log, and tree smoke wrappers passed,
+  without the earlier iOS log-store diagnostics. Log:
+  `/tmp/mobile-debug-conditional-device-suite-final.log`.
+- Final documentation relative-link checks and `git diff --check`: PASS.
+- Final lint after the device helper's selector/start-state correction: PASS.
+
+### Focused Android emulator evidence
+
+Command (against the built server over MCP stdio, no mocked tool handlers):
+
+```sh
+node --import tsx test/device/manual/interact/conditional_actions.manual.ts \
+  --platform android --id emulator-5554 \
+  --target-text 'Network & internet' --destination-text Internet \
+  --output /tmp/mobile-debug-conditional-android.json
+```
+
+Device: Android 16 sdk_gphone64_arm64, `emulator-5554`.
+Build: local `dist/server.js`, handshake `mobile-debug-mcp` 0.32.4, with
+`expectedState` confirmed in its advertised tool schema. This is the working-tree
+build, not proof of a published release.
+Starting state: system Settings root, with Network & internet visible.
+
+| Journey | Actions / expected outcome | Observed outcome | Result |
+| --- | --- | --- | --- |
+| Matching snapshot | Observe Settings; conditional coordinate tap Network & internet | `matched`, delivered once; fresh tree contains Internet | PASS |
+| Stale snapshot, compact | On network page, attempt safe back-navigation tap with root expectation | `PRECONDITION_FAILED`, not delivered; compact tree contains Internet; fresh tree confirms network page remains | PASS |
+| Stale snapshot, debug | Repeat guarded back navigation with root expectation | Same non-delivery and unchanged destination, full debug evidence | PASS |
+| Journey stop, compact | Successful wait for Internet, conditional back tap with root expectation, later tap | Earlier wait passed, guarded step failed with fresh tree, later step `not_run`; destination remained | PASS |
+| Journey stop, debug | Same sequence in debug mode | Same stop and preserved evidence | PASS |
+
+Full structured evidence: `/tmp/mobile-debug-conditional-android.json`.
+The five scenarios were rerun successfully against the final built server after
+the compact-error and metadata-validity fixes and the helper selector correction.
+The helper is reproducible and requires a deliberately prepared safe system
+Settings screen. No setting or subscription was changed. The original Modul8
+dev app was brought back to the foreground after checks.
+
+### Focused iOS simulator evidence
+
+The original iPhone Air simulator stalled during boot and was closed/rebooted by
+the user. The replacement iPhone 17 Pro became responsive; read-only screenshot
+and UI-tree checks confirmed Home and then Settings before running input checks.
+No boot/restart/reset commands were issued by the agent.
+
+Command:
+
+```sh
+node --import tsx test/device/manual/interact/conditional_actions.manual.ts \
+  --platform ios --id F9243BAF-62A8-4990-8A99-17F527F56FDA \
+  --target-text General --destination-text About \
+  --output /tmp/mobile-debug-conditional-ios.json
+```
+
+Device: iOS 26.4 iPhone 17 Pro simulator,
+`F9243BAF-62A8-4990-8A99-17F527F56FDA`.
+Build: the same local `dist/server.js` 0.32.4 build and MCP stdio route as Android,
+with condition support confirmed in tool discovery.
+Starting state: Settings root with General visible, About absent.
+
+| Journey | Actions / expected outcome | Observed outcome | Result |
+| --- | --- | --- | --- |
+| Matching snapshot | Observe Settings; conditional coordinate tap General | `matched`, delivered; fresh tree contains About | PASS |
+| Stale snapshot, compact | Attempt safe back-navigation tap with Settings-root expectation | `PRECONDITION_FAILED`, not delivered; compact fresh tree contains About; new observation confirms General stays visible | PASS |
+| Stale snapshot, debug | Same guarded back navigation | Same non-delivery and preserved full condition tree | PASS |
+| Journey stop, compact | Successful wait for About, stale conditional tap on `resource_id: BackButton`, later back tap | Wait passed; condition failed; later step `not_run`; General remained visible | PASS |
+| Journey stop, debug | Same sequence in debug mode | Same stop and fresh condition evidence | PASS |
+
+Structured evidence: `/tmp/mobile-debug-conditional-ios.json`.
+An initial helper attempt selected the application container sharing the Settings
+label and correctly stopped with `ELEMENT_NOT_INTERACTABLE` / `not_checked`;
+this was not counted as a conditional-journey pass. The helper now prefers the
+unique native resource ID and requires the destination to be absent from its
+starting screen. A subsequent incorrect-start attempt was also discarded.
+The final five-pass run above starts at the confirmed root and uses BackButton.
+
+Cleanup: only navigation was exercised. No setting, permission, account, or app
+data was changed. Home is restored after the smoke-suite rerun.
+
+### Focused quality review
+
+Reviewed the shared condition schema and advertised definitions, action wrapper
+and journey dispatch, Android/iOS native input boundaries, observation metadata
+and history, budget ancestors, compact serialization, error/recovery mapping,
+and associated tests/callers. The guard runs after adapter preparation, and
+blocked conditions replace generic adapter failures without inventing an execute
+trace or allowing recovery. Condition observation budgets pause only the current
+action; enclosing deadlines still apply. Tests check no late input after timeout
+and native observation child closure. No new framework or dependency was added.
+
+Review findings fixed:
+
+- Journey light-verification response overlay must preserve `not_requested` when
+  its conditional tap did not dispatch.
+- Compact tree responses must retain observation errors instead of looking like
+  successful deltas carrying an old revision/session. Added a regression test.
+- Repeated successful observations refresh retained revision timestamps, so a
+  recently observed stable screen does not yield an immediately unusable baseline.
+
+Limits: live simulator checks cover conditional taps and journey stops; conditional
+swipes and Android typing/back use production-adapter tests with fake native
+tools. Physical devices were not used for mutation checks. UI normalization, the observation-to-OS-input race, and concurrent external
+input remain explicit spec limits. No mutation testing was performed. No tests
+or validation rules were weakened. Existing uncommitted process/skill relocation
+work was preserved. No package was published and nothing was committed/pushed.