mobile-debug-mcp 0.24.0 → 0.24.2

package/docs/tools/interact.md

@@ -111,13 +111,26 @@ Input example:
 Success response example:
 
 ```json
-{ "success": true, "newFingerprint": "<hex-fingerprint>", "elapsedMs": 420 }
+{
+  "success": true,
+  "previousFingerprint": "<old-hex-fingerprint>",
+  "newFingerprint": "<hex-fingerprint>",
+  "elapsedMs": 420,
+  "observed_screen": { "fingerprint": "<hex-fingerprint>", "activity": "MainActivity" }
+}
 ```
 
 Failure (timeout) example:
 
 ```json
-{ "success": false, "reason": "timeout", "lastFingerprint": "<hex-fingerprint>", "elapsedMs": 5000 }
+{
+  "success": false,
+  "reason": "timeout",
+  "previousFingerprint": "<old-hex-fingerprint>",
+  "lastFingerprint": "<hex-fingerprint>",
+  "elapsedMs": 5000,
+  "observed_screen": { "fingerprint": "<hex-fingerprint>", "activity": "HomeActivity" }
+}
 ```
 
 Notes:
@@ -214,7 +227,26 @@ Success response:
     "index": 8,
     "elementId": "el_..."
   },
-  "metrics": { "latency_ms": 120, "poll_count": 1, "attempts": 1 }
+  "metrics": { "latency_ms": 120, "poll_count": 1, "attempts": 1 },
+  "requested": {
+    "selector": { "text": "Generate Session", "contains": false },
+    "condition": "clickable",
+    "match": { "index": 0 }
+  },
+  "observed": {
+    "matched_count": 1,
+    "condition_satisfied": true,
+    "selected_index": 8,
+    "last_matched_element": {
+      "text": "Generate Session",
+      "resource_id": null,
+      "accessibility_id": null,
+      "class": "android.widget.TextView",
+      "bounds": [471, 1098, 809, 1158],
+      "index": 8,
+      "elementId": "el_..."
+    }
+  }
 }
 ```
 
@@ -223,8 +255,27 @@ Timeout response:
 ```json
 {
   "status": "timeout",
-  "error": { "code": "ELEMENT_NOT_FOUND", "message": "Condition visible not satisfied within timeout" },
-  "metrics": { "latency_ms": 5000, "poll_count": 17, "attempts": 1 }
+  "error": { "code": "ELEMENT_NOT_FOUND", "message": "Condition visible not satisfied within timeout; observed 1 match(es)" },
+  "metrics": { "latency_ms": 5000, "poll_count": 17, "attempts": 1 },
+  "requested": {
+    "selector": { "text": "Generate Session", "contains": false },
+    "condition": "visible",
+    "match": { "index": 0 }
+  },
+  "observed": {
+    "matched_count": 1,
+    "condition_satisfied": false,
+    "selected_index": 8,
+    "last_matched_element": {
+      "text": "Generate Session",
+      "resource_id": null,
+      "accessibility_id": null,
+      "class": "android.widget.TextView",
+      "bounds": [471, 1098, 809, 1158],
+      "index": 8,
+      "elementId": "el_..."
+    }
+  }
 }
 ```
 
@@ -232,6 +283,7 @@ Notes:
 
 - Use `wait_for_ui` to get a stable `elementId` for `tap_element`.
 - Use it before an action when the target element or timing is uncertain.
+- Use `requested` and `observed` to see exactly what condition was checked and what the last poll actually found.
 - If the expected outcome is known after the action, follow with `expect_*`.
 
 ---
@@ -330,7 +382,12 @@ Response:
   "success": true,
   "observed_screen": { "fingerprint": "<actual-fingerprint>", "screen": "com.example.app.MainActivity" },
   "expected_screen": { "fingerprint": "<expected-fingerprint>", "screen": null },
-  "confidence": 1
+  "confidence": 1,
+  "comparison": {
+    "basis": "fingerprint",
+    "matched": true,
+    "reason": "observed fingerprint matches expected fingerprint <expected-fingerprint>"
+  }
 }
 ```
 
