mobile-debug-mcp 0.20.0 → 0.21.0

package/src/interact/index.ts

@@ -29,7 +29,6 @@ interface UiElement {
   _interactable?: boolean
 }
 
-const STABLE_IDLE_MS = 1000
 
 export class ToolsInteract {
 
@@ -262,76 +261,105 @@ export class ToolsInteract {
     return { success: false, reason: 'timeout', lastFingerprint, elapsedMs: Date.now() - start }
   }
 
-  static async observeUntilHandler({ type, query, timeoutMs = 5000, pollIntervalMs = 200, platform, deviceId }: { type: 'ui' | 'log' | 'screen' | 'idle', query?: string, timeoutMs?: number, pollIntervalMs?: number, platform?: 'android' | 'ios', deviceId?: string }) {
+  static async observeUntilHandler({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }: { type?: 'ui' | 'log' | 'screen' | 'idle', query?: string, timeoutMs?: number, pollIntervalMs?: number, includeSnapshotOnFailure?: boolean, match?: 'present'|'absent', stability_ms?: number, observationDelayMs?: number, platform?: 'android' | 'ios', deviceId?: string }) {
     const start = Date.now()
     const deadline = start + (timeoutMs || 0)
     const q = (query === null || query === undefined) ? '' : String(query)
 
-    // Baseline state
-    let initialFingerprint: string | null = null
-    try {
-      const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null
-      initialFingerprint = fpRes?.fingerprint ?? null
-    } catch (err) { console.error('observeUntil: error getting initial fingerprint', err); initialFingerprint = null }
+    // Clamp polling interval to 250-500ms for consistent behavior
+    const pollInterval = Math.max(250, Math.min(pollIntervalMs || 300, 500))
 
-    // For logs, capture a baseline snapshot (count or last line) to avoid matching historical lines
+    // Baseline state (fetch in parallel but bound to short timeouts so observation starts promptly)
+    let initialFingerprint: string | null = null
     let baselineLastLine: string | null = null
     try {
-      const gl = await ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 })
-      const logsArr = Array.isArray((gl as any).logs) ? (gl as any).logs : []
-      baselineLastLine = logsArr.length ? logsArr[logsArr.length - 1] : null
+      const fpPromise = ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as Promise<ScreenFingerprintResponse | null>
+      const logsPromise = ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 }) as Promise<any>
+      const withTimeout = (p: Promise<any>, ms: number) => Promise.race([p, new Promise(resolve => setTimeout(() => resolve(null), ms))])
+      const [fpRes, gl] = await Promise.all([withTimeout(fpPromise, 300), withTimeout(logsPromise, 500)])
+      if (fpRes && typeof fpRes === 'object') initialFingerprint = (fpRes as ScreenFingerprintResponse).fingerprint ?? null
+      if (gl) {
+        const logsArr = Array.isArray((gl as any).logs) ? (gl as any).logs : []
+        baselineLastLine = logsArr.length ? logsArr[logsArr.length - 1] : null
+      }
     } catch (err) {
-      // non-fatal but surface warning to aid debugging
-      try { console.warn('observeUntil: failed to get baseline logs (non-fatal):', err instanceof Error ? err.message : String(err)) } catch { }
+      try { console.warn('observeUntil: failed to get baseline data (non-fatal):', err instanceof Error ? err.message : String(err)) } catch { }
     }
 
-    
+    // Network-based waiting removed. Rely on UI and screen fingerprints for determinism.
     let lastChangeAt = Date.now()
     let prevFingerprint = initialFingerprint
 
     const sleep = (ms: number) => new Promise(r => setTimeout(r, ms))
 
+    // Optional initial observation delay requested by caller
+    if (typeof observationDelayMs === 'number' && observationDelayMs > 0) {
+      try { console.log(`observeUntil: delaying observation for ${observationDelayMs}ms`) } catch { }
+      await sleep(observationDelayMs)
+    }
+
     // Telemetry
     let pollCount = 0
