mobile-debug-mcp 0.24.1 → 0.24.2

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.1",
+  "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,6 +5,7 @@ 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 {
@@ -141,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 }
@@ -162,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> {

package/src/server/common.ts

@@ -63,26 +63,31 @@ export function inferScrollFailure(message: string | undefined): { failureCode:
 
 export function buildActionExecutionResult({
   actionType,
+  device,
   selector,
   resolved,
   success,
   uiFingerprintBefore,
   uiFingerprintAfter,
-  failure
+  failure,
+  details
 }: {
   actionType: string
+  device?: ActionExecutionResult['device']
   selector: Record<string, unknown> | null
   resolved?: Partial<ActionTargetResolved> | null
   success: boolean
   uiFingerprintBefore: string | null
   uiFingerprintAfter: string | null
   failure?: { failureCode: ActionFailureCode; retryable: boolean }
+  details?: Record<string, unknown>
 }): ActionExecutionResult {
   const timestamp = Date.now()
   return {
     action_id: nextActionId(actionType, timestamp),
     timestamp,
     action_type: actionType,
+    ...(device ? { device } : {}),
     target: {
       selector,
       resolved: normalizeResolvedTarget(resolved)
@@ -90,6 +95,7 @@ export function buildActionExecutionResult({
     success,
     ...(failure ? { failure_code: failure.failureCode, retryable: failure.retryable } : {}),
     ui_fingerprint_before: uiFingerprintBefore,
-    ui_fingerprint_after: uiFingerprintAfter
+    ui_fingerprint_after: uiFingerprintAfter,
+    ...(details ? { details } : {})
   }
 }

package/src/server/tool-handlers.ts

@@ -27,11 +27,19 @@ async function handleStartApp(args: ToolCallArgs) {
   const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId)
   return wrapResponse(buildActionExecutionResult({
     actionType: 'start_app',
+    device: res.device,
     selector: { appId },
     success: !!res.appStarted,
     uiFingerprintBefore,
     uiFingerprintAfter,
-    failure: res.appStarted ? undefined : inferGenericFailure((res as any).error)
+    failure: res.appStarted ? undefined : inferGenericFailure(res.error),
+    details: {
+      launch_time_ms: res.launchTimeMs,
+      ...(typeof res.output === 'string' ? { output: res.output } : {}),
+      ...(res.device ? { device_id: res.device.id } : {}),
+      ...(typeof res.error === 'string' ? { error: res.error } : {}),
+      ...(res.observedApp ? { observed_app: res.observedApp } : {})
+    }
   }))
 }
 
@@ -50,11 +58,20 @@ async function handleRestartApp(args: ToolCallArgs) {
   const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId)
   return wrapResponse(buildActionExecutionResult({
     actionType: 'restart_app',
+    device: res.device,
     selector: { appId },
     success: !!res.appRestarted,
     uiFingerprintBefore,
     uiFingerprintAfter,
-    failure: res.appRestarted ? undefined : inferGenericFailure((res as any).error)
+    failure: res.appRestarted ? undefined : inferGenericFailure(res.error),
+    details: {
+      launch_time_ms: res.launchTimeMs,
+      ...(typeof res.output === 'string' ? { output: res.output } : {}),
+      ...(typeof res.terminatedBeforeRestart === 'boolean' ? { terminated_before_restart: res.terminatedBeforeRestart } : {}),
+      ...(typeof res.terminateError === 'string' ? { terminate_error: res.terminateError } : {}),
+      ...(typeof res.error === 'string' ? { error: res.error } : {}),
+      ...(res.observedApp ? { observed_app: res.observedApp } : {})
+    }
   }))
 }
 

package/src/system/index.ts

@@ -10,8 +10,34 @@ export async function getSystemStatus() {
     const issues = [...android.issues, ...ios.issues, ...(gradle.issues || [])]
 
     const success = issues.length === 0
+    const androidReady = android.adbAvailable && android.devices > 0 && !android.issues.some((issue) => /unauthorized|offline/i.test(issue))
+    const iosReady = ios.iosAvailable && ios.iosDevices > 0
+    const gradleReady = (gradle.issues || []).length === 0
+    const overallStatus = success ? 'ready' : (androidReady || iosReady ? 'degraded' : 'blocked')
+
+    const androidSummary = !android.adbAvailable
+      ? 'ADB unavailable'
+      : android.devices === 0
+        ? 'ADB available but no Android devices connected'
+        : android.logsAvailable
+          ? `${android.devices} Android device(s) connected; log access available`
+          : `${android.devices} Android device(s) connected; log access unavailable`
+
+    const iosSummary = !ios.iosAvailable
+      ? 'xcrun unavailable'
+      : ios.iosDevices === 0
+        ? 'xcrun available but no iOS simulators booted'
+        : `${ios.iosDevices} iOS simulator(s) booted`
+
+    const gradleSummary = !gradle.gradleJavaHome
+      ? 'No explicit Gradle JDK override detected'
+      : gradleReady
+        ? `Gradle JDK configured at ${gradle.gradleJavaHome}`
+        : `Gradle JDK override invalid: ${gradle.gradleJavaHome}`
+
     return {
       success,
+      status: overallStatus,
       adbAvailable: android.adbAvailable,
       adbVersion: android.adbVersion,
       devices: android.devices,
@@ -25,9 +51,38 @@ export async function getSystemStatus() {
       gradleJavaHome: gradle.gradleJavaHome,
       gradleValid: gradle.gradleValid,
       gradleFilesChecked: gradle.filesChecked,
-      gradleSuggestedFixes: gradle.suggestedFixes
+      gradleSuggestedFixes: gradle.suggestedFixes,
+      summary: {
+        overall: overallStatus,
+        android: {
+          ready: androidReady,
+          summary: androidSummary,
+          blockers: android.issues
+        },
+        ios: {
+          ready: iosReady,
+          summary: iosSummary,
+          blockers: ios.issues
+        },
+        gradle: {
+          ready: gradleReady,
+          summary: gradleSummary,
+          blockers: gradle.issues || [],
+          suggestedFixes: gradle.suggestedFixes || []
+        }
+      }
     }
   } catch (e: unknown) {
-    return { success: false, issues: ['Internal error: ' + (e instanceof Error ? e.message : String(e))] }
+    return {
+      success: false,
+      status: 'blocked',
+      issues: ['Internal error: ' + (e instanceof Error ? e.message : String(e))],
+      summary: {
+        overall: 'blocked',
+        android: { ready: false, summary: 'Android status unavailable', blockers: [] },
+        ios: { ready: false, summary: 'iOS status unavailable', blockers: [] },
+        gradle: { ready: false, summary: 'Gradle status unavailable', blockers: [], suggestedFixes: [] }
+      }
+    }
   }
 }