@@ -367,6 +424,7 @@ Response:
   "success": true,
   "selector": { "text": "Play session" },
   "element_id": "el_123",
+  "expected_condition": "visible",
   "element": {
     "elementId": "el_123",
     "text": "Play session",
@@ -375,7 +433,14 @@ Response:
     "class": "android.widget.TextView",
     "bounds": [519, 1770, 762, 1830],
     "index": 11
-  }
+  },
+  "observed": {
+    "status": "success",
+    "matched_count": 1,
+    "condition_satisfied": true,
+    "selected_index": 11
+  },
+  "reason": "selector is visible"
 }
 ```
 
@@ -384,4 +449,5 @@ Notes:
 - Primary and authoritative verification tool for expected element visibility.
 - `selector` is the primary input; `element_id` is optional context only.
 - The tool resolves the selector internally when needed.
+- On failure, `reason` and `observed` tell you whether the selector was missing entirely or present but not yet visible.
 - Use when the screen should remain on the same destination but a specific element should appear or become visible.

package/docs/tools/manage.md

@@ -123,10 +123,23 @@ start_app response example:
   "action_id": "start_app_1710000000000_1",
   "timestamp": 1710000000000,
   "action_type": "start_app",
+  "device": { "platform": "android", "id": "emulator-5554", "osVersion": "14", "model": "Pixel", "simulator": true },
   "target": { "selector": { "appId": "com.example.app" }, "resolved": null },
   "success": true,
   "ui_fingerprint_before": "fp_before",
-  "ui_fingerprint_after": "fp_after"
+  "ui_fingerprint_after": "fp_after",
+  "details": {
+    "launch_time_ms": 1000,
+    "output": "Events injected: 1",
+    "device_id": "emulator-5554",
+    "observed_app": {
+      "appId": "com.example.app",
+      "package": "com.example.app",
+      "activity": "com.example.app.MainActivity",
+      "screen": "MainActivity",
+      "matchedTarget": true
+    }
+  }
 }
 ```
 
@@ -137,5 +150,7 @@ terminate_app and reset_app_data return operation-specific lifecycle results ins
 Notes:
 
 - `start_app` and `restart_app` report execution success, not outcome correctness.
+- Use `details.observed_app` as the quick decision signal for what the tool actually saw after launch.
+- Android launch feedback usually includes package/activity matching; iOS launch feedback includes launch output and PID when available.
 - When the landing screen is known, use `expect_screen` as the final verification step.
 - If launch timing is uncertain, insert `wait_for_screen_change` before `expect_screen`.

package/docs/tools/system.md

@@ -16,6 +16,7 @@ Response (example):
 ```json
 {
   "success": true,
+  "status": "ready",
   "adbAvailable": true,
   "adbVersion": "8.1.0",
   "devices": 1,
@@ -25,7 +26,26 @@ Response (example):
   "issues": [],
   "appInstalled": true,
   "iosAvailable": true,
-  "iosDevices": 1
+  "iosDevices": 1,
+  "summary": {
+    "overall": "ready",
+    "android": {
+      "ready": true,
+      "summary": "1 Android device(s) connected; log access available",
+      "blockers": []
+    },
+    "ios": {
+      "ready": true,
+      "summary": "1 iOS simulator(s) booted",
+      "blockers": []
+    },
+    "gradle": {
+      "ready": true,
+      "summary": "No explicit Gradle JDK override detected",
+      "blockers": [],
+      "suggestedFixes": []
+    }
+  }
 }
 ```
 
@@ -39,6 +59,8 @@ Checks performed (fast, best-effort):
 
 Behavior notes:
 - Always returns structured JSON and never throws; any failures are surfaced in the `issues` array.