-    let timeToMatch: number | null = null
+    let matchedAt: number | null = null
+    let lastObservedState: boolean | null = null
+    let stableDuration = 0
     let matchSource: string | null = null
 
     while (Date.now() <= deadline) {
       pollCount++
-      try {
+        const now = Date.now()
+        // Evaluate condition per type
         if (type === 'ui') {
-          // fast findElement with short timeout to avoid blocking
           try {
-            const found = await ToolsInteract.findElementHandler({ query: q, exact: false, timeoutMs: Math.min(500, timeoutMs || 500), platform, deviceId })
-            if (found && (found as any).found) {
-              timeToMatch = Date.now() - start
-              // determine matchSource heuristics
-              const el = (found as any).element || {}
-              if (el && el.resourceId && String(el.resourceId).toLowerCase().includes(q.toLowerCase())) matchSource = 'ui-resourceId'
-              else if (el && el.text && String(el.text).toLowerCase() === q.toLowerCase()) matchSource = 'ui-exact'
-              else matchSource = 'ui-partial'
-
-              return { success: true, type: 'ui', matched: true, details: `UI element matched '${q}'`, timestamp: Date.now(), element: (found as any).element, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } }
-            }
+                // Lightweight UI check: fetch UI tree and perform a normalized substring match to reduce overhead
+            try {
+              // Bound the UI tree fetch to avoid long blocking calls; prefer quick failure over hanging a poll
+              const withTimeout = (p: Promise<any>, ms: number) => Promise.race([p, new Promise(resolve => setTimeout(()=>resolve(null), ms))])
+              const tree = await withTimeout(ToolsObserve.getUITreeHandler({ platform, deviceId }), Math.min(pollInterval, 500)) as any
+              const elems = Array.isArray(tree && tree.elements) ? tree.elements : []
+              const qnorm = q.toLowerCase()
+              let matched: any = null
+              for (const el of elems) {
+                try {
+                  const txt = ((el && (el.text || el.label || el.value || el.contentDescription || el.accessibilityLabel)) || '')
+                  if (!txt) continue
+                  if (String(txt).toLowerCase().includes(qnorm)) { matched = el; break }
+                } catch { continue }
+              }
+              const isPresent = !!matched
+              const conditionTrue = (match === 'present') ? isPresent : !isPresent
+              if (conditionTrue) {
+                if (matchedAt === null) matchedAt = Date.now()
+                stableDuration = Date.now() - (matchedAt as number)
+                lastObservedState = true
+                if (stableDuration >= stability_ms) {
+                  matchSource = 'ui-tree-' + (match === 'present' ? 'present' : 'absent')
+                  const element = isPresent ? matched : null
+                  const now2 = Date.now()
+                  return { success: true, condition: match, query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: stableDuration, matchedElement: element, matchSource, timestamp: now2, type: 'ui', observed_state: lastObservedState ?? null }
+                }
+              } else {
+                matchedAt = null
+                stableDuration = 0
+                lastObservedState = false
+              }
+            } catch (err) { console.error('observeUntil(ui) tree error:', err) }
           } catch (err) { console.error('observeUntil(ui) find error:', err) }
         } else if (type === 'log') {
           try {
-            // Try reading from active stream first
+            // Logs: presence semantics only (match 'present'). Stability not applicable (immediate)
             const stream = await ToolsObserve.readLogStreamHandler({ platform, sessionId: 'default', limit: 200 }) as any
             const entries = (stream && Array.isArray(stream.entries)) ? stream.entries : []
             for (const ent of entries) {
               const msg = ent && (ent.message || ent.msg || ent) ? (ent.message || ent.msg || ent) : ''
               if (q && String(msg).includes(q)) {
-                timeToMatch = Date.now() - start
-                matchSource = 'log-stream'
-                return { success: true, type: 'log', matched: true, details: `Log matched '${q}'`, timestamp: Date.now(), log: { message: msg, raw: ent }, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } }
+                const now2 = Date.now()
+                return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: 0, matchedLog: { message: msg, raw: ent }, matchSource: 'log-stream', timestamp: now2, type: 'log', observed_state: true }
               }
             }
 
-            // Fallback to snapshot logs
             const gl = await ToolsObserve.getLogsHandler({ platform, deviceId, lines: 200 }) as any
             const logsArr = Array.isArray(gl && gl.logs) ? gl.logs : []
-            // Only consider new lines after baselineLastLine when possible
             let startIndex = 0
             if (baselineLastLine) {
               const idx = logsArr.lastIndexOf(baselineLastLine)
@@ -340,9 +368,8 @@ export class ToolsInteract {
             for (let i = startIndex; i < logsArr.length; i++) {
               const line = logsArr[i]
               if (q && String(line).includes(q)) {
-                timeToMatch = Date.now() - start
-                matchSource = 'log-snapshot'
-                return { success: true, type: 'log', matched: true, details: `Log matched '${q}'`, timestamp: Date.now(), log: { message: line }, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } }
+                const now2 = Date.now()
+                return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: 0, matchedLog: { message: line }, matchSource: 'log-snapshot', timestamp: now2, type: 'log', observed_state: true }
               }
             }
           } catch (err) { console.error('observeUntil(log) error:', err) }