+- `status` gives a quick overall gate: `ready`, `degraded`, or `blocked`.
+- `summary.android`, `summary.ios`, and `summary.gradle` provide the fastest path to the actual blocker category.
 - Designed to be fast (<~1s probes where possible); startup callers may prefer a `fastMode` variant that only checks existence.
 - Useful to call at the start of an agent session to gate subsequent actions.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {

package/src/interact/index.ts

@@ -490,6 +490,12 @@ export class ToolsInteract {
 
   static async waitForUIHandler({ selector, condition = 'exists', timeout_ms = 60000, poll_interval_ms = 300, match, retry = { max_attempts: 1, backoff_ms: 0 }, platform, deviceId }: { selector?: { text?: string, resource_id?: string, accessibility_id?: string, contains?: boolean }, condition?: 'exists'|'not_exists'|'visible'|'clickable', timeout_ms?: number, poll_interval_ms?: number, match?: { index?: number }, retry?: { max_attempts?: number, backoff_ms?: number }, platform?: 'android'|'ios', deviceId?: string }) {
     const overallStart = Date.now()
+    const requestedIndex = typeof match?.index === 'number' ? match.index : null
+    const requested = {
+      selector: selector ?? {},
+      condition,
+      match: requestedIndex === null ? null : { index: requestedIndex }
+    }
 
     // Validate selector: require at least one non-empty field (text, resource_id, or accessibility_id)
     const hasText = typeof selector?.text === 'string' && selector.text.trim().length > 0;
@@ -503,18 +509,20 @@ export class ToolsInteract {
           code: 'INVALID_SELECTOR',
           message: 'Selector must include at least one non-empty field: text, resource_id, or accessibility_id'
         },
-        metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 }
+        metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 },
+        requested,
+        observed: { matched_count: 0, condition_satisfied: false, selected_index: null, last_matched_element: null }
       };
     }
 
     // Validate condition
     if (!['exists','not_exists','visible','clickable'].includes(condition)) {
-      return { status: 'timeout', error: { code: 'INVALID_CONDITION', message: `Unsupported condition: ${condition}` }, metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 } }
+      return { status: 'timeout', error: { code: 'INVALID_CONDITION', message: `Unsupported condition: ${condition}` }, metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 }, requested, observed: { matched_count: 0, condition_satisfied: false, selected_index: null, last_matched_element: null } }
     }
 
     // Platform check
     if (platform && !['android','ios'].includes(platform)) {
-      return { status: 'timeout', error: { code: 'PLATFORM_NOT_SUPPORTED', message: `Unsupported platform: ${platform}` }, metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 } }
+      return { status: 'timeout', error: { code: 'PLATFORM_NOT_SUPPORTED', message: `Unsupported platform: ${platform}` }, metrics: { latency_ms: Date.now() - overallStart, poll_count: 0, attempts: 0 }, requested, observed: { matched_count: 0, condition_satisfied: false, selected_index: null, last_matched_element: null } }
     }
 
     const effectivePoll = Math.max(50, Math.min(poll_interval_ms || 300, 2000))
@@ -523,6 +531,9 @@ export class ToolsInteract {
 
     let attempts = 0
     let totalPollCount = 0
+    let lastMatchedCount = 0
+    let lastMatchedElement: ActionTargetResolved | null = null
+    let lastConditionSatisfied = false
 
     // Precompute normalized selector values and helpers (constant across polls)
     const normalize = ToolsInteract._normalize
@@ -623,19 +634,29 @@ export class ToolsInteract {
               } else conditionMet = false
             }
 
+            const resolvedPlatform = tree?.device?.platform === 'ios' ? 'ios' : (platform || 'android')
+            const resolvedDeviceId = tree?.device?.id || deviceId
+            lastMatchedCount = matchedCount
+            lastConditionSatisfied = conditionMet
+            lastMatchedElement = matchedElement ? ToolsInteract._buildResolvedElement(resolvedPlatform, resolvedDeviceId, matchedElement.el, matchedElement.idx) : null
+
             if (conditionMet) {
               const now = Date.now()
               const latency_ms = now - overallStart
-              // Build element output per spec
-              const resolvedPlatform = tree?.device?.platform === 'ios' ? 'ios' : (platform || 'android')
-              const resolvedDeviceId = tree?.device?.id || deviceId
-              const outEl = matchedElement ? ToolsInteract._buildResolvedElement(resolvedPlatform, resolvedDeviceId, matchedElement.el, matchedElement.idx) : null
+              const outEl = lastMatchedElement
 
               return {
                 status: 'success',
                 matched: matchedCount,
                 element: outEl,
-                metrics: { latency_ms, poll_count: totalPollCount, attempts }
+                metrics: { latency_ms, poll_count: totalPollCount, attempts },
+                requested,
+                observed: {
+                  matched_count: matchedCount,
+                  condition_satisfied: true,
+                  selected_index: outEl?.index ?? null,
+                  last_matched_element: outEl
+                }
               }
             }
 
@@ -656,16 +677,38 @@ export class ToolsInteract {
 
         // Final failure for this call
         const elapsed = Date.now() - overallStart
+        const observed = {
+          matched_count: lastMatchedCount,
+          condition_satisfied: lastConditionSatisfied,
+          selected_index: lastMatchedElement?.index ?? null,
+          last_matched_element: lastMatchedElement
+        }
+        const matchNote = requestedIndex !== null && lastMatchedCount <= requestedIndex
+          ? ` requested match.index=${requestedIndex} but observed ${lastMatchedCount} match(es)`
+          : ` observed ${lastMatchedCount} match(es)`
         return {
           status: 'timeout',
-          error: { code: 'ELEMENT_NOT_FOUND', message: `Condition ${condition} not satisfied within timeout` },
-          metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts }
+          error: { code: 'ELEMENT_NOT_FOUND', message: `Condition ${condition} not satisfied within timeout;${matchNote}` },
+          metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts },
+          requested,
+          observed
         }
       }
 
     } catch (err) {
       const elapsed = Date.now() - overallStart
-      return { status: 'timeout', error: { code: 'INTERNAL_ERROR', message: err instanceof Error ? err.message : String(err) }, metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts } }
+      return {
+        status: 'timeout',
+        error: { code: 'INTERNAL_ERROR', message: err instanceof Error ? err.message : String(err) },
+        metrics: { latency_ms: elapsed, poll_count: totalPollCount, attempts },
+        requested,
+        observed: {
+          matched_count: lastMatchedCount,
+          condition_satisfied: false,
+          selected_index: lastMatchedElement?.index ?? null,
+          last_matched_element: lastMatchedElement
+        }
+      }
     }
   }
 