@@ -351,21 +378,20 @@ export class ToolsInteract {
             const fpRes = await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null
             const fp = fpRes?.fingerprint ?? null
             if (fp !== null && fp !== undefined && fp !== initialFingerprint) {
-              if (q) {
-                // optionally validate query against new screen context
-                try {
-                  const found = await ToolsInteract.findElementHandler({ query: q, exact: false, timeoutMs: Math.min(500, timeoutMs || 500), platform, deviceId })
-                  if (found && (found as any).found) {
-                    timeToMatch = Date.now() - start
-                    matchSource = 'screen-validated-ui'
-                    return { success: true, type: 'screen', matched: true, details: `Screen changed and query matched on new screen`, timestamp: Date.now(), newFingerprint: fp, element: (found as any).element, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } }
-                  }
-                } catch (err) { console.error('observeUntil(screen) find error:', err) }
-                // If query provided but not matched yet, continue polling until timeout
+              // when screen changed, require stability_ms where fingerprint remains the same
+              if (matchedAt === null) matchedAt = now
+              const confirmFp = (await ToolsObserve.getScreenFingerprintHandler({ platform, deviceId }) as ScreenFingerprintResponse | null)?.fingerprint ?? null
+              if (confirmFp === fp) {
+                stableDuration = Date.now() - (matchedAt as number)
+                lastObservedState = true
+                if (stableDuration >= stability_ms) {
+                  const now2 = Date.now()
+                  return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: stableDuration, newFingerprint: fp, matchSource: 'screen-fingerprint', timestamp: now2, type: 'screen', observed_state: lastObservedState ?? null }
+                }
               } else {
-                timeToMatch = Date.now() - start
-                matchSource = 'screen-fingerprint'
-                return { success: true, type: 'screen', matched: true, details: 'Screen fingerprint changed', timestamp: Date.now(), newFingerprint: fp, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } }
+                matchedAt = null
+                stableDuration = 0
+                lastObservedState = false
               }
             }
           } catch (err) { console.error('observeUntil(screen) error:', err) }
@@ -376,33 +402,35 @@ export class ToolsInteract {
             if (fp !== prevFingerprint) {
               prevFingerprint = fp
               lastChangeAt = Date.now()
+              matchedAt = null
+              stableDuration = 0
+              lastObservedState = false
             } else {
-              if (Date.now() - lastChangeAt >= STABLE_IDLE_MS) {
-                timeToMatch = Date.now() - start
-                matchSource = 'idle-stable'
-                return { success: true, type: 'idle', matched: true, details: `UI stable for ${STABLE_IDLE_MS}ms`, timestamp: Date.now(), fingerprint: fp, telemetry: { pollCount, timeToMatch, elapsedMs: Date.now() - start, matchSource } }
+              const idleMs = Date.now() - lastChangeAt
+              lastObservedState = true
+              if (idleMs >= stability_ms) {
+                const now2 = Date.now()
+                return { success: true, condition: 'present', query: q, poll_count: pollCount, duration_ms: now2 - start, stable_duration_ms: idleMs, matchSource: 'idle-stable', timestamp: now2, type: 'idle', observed_state: lastObservedState ?? null }
               }
             }
           } catch (err) { console.error('observeUntil(idle) error:', err) }
         }