@@ -682,11 +725,13 @@ export class ToolsInteract {
   static async waitForScreenChangeHandler({ platform, previousFingerprint, timeoutMs = 5000, pollIntervalMs = 300, deviceId }: { platform?: 'android' | 'ios', previousFingerprint: string, timeoutMs?: number, pollIntervalMs?: number, deviceId?: string }) {
     const start = Date.now()
     let lastFingerprint: string | null = null
+    let lastActivity: string | null = null
 
     while (Date.now() - start < timeoutMs) {
       try {
         const res = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null
         const fp = res?.fingerprint ?? null
+        lastActivity = (res as any)?.activity ?? lastActivity
         if (fp === null || fp === undefined) {
           lastFingerprint = null
           await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
@@ -701,8 +746,18 @@ export class ToolsInteract {
               try {
             const confirmRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null
             const confirmFp = confirmRes?.fingerprint ?? null
+            lastActivity = (confirmRes as any)?.activity ?? lastActivity
             if (confirmFp === fp) {
-              return { success: true, newFingerprint: fp, elapsedMs: Date.now() - start }
+              return {
+                success: true,
+                previousFingerprint,
+                newFingerprint: fp,
+                elapsedMs: Date.now() - start,
+                observed_screen: {
+                  fingerprint: fp,
+                  activity: lastActivity
+                }
+              }
             }
             lastFingerprint = confirmFp
             continue
@@ -713,7 +768,17 @@ export class ToolsInteract {
       await new Promise(resolve => setTimeout(resolve, pollIntervalMs))
     }
 
-    return { success: false, reason: 'timeout', lastFingerprint, elapsedMs: Date.now() - start }
+    return {
+      success: false,
+      reason: 'timeout',
+      previousFingerprint,
+      lastFingerprint,
+      elapsedMs: Date.now() - start,
+      observed_screen: {
+        fingerprint: lastFingerprint,
+        activity: lastActivity
+      }
+    }
   }
 
   static async expectScreenHandler({
@@ -749,13 +814,23 @@ export class ToolsInteract {
     }
 
     let success = false
+    let basis: 'fingerprint' | 'screen' | 'none' = 'none'
+    let reason = 'No fingerprint or screen expectation provided'
     if (fingerprint) {
+      basis = 'fingerprint'
       success = observedScreen.fingerprint === fingerprint
+      reason = success
+        ? `observed fingerprint matches expected fingerprint ${fingerprint}`
+        : `expected fingerprint ${fingerprint} but observed ${observedScreen.fingerprint ?? 'null'}`
     } else if (screen) {
+      basis = 'screen'
       const candidates = new Set<string>()
       if (observedScreen.screen) candidates.add(observedScreen.screen)
       if (observedScreenLabel) candidates.add(observedScreenLabel)
       success = candidates.has(screen)
+      reason = success
+        ? `observed screen matches expected screen ${screen}`
+        : `expected screen ${screen} but observed ${observedScreenLabel ?? observedScreen.screen ?? 'null'}`
     }
 
     return {
@@ -765,7 +840,12 @@ export class ToolsInteract {
         screen: observedScreenLabel
       },
       expected_screen: expectedScreen,
-      confidence: success ? 1 : 0
+      confidence: success ? 1 : 0,
+      comparison: {
+        basis,
+        matched: success,
+        reason
+      }
     }
   }
 
@@ -798,6 +878,7 @@ export class ToolsInteract {
         success: true,
         selector,
         element_id: result.element.elementId ?? element_id ?? null,
+        expected_condition: 'visible',
         element: {
           elementId: result.element.elementId ?? null,
           text: result.element.text ?? null,
@@ -806,7 +887,23 @@ export class ToolsInteract {
           class: result.element.class ?? null,
           bounds: result.element.bounds ?? null,
           index: typeof result.element.index === 'number' ? result.element.index : null
-        }
+        },
+        observed: {
+          status: result.status,
+          matched_count: typeof result.matched === 'number' ? result.matched : result?.observed?.matched_count ?? null,
+          condition_satisfied: true,
+          selected_index: typeof result.element.index === 'number' ? result.element.index : null,
+          last_matched_element: {
+            elementId: result.element.elementId ?? null,
+            text: result.element.text ?? null,
+            resource_id: result.element.resource_id ?? null,
+            accessibility_id: result.element.accessibility_id ?? null,
+            class: result.element.class ?? null,
+            bounds: result.element.bounds ?? null,
+            index: typeof result.element.index === 'number' ? result.element.index : null
+          }
+        },
+        reason: 'selector is visible'
       }
     }
 
@@ -815,6 +912,15 @@ export class ToolsInteract {
       success: false,
       selector,
       element_id: element_id ?? null,
+      expected_condition: 'visible',
+      observed: {
+        status: result?.status,
+        matched_count: result?.observed?.matched_count,
+        condition_satisfied: result?.observed?.condition_satisfied ?? false,
+        selected_index: result?.observed?.selected_index ?? null,
+        last_matched_element: result?.observed?.last_matched_element ?? null
+      },
+      reason: result?.error?.message ?? 'selector is not visible',
       failure_code: errorCode,
       retryable: errorCode === 'TIMEOUT'
     }

package/src/manage/android.ts

@@ -5,9 +5,14 @@ import { existsSync } from 'fs'
 import { execAdb, spawnAdb, getAndroidDeviceMetadata, getDeviceInfo, findApk } from '../utils/android/utils.js'
 import { execAdbWithDiagnostics } from '../utils/diagnostics.js'
 import { detectJavaHome } from '../utils/java.js'
+import { AndroidObserve } from '../observe/android.js'
 import { InstallAppResponse, StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse } from '../types.js'
 
 export class AndroidManage {
+  private isTestOnlyInstallFailure(output: string | undefined): boolean {
+    return typeof output === 'string' && output.includes('INSTALL_FAILED_TEST_ONLY')
+  }
+
   async build(projectPath: string, _variant?: string): Promise<{ artifactPath: string, output?: string } | { error: string }> {
     void _variant
     try {
@@ -92,6 +97,14 @@ export class AndroidManage {
         if (res.code === 0) {
           return { device: deviceInfo, installed: true, output: res.stdout }
         }
+
+        const installOutput = `${res.stdout}\n${res.stderr}`.trim()
+        if (this.isTestOnlyInstallFailure(installOutput)) {
+          const retryRes = await spawnAdb(['install', '-r', '-t', apkToInstall], deviceId)
+          if (retryRes.code === 0) {
+            return { device: deviceInfo, installed: true, output: retryRes.stdout }
+          }
+        }
       } catch (e) {
         console.debug('[android-run] adb install failed, attempting push+pm fallback:', e instanceof Error ? e.message : String(e))
       }
@@ -99,9 +112,21 @@ export class AndroidManage {
       const basename = path.basename(apkToInstall)
       const remotePath = `/data/local/tmp/${basename}`
       await execAdb(['push', apkToInstall, remotePath], deviceId)
-      const pmOut = await execAdb(['shell', 'pm', 'install', '-r', remotePath], deviceId)
-      try { await execAdb(['shell', 'rm', remotePath], deviceId) } catch {}
-      return { device: deviceInfo, installed: true, output: pmOut }
+      let finalPmRes = await spawnAdb(['shell', 'pm', 'install', '-r', remotePath], deviceId)
+      try {
+        if (finalPmRes.code === 0) {
+          return { device: deviceInfo, installed: true, output: finalPmRes.stdout }
+        }
+        if (this.isTestOnlyInstallFailure(`${finalPmRes.stdout}\n${finalPmRes.stderr}`)) {
+          finalPmRes = await spawnAdb(['shell', 'pm', 'install', '-r', '-t', remotePath], deviceId)
+          if (finalPmRes.code === 0) {
+            return { device: deviceInfo, installed: true, output: finalPmRes.stdout }
+          }
+        }
+        throw new Error(finalPmRes.stderr || finalPmRes.stdout || 'pm install failed')
+      } finally {
+        try { await execAdb(['shell', 'rm', remotePath], deviceId) } catch {}
+      }
     } catch (e) {
       // gather diagnostics for attempted adb operations
       const basename = path.basename(apkToInstall)
@@ -117,8 +142,21 @@ export class AndroidManage {
     const metadata = await getAndroidDeviceMetadata(appId, deviceId)
     const deviceInfo = getDeviceInfo(deviceId || 'default', metadata)
     try {
-      await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId)
-      return { device: deviceInfo, appStarted: true, launchTimeMs: 1000 }
+      const output = await execAdb(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId)
+      const current = await new AndroidObserve().getCurrentScreen(deviceId).catch(() => null)
+      return {
+        device: deviceInfo,
+        appStarted: true,
+        launchTimeMs: 1000,
+        output,
+        observedApp: {
+          appId,
+          package: current?.package ?? null,
+          activity: current?.activity ?? null,
+          screen: current?.shortActivity ?? current?.activity ?? null,
+          matchedTarget: current ? current.package === appId : null
+        }
+      }
     } catch (e: unknown) {
       const diag = execAdbWithDiagnostics(['shell', 'monkey', '-p', appId, '-c', 'android.intent.category.LAUNCHER', '1'], deviceId)
       return { device: deviceInfo, appStarted: false, launchTimeMs: 0, error: e instanceof Error ? e.message : String(e), diagnostics: diag }
@@ -138,12 +176,18 @@ export class AndroidManage {
   }
 
   async restartApp(appId: string, deviceId?: string): Promise<RestartAppResponse> {
-    await this.terminateApp(appId, deviceId)
+    const terminateResult = await this.terminateApp(appId, deviceId)
     const startResult = await this.startApp(appId, deviceId)
     return {
       device: startResult.device,
       appRestarted: startResult.appStarted,
-      launchTimeMs: startResult.launchTimeMs
+      launchTimeMs: startResult.launchTimeMs,
+      output: startResult.output,
+      observedApp: startResult.observedApp,
+      terminatedBeforeRestart: terminateResult.appTerminated,
+      ...(terminateResult.error ? { terminateError: terminateResult.error } : {}),
+      ...(startResult.error ? { error: startResult.error } : {}),
+      ...(startResult.diagnostics ? { diagnostics: startResult.diagnostics } : {})
     }
   }
 

package/src/manage/ios.ts

@@ -2,6 +2,7 @@ import { promises as fs } from "fs"
 import { spawn, spawnSync } from "child_process"
 import { StartAppResponse, TerminateAppResponse, RestartAppResponse, ResetAppDataResponse, InstallAppResponse } from "../types.js"
 import { execCommand, execCommandWithDiagnostics, getIOSDeviceMetadata, validateBundleId, getIdbCmd, findAppBundle } from "../utils/ios/utils.js"
+import { iOSObserve } from "../observe/ios.js"
 import path from "path"
 
 export class iOSManage {
@@ -301,7 +302,20 @@ export class iOSManage {
     try {
       const result = await execCommand(['simctl', 'launch', deviceId, bundleId], deviceId)
       const device = await getIOSDeviceMetadata(deviceId)
-      return { device, appStarted: !!result.output, launchTimeMs: 1000 }
+      const fingerprint = await new iOSObserve().getScreenFingerprint(deviceId).catch(() => null)
+      const pidMatch = result.output.match(/:\s*(\d+)\s*$/)
+      return {
+        device,
+        appStarted: !!result.output,
+        launchTimeMs: 1000,
+        output: result.output,
+        observedApp: {
+          appId: bundleId,
+          pid: pidMatch ? Number(pidMatch[1]) : null,
+          screen: fingerprint?.activity ?? null,
+          matchedTarget: null
+        }
+      }
     } catch (e: unknown) {
       const diag = execCommandWithDiagnostics(['simctl', 'launch', deviceId, bundleId], deviceId)
       const device = await getIOSDeviceMetadata(deviceId)
@@ -323,9 +337,19 @@ export class iOSManage {
   }
 
   async restartApp(bundleId: string, deviceId: string = "booted"): Promise<RestartAppResponse> {
-    await this.terminateApp(bundleId, deviceId)
+    const terminateResult = await this.terminateApp(bundleId, deviceId)
     const startResult = await this.startApp(bundleId, deviceId)
-    return { device: startResult.device, appRestarted: startResult.appStarted, launchTimeMs: startResult.launchTimeMs }
+    return {
+      device: startResult.device,
+      appRestarted: startResult.appStarted,
+      launchTimeMs: startResult.launchTimeMs,
+      output: startResult.output,
+      observedApp: startResult.observedApp,
+      terminatedBeforeRestart: terminateResult.appTerminated,
+      ...(terminateResult.error ? { terminateError: terminateResult.error } : {}),
+      ...(startResult.error ? { error: startResult.error } : {}),
+      ...(startResult.diagnostics ? { diagnostics: startResult.diagnostics } : {})
+    }
   }
 
   async resetAppData(bundleId: string, deviceId: string = "booted"): Promise<ResetAppDataResponse> {