-      } catch (err) {
-        console.error('observeUntil: unexpected error', err)
-      }
 
       // Respect poll interval and avoid tight loop
-      await sleep(pollIntervalMs || 200)
+      await sleep(pollInterval)
     }
 
-    // On timeout, capture a failure snapshot to aid debugging (best-effort)
+    // On timeout, optionally capture a failure snapshot to aid debugging (best-effort)
     let snapshot: any = null
-    try {
-      snapshot = await ToolsObserve.captureDebugSnapshotHandler({ reason: `observe_until timeout for ${type}`, includeLogs: true, platform, deviceId })
-    } catch (err) {
-      snapshot = { error: err instanceof Error ? err.message : String(err) }
+    if (includeSnapshotOnFailure) {
+      try {
+        snapshot = await ToolsObserve.captureDebugSnapshotHandler({ reason: `observe_until timeout for ${type}`, includeLogs: true, platform, deviceId })
+      } catch (err) {
+        snapshot = { error: err instanceof Error ? err.message : String(err) }
+      }
     }
 
     const elapsed = Date.now() - start
-    return { success: false, error: 'Timeout waiting for condition', type, timeoutMs, telemetry: { pollCount, elapsedMs: elapsed, matchSource: null }, snapshot }
-  }
-
+    return { success: false, condition: match, query: q, poll_count: pollCount, duration_ms: elapsed, stable_duration_ms: stableDuration, error: 'Timeout waiting for condition', snapshot, observed_state: lastObservedState ?? null }
+  }  
 }

package/src/manage/android.ts

@@ -64,8 +64,12 @@ export class AndroidManage {
         const spawnOpts: any = { cwd: apkPath, env }
         if (useWrapper) {
           await fs.chmod(wrapperPath, 0o755).catch(() => {})
+          // Run wrapper directly to avoid shell splitting of args
           spawnOpts.shell = false
-        } else spawnOpts.shell = true
+        } else {
+          // Execute gradle directly without a shell so paths with spaces are preserved
+          spawnOpts.shell = false
+        }
 
         const proc = spawn(execCmd, gradleArgs, spawnOpts)
         let stderr = ''

package/src/server.ts

@@ -339,6 +339,26 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ["previousFingerprint"]
       }
     },
+    {
+      name: "observe_until",
+      description: "Wait for a UI condition (element present/absent) and require a stability window before returning success. Network-based waiting is not required; UI-only synchronization is the default and primary mode.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          type: { type: "string", enum: ["ui","log","screen","idle"], description: "Condition type to observe", default: "ui" },
+          query: { type: "string", description: "Optional query string for ui/log/screen types" },
+          timeoutMs: { type: "number", description: "Timeout in ms to wait for condition (default 30000)", default: 30000 },
+          pollIntervalMs: { type: "number", description: "Polling interval in ms (default 300, clamped to 250-500)", default: 300 },
+          match: { type: "string", enum: ["present","absent"], description: "Match mode for UI checks: 'present' or 'absent' (default 'present')", default: "present" },
+          stability_ms: { type: "number", description: "Stability window in ms that the condition must hold before returning success (default 700)", default: 700 },
+          includeSnapshotOnFailure: { type: "boolean", description: "Whether to include a debug snapshot on timeout (default true)", default: true },
+          platform: { type: "string", enum: ["android","ios"], description: "Optional platform override" },
+          deviceId: { type: "string", description: "Optional device serial/udid" }
+        }
+      }
+    },
+
+
     {
       name: "wait_for_element",
       description: "Wait until a UI element with matching text appears on screen or timeout is reached.",

package/src/system/gradle.ts

@@ -0,0 +1,98 @@
+import { readFileSync, existsSync } from 'fs'
+import path from 'path'
+import os from 'os'
+
+function readPropertiesFile(p: string): Record<string,string> {
+  try {
+    const txt = readFileSync(p, { encoding: 'utf8' })
+    const lines = String(txt).split(/\r?\n/)
+    const out: Record<string,string> = {}
+    for (const l of lines) {
+      const trimmed = l.trim()
+      if (!trimmed || trimmed.startsWith('#')) continue
+      const idx = trimmed.indexOf('=')
+      if (idx === -1) continue
+      const k = trimmed.substring(0, idx).trim()
+      const v = trimmed.substring(idx+1).trim()
+      out[k] = v
+    }
+    return out
+  } catch {
+    return {}
+  }
+}
+
+function javaBinExists(p?: string): boolean {
+  if (!p) return false
+  try {
+    const javaPath = path.join(p, 'bin', 'java')
+    if (existsSync(javaPath)) return true
+    const alt = path.join(p, 'Contents', 'Home', 'bin', 'java')
+    if (existsSync(alt)) return true
+    return false
+  } catch { return false }
+}
+
+export async function checkGradle(): Promise<{ gradleJavaHome?: string; gradleValid: boolean; filesChecked: string[]; issues: string[]; suggestedFixes?: string[] }> {
+  const issues: string[] = []
+  const filesChecked: string[] = []
+  const suggestedFixes: string[] = []
+  let gradleJavaHome: string | undefined
+
+  // 1) explicit env
+  if (process.env.GRADLE_JAVA_HOME) {
+    gradleJavaHome = process.env.GRADLE_JAVA_HOME
+    if (!javaBinExists(gradleJavaHome)) {
+      issues.push(`GRADLE_JAVA_HOME is set to '${gradleJavaHome}' but no java binary was found there`)
+      suggestedFixes.push('Unset GRADLE_JAVA_HOME or point it to a valid JDK (e.g., /Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home)')
+    }
+  }
+
+  // 2) user gradle.properties
+  const gradleUserHome = process.env.GRADLE_USER_HOME || path.join(os.homedir(), '.gradle')
+  const userProps = path.join(gradleUserHome, 'gradle.properties')
+  filesChecked.push(userProps)
+  try {
+    const props = readPropertiesFile(userProps)
+    if (props['org.gradle.java.home']) {
+      const p = props['org.gradle.java.home']
+      gradleJavaHome = gradleJavaHome || p
+      if (!javaBinExists(p)) {
+        issues.push(`org.gradle.java.home in ${userProps} points to '${p}' which does not look like a valid JDK`)
+        suggestedFixes.push(`Edit ${userProps} to remove or correct org.gradle.java.home`)
+      }
+    }
+  } catch { }
+
+  // 3) system gradle.properties
+  const systemProps = '/etc/gradle/gradle.properties'
+  filesChecked.push(systemProps)
+  try {
+    const props = readPropertiesFile(systemProps)
+    if (props['org.gradle.java.home']) {
+      const p = props['org.gradle.java.home']
+      gradleJavaHome = gradleJavaHome || p
+      if (!javaBinExists(p)) {
+        issues.push(`org.gradle.java.home in ${systemProps} points to '${p}' which does not look like a valid JDK`)
+        suggestedFixes.push(`Edit ${systemProps} to remove or correct org.gradle.java.home`)
+      }
+    }
+  } catch { }
+
+  // 4) GRADLE_HOME fallback
+  if (!gradleJavaHome && process.env.GRADLE_HOME) {
+    filesChecked.push(process.env.GRADLE_HOME)
+    if (javaBinExists(process.env.GRADLE_HOME)) {
+      gradleJavaHome = process.env.GRADLE_HOME
+    }
+  }
+
+  const gradleValid = !!gradleJavaHome && javaBinExists(gradleJavaHome)
+  if (!gradleJavaHome) {
+    // no explicit gradle java home detected — not an issue
+  } else if (!gradleValid) {
+    issues.push(`Detected org.gradle.java.home = '${gradleJavaHome}' but it is invalid`)
+  }
+
+  return { gradleJavaHome, gradleValid, filesChecked, issues, suggestedFixes }
+}

package/src/system/index.ts

@@ -1,11 +1,13 @@
 import { checkAndroid } from './android.js'
 import { checkIOS } from './ios.js'
+import { checkGradle } from './gradle.js'
 
 export async function getSystemStatus() {
   try {
     const android = await checkAndroid()
     const ios = await checkIOS()
-    const issues = [...android.issues, ...ios.issues]
+    const gradle = await checkGradle()
+    const issues = [...android.issues, ...ios.issues, ...(gradle.issues || [])]
 
     const success = issues.length === 0
     return {
@@ -19,7 +21,11 @@ export async function getSystemStatus() {
       issues,
       appInstalled: android.appInstalled,
       iosAvailable: ios.iosAvailable,
-      iosDevices: ios.iosDevices
+      iosDevices: ios.iosDevices,
+      gradleJavaHome: gradle.gradleJavaHome,
+      gradleValid: gradle.gradleValid,
+      gradleFilesChecked: gradle.filesChecked,
+      gradleSuggestedFixes: gradle.suggestedFixes
     }
   } catch (e: unknown) {
     return { success: false, issues: ['Internal error: ' + (e instanceof Error ? e.message : String(e))] }

package/src/utils/android/utils.ts

@@ -4,6 +4,7 @@ import path from 'path'
 import { detectJavaHome } from '../java.js'
 import { execCmd } from '../exec.js'
 import { spawnSync } from 'child_process'
+import { checkGradle } from '../../system/gradle.js'
 
 function findInPath(cmd: string): string | null {
   try {
@@ -73,6 +74,14 @@ export async function prepareGradle(projectPath: string): Promise<{ execCmd: str
   }
 
   const detectedJavaHome = await detectJavaHome().catch(() => undefined)
+  // Check for problematic org.gradle.java.home entries (env or properties) and avoid passing invalid values to Gradle
+  let gradleCheck
+  try {
+    gradleCheck = await checkGradle()
+  } catch {
+    gradleCheck = { gradleJavaHome: undefined, gradleValid: false, filesChecked: [], issues: [] }
+  }
+
   const env = Object.assign({}, process.env)
 
   // Ensure child processes can find Android platform-tools (adb, etc.) by
@@ -86,6 +95,7 @@ export async function prepareGradle(projectPath: string): Promise<{ execCmd: str
   } catch (e: unknown) { console.debug(`[prepareGradle] error resolving adbPath: ${String(e)}`) }
 
   const pathParts: string[] = []
+  // Prefer a detected (validated) Java home from the system/IDE
   if (detectedJavaHome) {
     if (env.JAVA_HOME !== detectedJavaHome) {
       env.JAVA_HOME = detectedJavaHome
@@ -95,6 +105,20 @@ export async function prepareGradle(projectPath: string): Promise<{ execCmd: str
     gradleArgs.push(`-Dorg.gradle.java.home=${detectedJavaHome}`)
     gradleArgs.push('--no-daemon')
     env.GRADLE_JAVA_HOME = detectedJavaHome
+  } else if (gradleCheck && gradleCheck.gradleJavaHome) {
+    // There's an org.gradle.java.home configured somewhere (env or gradle.properties)
+    if (gradleCheck.gradleValid) {
+      const p = gradleCheck.gradleJavaHome as string
+      const javaBin = path.join(p, 'bin')
+      if (!env.PATH || !env.PATH.includes(javaBin)) pathParts.push(javaBin)
+      gradleArgs.push(`-Dorg.gradle.java.home=${p}`)
+      gradleArgs.push('--no-daemon')
+      env.GRADLE_JAVA_HOME = p
+    } else {
+      // Invalid gradle java home detected: avoid passing it to Gradle and remove from spawn env
+      console.debug(`[prepareGradle] Invalid org.gradle.java.home detected (${gradleCheck.gradleJavaHome}); removing from spawn env to avoid Gradle error.`)
+      try { delete env.GRADLE_JAVA_HOME } catch { }
+    }
   }
 
   if (platformToolsDir) {
@@ -126,9 +150,11 @@ export async function prepareGradle(projectPath: string): Promise<{ execCmd: str
   const spawnOpts: any = { cwd: projectPath, env }
   if (useWrapper) {
     try { await fsPromises.chmod(gradlewPath, 0o755) } catch (e: unknown) { console.debug('[prepareGradle] chmod failed for gradlew:', String(e)) }
+    // Execute the wrapper directly without a shell to avoid shell tokenization of args (spaces in paths)
     spawnOpts.shell = false
   } else {
-    spawnOpts.shell = true
+    // Prefer executing gradle directly without invoking a shell to preserve argument boundaries
+    spawnOpts.shell = false
   }
 
   return { execCmd, gradleArgs, spawnOpts }

package/test/observe/unit/observe_until_edge_cases.test.ts

@@ -0,0 +1,41 @@
+import { ToolsInteract } from '../../../../src/interact/index.js'
+import * as Observe from '../../../../src/observe/index.js'
+
+async function run() {
+  console.log('Unit: observe_until edge cases')
+
+  const origFind = (ToolsInteract as any).findElementHandler
+  const origFp = (Observe as any).ToolsObserve.getScreenFingerprintHandler
+
+  try {
+    // 1) Immediate absence should pass for match='absent'
+    (ToolsInteract as any).findElementHandler = async () => ({ found: false })
+    const r1 = await (ToolsInteract as any).observeUntilHandler({ type: 'ui', query: 'Nothing', timeoutMs: 2000, pollIntervalMs: 100, stability_ms: 200, match: 'absent', platform: 'android' })
+    console.log('Immediate absent test:', r1 && (r1 as any).success ? 'PASS' : 'FAIL', JSON.stringify({ poll_count: (r1 as any).poll_count, duration_ms: (r1 as any).duration_ms, stable_duration_ms: (r1 as any).stable_duration_ms, matchSource: (r1 as any).matchSource }, null, 2))
+
+    // 2) Boundary stability: condition becomes true and stays exactly long enough
+    // Use pollInterval 100ms and stability 300ms -> need ~3 consecutive trues
+    let seq2 = [false, true, true, true]
+    (ToolsInteract as any).findElementHandler = async () => ({ found: seq2.shift() ?? true })
+    const r2 = await (ToolsInteract as any).observeUntilHandler({ type: 'ui', query: 'Boundary', timeoutMs: 2000, pollIntervalMs: 100, stability_ms: 300, match: 'present', platform: 'android' })
+    console.log('Boundary stability test:', r2 && (r2 as any).success ? 'PASS' : 'FAIL', JSON.stringify({ poll_count: (r2 as any).poll_count, duration_ms: (r2 as any).duration_ms, stable_duration_ms: (r2 as any).stable_duration_ms, matchSource: (r2 as any).matchSource }, null, 2))
+
+    // 3) Long flicker that never stabilizes should timeout/fail
+    // Sequence toggles true/false repeatedly
+    let seq3 = [false, true, false, true, false, true, false]
+    (ToolsInteract as any).findElementHandler = async () => ({ found: seq3.shift() ?? false })
+    const r3 = await (ToolsInteract as any).observeUntilHandler({ type: 'ui', query: 'Flicker', timeoutMs: 1200, pollIntervalMs: 150, stability_ms: 400, match: 'present', platform: 'android' })
+    console.log('Long flicker timeout test:', !(r3 && (r3 as any).success) ? 'PASS' : 'FAIL', JSON.stringify({ poll_count: (r3 as any).poll_count, duration_ms: (r3 as any).duration_ms, stable_duration_ms: (r3 as any).stable_duration_ms, matchSource: (r3 as any).matchSource }, null, 2))
+
+    // 4) Very short stability requirement should pass quickly
+    (ToolsInteract as any).findElementHandler = async () => ({ found: true })
+    const r4 = await (ToolsInteract as any).observeUntilHandler({ type: 'ui', query: 'ShortStable', timeoutMs: 2000, pollIntervalMs: 200, stability_ms: 50, match: 'present', platform: 'android' })
+    console.log('Short stability test:', r4 && (r4 as any).success ? 'PASS' : 'FAIL', JSON.stringify({ poll_count: (r4 as any).poll_count, duration_ms: (r4 as any).duration_ms, stable_duration_ms: (r4 as any).stable_duration_ms, matchSource: (r4 as any).matchSource }, null, 2))
+
+  } finally {
+    (ToolsInteract as any).findElementHandler = origFind
+    (Observe as any).ToolsObserve.getScreenFingerprintHandler = origFp
+  }
+}
+
+run().catch(e=>{ console.error(e); process.exit(1) })

package/test/observe/unit/observe_until_stability.test.ts

@@ -0,0 +1,30 @@
+import { ToolsInteract } from '../../../../src/interact/index.js'
+import * as Observe from '../../../../src/observe/index.js'
+
+async function run() {
+  console.log('Unit: observe_until stability behavior')
+
+  const origFind = (ToolsInteract as any).findElementHandler
+  const origFp = (Observe as any).ToolsObserve.getScreenFingerprintHandler
+
+  try {
+    // Simulate UI flicker: present, absent, present, then stable
+    const seq = [false, true, false, true, true, true]
+    (ToolsInteract as any).findElementHandler = async () => ({ found: seq.shift() ?? true })
+
+    const res = await (ToolsInteract as any).observeUntilHandler({ type: 'ui', query: 'X', timeoutMs: 5000, pollIntervalMs: 100, stability_ms: 500, platform: 'android' })
+    const ok = res && (res as any).success
+    console.log('Flicker stability test:', ok ? 'PASS' : 'FAIL', JSON.stringify((res as any).telemetry || {}, null, 2))
+
+    // Simulate immediate stable presence
+    (ToolsInteract as any).findElementHandler = async () => ({ found: true })
+    const res2 = await (ToolsInteract as any).observeUntilHandler({ type: 'ui', query: 'Y', timeoutMs: 2000, pollIntervalMs: 100, stability_ms: 300, platform: 'android' })
+    console.log('Immediate stable test:', res2 && (res2 as any).success ? 'PASS' : 'FAIL', JSON.stringify((res2 as any).telemetry || {}, null, 2))
+
+  } finally {
+    (ToolsInteract as any).findElementHandler = origFind
+    (Observe as any).ToolsObserve.getScreenFingerprintHandler = origFp
+  }
+}
+
+run().catch(e=>{ console.error(e); process.exit(1) })

package/test/interact/device/observe_until_device.ts

@@ -1,24 +0,0 @@
-(async function main(){
-  try{
-    const inter = await import('../../src/interact/index.ts')
-    const manage = await import('../../src/manage/index.ts')
-    const ToolsInteract = (inter as any).ToolsInteract
-    const ToolsManage = (manage as any).ToolsManage
-
-    const ANDROID_ID = process.env.ANDROID_DEVICE || 'emulator-5554'
-    const IOS_UDID = process.env.IOS_DEVICE || '2EFFD8FD-5D09-47CC-95F8-28BBE30AF7ED'
-    console.log('Device test starting. Android:', ANDROID_ID, 'iOS:', IOS_UDID)
-
-    // Start modul8 on both platforms if present
-    try { await ToolsManage.startAppHandler({ platform: 'android', appId: 'com.ideamechanics.modul8', deviceId: ANDROID_ID }); console.log('Started android app (if installed)') } catch(e){ console.error('Android start skipped:', e.message || e) }
-    try { await ToolsManage.startAppHandler({ platform: 'ios', appId: 'com.ideamechanics.modul8.Modul8', deviceId: IOS_UDID }); console.log('Started ios app (if installed)') } catch(e){ console.error('iOS start skipped:', e.message || e) }
-
-    // Observe UI for Generate Session on both devices (will timeout if not present)
-    const aRes = await ToolsInteract.observeUntilHandler({ type: 'ui', query: 'Generate Session', timeoutMs: 20000, pollIntervalMs: 500, platform: 'android', deviceId: ANDROID_ID })
-    console.log('Android observe result:', JSON.stringify(aRes, null, 2))
-
-    const iRes = await ToolsInteract.observeUntilHandler({ type: 'ui', query: 'Generate Session', timeoutMs: 20000, pollIntervalMs: 500, platform: 'ios', deviceId: IOS_UDID })
-    console.log('iOS observe result:', JSON.stringify(iRes, null, 2))
-
-  } catch (e) { console.error('ERR', e); process.exit(1) }
-})()