@validate.qa/runner 1.0.70 → 1.0.72

package/dist/cli.js

@@ -735,6 +735,7 @@ var require_mobile_source_parser = __commonJS({
     exports2.computeScreenHash = computeScreenHash;
     exports2.buildLocatorBundle = buildLocatorBundle;
     exports2.preferredLocator = preferredLocator;
+    exports2.identityMatchInfo = identityMatchInfo;
     exports2.parseMobileSource = parseMobileSource2;
     exports2.resolveLocatorAgainstScreenDetailed = resolveLocatorAgainstScreenDetailed;
     exports2.resolveLocatorAgainstScreen = resolveLocatorAgainstScreen;
@@ -1349,16 +1350,34 @@ var require_mobile_source_parser = __commonJS({
         bundle.contentDesc = el.accessibilityId;
       return bundle;
     }
-    function preferredLocator(el) {
-      const durableText = el.text && !isEditableElement(el) && !isStateValueElement(el) ? el.text : void 0;
+    function identityFieldValue(el, field) {
+      if (field === "text") {
+        return el.text && !isEditableElement(el) && !isStateValueElement(el) ? el.text : void 0;
+      }
+      return el[field];
+    }
+    function choosePreferredIdentityField(el) {
       const candidates = [
-        { value: el.accessibilityId, unique: el.identityUnique?.accessibilityId },
-        { value: el.resourceId, unique: el.identityUnique?.resourceId },
-        { value: durableText, unique: el.identityUnique?.text }
+        { field: "accessibilityId", value: identityFieldValue(el, "accessibilityId"), unique: el.identityUnique?.accessibilityId },
+        { field: "resourceId", value: identityFieldValue(el, "resourceId"), unique: el.identityUnique?.resourceId },
+        { field: "text", value: identityFieldValue(el, "text"), unique: el.identityUnique?.text }
       ];
       const uniqueFirst = candidates.find((c) => c.value && c.unique !== false);
-      const chosen = (uniqueFirst ?? candidates.find((c) => c.value))?.value;
-      return chosen ?? el.xpath;
+      const chosen = uniqueFirst ?? candidates.find((c) => c.value);
+      return chosen?.value ? { field: chosen.field, value: chosen.value } : void 0;
+    }
+    function preferredLocator(el) {
+      return choosePreferredIdentityField(el)?.value ?? el.xpath;
+    }
+    function identityMatchInfo(el, elements) {
+      const chosen = choosePreferredIdentityField(el);
+      if (!chosen)
+        return void 0;
+      if (el.identityUnique?.[chosen.field] !== false)
+        return void 0;
+      const sameValue = elements.filter((candidate) => identityFieldValue(candidate, chosen.field) === chosen.value);
+      const matchIndex = sameValue.indexOf(el);
+      return matchIndex >= 0 && sameValue.length > 1 ? { matchIndex, expectedMatchCount: sameValue.length } : void 0;
     }
     function buildScreenSignal(elements, root, platform3) {
       const signal = {
@@ -2112,6 +2131,9 @@ function readMobileMetadata(value) {
     return { screenName: "UnknownScreen" };
   }
   const locatorBundle = isPlainObject(value.locatorBundle) && typeof value.locatorBundle.xpath === "string" && typeof value.locatorBundle.className === "string" ? value.locatorBundle : void 0;
+  const rawMatchIndex = value.matchIndex;
+  const rawExpectedMatchCount = value.expectedMatchCount;
+  const hasValidMatchPair = typeof rawMatchIndex === "number" && Number.isInteger(rawMatchIndex) && rawMatchIndex >= 0 && typeof rawExpectedMatchCount === "number" && Number.isInteger(rawExpectedMatchCount) && rawExpectedMatchCount > rawMatchIndex;
   return {
     screenName: typeof value.screenName === "string" && value.screenName.trim() ? value.screenName.trim() : "UnknownScreen",
     targetLabel: typeof value.targetLabel === "string" && value.targetLabel.trim() ? value.targetLabel.trim() : void 0,
@@ -2126,7 +2148,9 @@ function readMobileMetadata(value) {
     distance: typeof value.distance === "number" && Number.isFinite(value.distance) ? value.distance : void 0,
     appContext: value.appContext === "WEBVIEW" ? "WEBVIEW" : value.appContext === "NATIVE" ? "NATIVE" : void 0,
     webCss: typeof value.webCss === "string" && value.webCss.trim() ? value.webCss.trim() : void 0,
-    webviewContext: typeof value.webviewContext === "string" && /^WEBVIEW/i.test(value.webviewContext.trim()) ? value.webviewContext.trim() : void 0
+    webviewContext: typeof value.webviewContext === "string" && /^WEBVIEW/i.test(value.webviewContext.trim()) ? value.webviewContext.trim() : void 0,
+    matchIndex: hasValidMatchPair ? rawMatchIndex : void 0,
+    expectedMatchCount: hasValidMatchPair ? rawExpectedMatchCount : void 0
   };
 }
 function nonEmpty(value) {
@@ -2135,6 +2159,9 @@ function nonEmpty(value) {
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : void 0;
 }
+function matchInstanceFields(metadata) {
+  return metadata.matchIndex !== void 0 && metadata.expectedMatchCount !== void 0 ? { matchIndex: metadata.matchIndex, expectedMatchCount: metadata.expectedMatchCount } : {};
+}
 function buildStepTarget(metadata, selector) {
   const locatorBundle = metadata.locatorBundle;
   const trimmedSelector = nonEmpty(selector);
@@ -2145,7 +2172,8 @@ function buildStepTarget(metadata, selector) {
     return {
       primary: trimmedSelector,
       fallbacks: [],
-      screenName: metadata.screenName
+      screenName: metadata.screenName,
+      ...matchInstanceFields(metadata)
     };
   }
   const webCss = nonEmpty(metadata.webCss) ?? (trimmedSelector?.startsWith("css=") ? trimmedSelector.slice(4) : void 0) ?? (nonEmpty(locatorBundle.xpath)?.startsWith("css=") ? locatorBundle.xpath.slice(4) : void 0);
@@ -2168,8 +2196,9 @@ function buildStepTarget(metadata, selector) {
     primary,
     fallbacks,
     screenName: metadata.screenName,
-    locatorBundle
+    locatorBundle,
     // Include the locatorBundle for better selector generation later
+    ...matchInstanceFields(metadata)
   };
 }
 function labelForAction(action, metadata) {
@@ -2616,6 +2645,165 @@ function buildAppiumCode(testName, target, steps) {
     `main().catch((err) => { console.error(err); process.exitCode = 1; });`
   ].join("\n");
 }
+function webviewStepLogicalId(step) {
+  if (step.metadata?.appContext !== "WEBVIEW")
+    return null;
+  const webCss = typeof step.metadata?.webCss === "string" && step.metadata.webCss.length > 0 ? step.metadata.webCss : step.target?.primary?.startsWith("css=") ? step.target.primary.slice(4) : "";
+  const match = String(webCss ?? "").match(/^#([A-Za-z][\w-]*)$/);
+  return match ? match[1].toLowerCase() : null;
+}
+function nativeStepResourceId(step) {
+  const target = step.target;
+  if (!target)
+    return null;
+  const xpaths = [target.locatorBundle?.xpath, ...target.fallbacks ?? []].filter((value) => typeof value === "string" && value.length > 0);
+  for (const xpath of xpaths) {
+    const match = xpath.match(/@resource-id=['"]([^'"]+)['"]/);
+    if (match)
+      return match[1].split("/").pop().toLowerCase();
+  }
+  const resourceId = nonEmpty(target.locatorBundle?.resourceId);
+  if (resourceId)
+    return resourceId.split("/").pop().toLowerCase();
+  const primary = (target.primary ?? "").trim();
+  if (/^[A-Za-z][\w-]*$/.test(primary) && !primary.startsWith("css="))
+    return primary.toLowerCase();
+  return null;
+}
+function renumberMobileSteps(steps) {
+  steps.forEach((step, index) => {
+    step.order = index;
+  });
+}
+function dropHybridNativeMirrorStepsInPlace(steps) {
+  const webviewKeys = /* @__PURE__ */ new Set();
+  for (const step of steps) {
+    const id = webviewStepLogicalId(step);
+    if (id)
+      webviewKeys.add(`${step.target?.screenName ?? ""}::${id}`);
+  }
+  if (webviewKeys.size === 0)
+    return 0;
+  const kept = steps.filter((step) => {
+    if (step.metadata?.appContext === "WEBVIEW")
+      return true;
+    if (step.action !== "tap" && step.action !== "type")
+      return true;
+    const id = nativeStepResourceId(step);
+    if (id === null)
+      return true;
+    return !webviewKeys.has(`${step.target?.screenName ?? ""}::${id}`);
+  });
+  const removed = steps.length - kept.length;
+  if (removed > 0) {
+    steps.splice(0, steps.length, ...kept);
+    renumberMobileSteps(steps);
+  }
+  return removed;
+}
+function strictOnMobileWanderFlag(value) {
+  const v = (value || "").trim().toLowerCase();
+  return v === "true" || v === "1";
+}
+function isMobileWanderSimplifyEnabled() {
+  const value = (process.env.VALIDATEQA_MOBILE_WANDER_SIMPLIFY || "").trim().toLowerCase();
+  return value === "on" || value === "true" || value === "1";
+}
+function mobileWanderTraceEnabled() {
+  return strictOnMobileWanderFlag(process.env.VALIDATEQA_MOBILE_WANDER_TRACE);
+}
+function isMobileWanderCommitTapText(text) {
+  const isChooser = /\b(continue\s+with|sign\s+in\s+with|log\s+in\s+with|use\s+(?:email|phone)|choose|pick|select)\b/i.test(text);
+  if (isChooser)
+    return false;
+  return /\b(sign\s*in|log\s*in|login|submit|save|continue|create|send|confirm|done|next|apply|checkout|pay|finish|update|register|sign\s*up)\b/i.test(text);
+}
+function isMobileWanderCommitStep(step) {
+  if (step.action === "type" && typeof step.value === "string" && /\n$/.test(step.value))
+    return true;
+  if (step.action === "tap") {
+    const text = [step.description, step.target?.primary].filter((v) => typeof v === "string" && v.length > 0).join(" ");
+    return isMobileWanderCommitTapText(text);
+  }
+  return false;
+}
+function isMobileWanderStateToggleTap(step) {
+  return step.action === "tap" && isStateValueMobileClassName(step.target?.locatorBundle?.className);
+}
+function simplifyMobileWanderingInPlace(steps, trace) {
+  let removed = 0;
+  const afterAdjacentDupes = [];
+  for (const step of steps) {
+    const previous = afterAdjacentDupes[afterAdjacentDupes.length - 1];
+    const primary = step.target?.primary;
+    const isAdjacentDuplicateTap = previous !== void 0 && step.action === "tap" && previous.action === "tap" && !!primary && primary === previous.target?.primary && step.target?.screenName === previous.target?.screenName && step.value === previous.value && !isMobileWanderStateToggleTap(step) && !isMobileWanderStateToggleTap(previous);
+    if (isAdjacentDuplicateTap) {
+      removed += 1;
+      trace?.(`dropped adjacent duplicate tap "${primary}" (exact repeat, nothing between)`);
+      afterAdjacentDupes[afterAdjacentDupes.length - 1] = step;
+      continue;
+    }
+    afterAdjacentDupes.push(step);
+  }
+  const lastTypeIndexByPrimary = /* @__PURE__ */ new Map();
+  const refocusTapIndexesByPrimary = /* @__PURE__ */ new Map();
+  const toDrop = /* @__PURE__ */ new Set();
+  afterAdjacentDupes.forEach((step, index) => {
+    if (step.action === "assertVisible" || step.action === "assertText" || step.action === "waitForElement") {
+      lastTypeIndexByPrimary.clear();
+      refocusTapIndexesByPrimary.clear();
+      return;
+    }
+    if (step.action === "clear") {
+      const primary2 = step.target?.primary;
+      if (primary2) {
+        lastTypeIndexByPrimary.delete(primary2);
+        refocusTapIndexesByPrimary.delete(primary2);
+      }
+      return;
+    }
+    if (isMobileWanderCommitStep(step)) {
+      lastTypeIndexByPrimary.clear();
+      refocusTapIndexesByPrimary.clear();
+      return;
+    }
+    if (step.action === "tap") {
+      const primary2 = step.target?.primary;
+      if (primary2) {
+        const list = refocusTapIndexesByPrimary.get(primary2) ?? [];
+        list.push(index);
+        refocusTapIndexesByPrimary.set(primary2, list);
+      }
+      return;
+    }
+    if (step.action !== "type")
+      return;
+    const primary = step.target?.primary;
+    if (!primary)
+      return;
+    const priorIndex = lastTypeIndexByPrimary.get(primary);
+    if (priorIndex !== void 0) {
+      toDrop.add(priorIndex);
+      removed += 1;
+      trace?.(`dropped superseded type into "${primary}" (a later type into the same field wins)`);
+      for (const tapIndex of refocusTapIndexesByPrimary.get(primary) ?? []) {
+        if (tapIndex > priorIndex && tapIndex < index && !toDrop.has(tapIndex)) {
+          toDrop.add(tapIndex);
+          removed += 1;
+          trace?.(`dropped redundant re-focus tap on "${primary}" (it only re-focused a field whose write was superseded)`);
+        }
+      }
+    }
+    lastTypeIndexByPrimary.set(primary, index);
+    refocusTapIndexesByPrimary.set(primary, []);
+  });
+  if (removed === 0)
+    return 0;
+  const kept = afterAdjacentDupes.filter((_, index) => !toDrop.has(index));
+  steps.splice(0, steps.length, ...kept);
+  renumberMobileSteps(steps);
+  return removed;
+}
 function generateMobileTestFromSession(input) {
   if (input.medium !== "IOS_NATIVE" && input.medium !== "ANDROID_NATIVE") {
     throw new Error(`Mobile test generation requires IOS_NATIVE or ANDROID_NATIVE medium (received ${input.medium})`);
@@ -2659,12 +2847,20 @@ function generateMobileTestFromSession(input) {
   if (steps.length === 0) {
     throw new Error("No mobile actions were recorded for this session");
   }
+  dropHybridNativeMirrorStepsInPlace(steps);
+  const wanderTraceMessages = [];
+  const wanderTraceSink = (message) => {
+    wanderTraceMessages.push(message);
+  };
+  if (isMobileWanderSimplifyEnabled()) {
+    simplifyMobileWanderingInPlace(steps, mobileWanderTraceEnabled() ? wanderTraceSink : void 0);
+  }
   const interactionSteps = steps.filter((step) => step.action !== "launchApp");
   const runnableInteractions = interactionSteps.filter(isRunnableStep);
   if (interactionSteps.length === 0 || runnableInteractions.length === 0) {
     throw new Error("Generated mobile test has no runnable steps \u2014 re-record the flow so each interaction targets an on-screen element.");
   }
-  const warnings = [];
+  const warnings = wanderTraceMessages.map((message) => `[wander] ${message}`);
   const unrunnable = interactionSteps.length - runnableInteractions.length;
   if (unrunnable > 0) {
     warnings.push(`${unrunnable} recorded step(s) could not be turned into a runnable action (missing a replayable identity locator or coordinate) and were kept best-effort.`);
@@ -6221,6 +6417,7 @@ __export(dist_exports, {
   isEnvironmentalError: () => isEnvironmentalError,
   isIdentityMobileXpath: () => isIdentityMobileXpath,
   isMobilePlatform: () => isMobilePlatform,
+  isMobileWanderSimplifyEnabled: () => isMobileWanderSimplifyEnabled,
   isPricingPlan: () => isPricingPlan,
   isRunnableStep: () => isRunnableStep,
   isSafeDeepLink: () => isSafeDeepLink,
@@ -6242,6 +6439,7 @@ __export(dist_exports, {
   mobileCredentialPlaceholder: () => mobileCredentialPlaceholder,
   mobileLocatorBundleHasIdentity: () => mobileLocatorBundleHasIdentity,
   mobilePlatformFromMedium: () => mobilePlatformFromMedium,
+  mobileWanderTraceEnabled: () => mobileWanderTraceEnabled,
   normalizeControlName: () => normalizeControlName,
   normalizeTtsVoiceId: () => normalizeTtsVoiceId,
   otherMobilePlatform: () => otherMobilePlatform,
@@ -6270,6 +6468,7 @@ __export(dist_exports, {
   scrubUrlPropertyBag: () => scrubUrlPropertyBag,
   selectorCandidatesForStep: () => selectorCandidatesForStep,
   selectorForValue: () => selectorForValue,
+  simplifyMobileWanderingInPlace: () => simplifyMobileWanderingInPlace,
   stepAppliesToPlatform: () => stepAppliesToPlatform,
   stepIsDivergentForPlatform: () => stepIsDivergentForPlatform,
   stepsMissingPlatformLocators: () => stepsMissingPlatformLocators,
@@ -10556,7 +10755,7 @@ var require_sonic_boom = __commonJS({
       if (!(this instanceof SonicBoom)) {
         return new SonicBoom(opts);
       }
-      let { fd, dest, minLength, maxLength, maxWrite, periodicFlush, sync, append = true, mkdir: mkdir2, retryEAGAIN, fsync, contentMode, mode } = opts || {};
+      let { fd, dest, minLength, maxLength, maxWrite, periodicFlush, sync, append = true, mkdir: mkdir3, retryEAGAIN, fsync, contentMode, mode } = opts || {};
       fd = fd || dest;
       this._len = 0;
       this.fd = -1;
@@ -10581,7 +10780,7 @@ var require_sonic_boom = __commonJS({
       this.append = append || false;
       this.mode = mode;
       this.retryEAGAIN = retryEAGAIN || (() => true);
-      this.mkdir = mkdir2 || false;
+      this.mkdir = mkdir3 || false;
       let fsWriteSync;
       let fsWrite;
       if (contentMode === kContentModeBuffer) {
@@ -11292,8 +11491,8 @@ var require_thread_stream = __commonJS({
     "use strict";
     var { version } = require_package();
     var { EventEmitter: EventEmitter2 } = require("events");
-    var { Worker } = require("worker_threads");
-    var { join: join7 } = require("path");
+    var { Worker: Worker2 } = require("worker_threads");
+    var { join: join8 } = require("path");
     var { pathToFileURL } = require("url");
     var { wait } = require_wait();
     var {
@@ -11344,8 +11543,8 @@ var require_thread_stream = __commonJS({
     function createWorker(stream, opts) {
       const { filename, workerData } = opts;
       const bundlerOverrides = "__bundlerPathsOverrides" in globalThis ? globalThis.__bundlerPathsOverrides : {};
-      const toExecute = bundlerOverrides["thread-stream-worker"] || join7(__dirname, "lib", "worker.js");
-      const worker = new Worker(toExecute, {
+      const toExecute = bundlerOverrides["thread-stream-worker"] || join8(__dirname, "lib", "worker.js");
+      const worker = new Worker2(toExecute, {
         ...opts.workerOpts,
         name: opts.workerOpts?.name || "thread-stream",
         trackUnmanagedFds: false,
@@ -11812,7 +12011,7 @@ var require_transport = __commonJS({
     var { createRequire } = require("module");
     var { existsSync: existsSync3 } = require("fs");
     var getCallers = require_caller();
-    var { join: join7, isAbsolute, sep } = require("path");
+    var { join: join8, isAbsolute: isAbsolute2, sep } = require("path");
     var { fileURLToPath } = require("url");
     var sleep = require_atomic_sleep();
     var onExit = require_on_exit_leak_free();
@@ -11884,7 +12083,7 @@ var require_transport = __commonJS({
           return false;
         }
       }
-      return isAbsolute(path) && !existsSync3(path);
+      return isAbsolute2(path) && !existsSync3(path);
     }
     function stripQuotes(value) {
       const first = value[0];
@@ -11965,7 +12164,7 @@ var require_transport = __commonJS({
         throw new Error("only one of target or targets can be specified");
       }
       if (targets) {
-        target = bundlerOverrides["pino-worker"] || join7(__dirname, "worker.js");
+        target = bundlerOverrides["pino-worker"] || join8(__dirname, "worker.js");
         options.targets = targets.filter((dest) => dest.target).map((dest) => {
           return {
             ...dest,
@@ -11983,7 +12182,7 @@ var require_transport = __commonJS({
           });
         });
       } else if (pipeline) {
-        target = bundlerOverrides["pino-worker"] || join7(__dirname, "worker.js");
+        target = bundlerOverrides["pino-worker"] || join8(__dirname, "worker.js");
         options.pipelines = [pipeline.map((dest) => {
           return {
             ...dest,
@@ -12002,11 +12201,11 @@ var require_transport = __commonJS({
       return buildStream(fixTarget(target), options, worker, sync, name);
       function fixTarget(origin) {
         origin = bundlerOverrides[origin] || origin;
-        if (isAbsolute(origin) || origin.indexOf("file://") === 0) {
+        if (isAbsolute2(origin) || origin.indexOf("file://") === 0) {
           return origin;
         }
         if (origin === "pino/file") {
-          return join7(__dirname, "..", "file.js");
+          return join8(__dirname, "..", "file.js");
         }
         let fixTarget2;
         for (const filePath of callers) {
@@ -12987,7 +13186,7 @@ var require_safe_stable_stringify = __commonJS({
               return circularValue;
             }
             let res = "";
-            let join7 = ",";
+            let join8 = ",";
             const originalIndentation = indentation;
             if (Array.isArray(value)) {
               if (value.length === 0) {
@@ -13001,7 +13200,7 @@ var require_safe_stable_stringify = __commonJS({
                 indentation += spacer;
                 res += `
 ${indentation}`;
-                join7 = `,
+                join8 = `,
 ${indentation}`;
               }
               const maximumValuesToStringify = Math.min(value.length, maximumBreadth);
@@ -13009,13 +13208,13 @@ ${indentation}`;
               for (; i < maximumValuesToStringify - 1; i++) {
                 const tmp2 = stringifyFnReplacer(String(i), value, stack, replacer, spacer, indentation);
                 res += tmp2 !== void 0 ? tmp2 : "null";
-                res += join7;
+                res += join8;
               }
               const tmp = stringifyFnReplacer(String(i), value, stack, replacer, spacer, indentation);
               res += tmp !== void 0 ? tmp : "null";
               if (value.length - 1 > maximumBreadth) {
                 const removedKeys = value.length - maximumBreadth - 1;
-                res += `${join7}"... ${getItemCount(removedKeys)} not stringified"`;
+                res += `${join8}"... ${getItemCount(removedKeys)} not stringified"`;
               }
               if (spacer !== "") {
                 res += `
@@ -13036,7 +13235,7 @@ ${originalIndentation}`;
             let separator = "";
             if (spacer !== "") {
               indentation += spacer;
-              join7 = `,
+              join8 = `,
 ${indentation}`;
               whitespace = " ";
             }
@@ -13050,13 +13249,13 @@ ${indentation}`;
               const tmp = stringifyFnReplacer(key2, value, stack, replacer, spacer, indentation);
               if (tmp !== void 0) {
                 res += `${separator}${strEscape(key2)}:${whitespace}${tmp}`;
-                separator = join7;
+                separator = join8;
               }
             }
             if (keyLength > maximumBreadth) {
               const removedKeys = keyLength - maximumBreadth;
               res += `${separator}"...":${whitespace}"${getItemCount(removedKeys)} not stringified"`;
-              separator = join7;
+              separator = join8;
             }
             if (spacer !== "" && separator.length > 1) {
               res = `
@@ -13097,7 +13296,7 @@ ${originalIndentation}`;
             }
             const originalIndentation = indentation;
             let res = "";
-            let join7 = ",";
+            let join8 = ",";
             if (Array.isArray(value)) {
               if (value.length === 0) {
                 return "[]";
@@ -13110,7 +13309,7 @@ ${originalIndentation}`;
                 indentation += spacer;
                 res += `
 ${indentation}`;
-                join7 = `,
+                join8 = `,
 ${indentation}`;
               }
               const maximumValuesToStringify = Math.min(value.length, maximumBreadth);
@@ -13118,13 +13317,13 @@ ${indentation}`;
               for (; i < maximumValuesToStringify - 1; i++) {
                 const tmp2 = stringifyArrayReplacer(String(i), value[i], stack, replacer, spacer, indentation);
                 res += tmp2 !== void 0 ? tmp2 : "null";
-                res += join7;
+                res += join8;
               }
               const tmp = stringifyArrayReplacer(String(i), value[i], stack, replacer, spacer, indentation);
               res += tmp !== void 0 ? tmp : "null";
               if (value.length - 1 > maximumBreadth) {
                 const removedKeys = value.length - maximumBreadth - 1;
-                res += `${join7}"... ${getItemCount(removedKeys)} not stringified"`;
+                res += `${join8}"... ${getItemCount(removedKeys)} not stringified"`;
               }
               if (spacer !== "") {
                 res += `
@@ -13137,7 +13336,7 @@ ${originalIndentation}`;
             let whitespace = "";
             if (spacer !== "") {
               indentation += spacer;
-              join7 = `,
+              join8 = `,
 ${indentation}`;
               whitespace = " ";
             }
@@ -13146,7 +13345,7 @@ ${indentation}`;
               const tmp = stringifyArrayReplacer(key2, value[key2], stack, replacer, spacer, indentation);
               if (tmp !== void 0) {
                 res += `${separator}${strEscape(key2)}:${whitespace}${tmp}`;
-                separator = join7;
+                separator = join8;
               }
             }
             if (spacer !== "" && separator.length > 1) {
@@ -13204,20 +13403,20 @@ ${originalIndentation}`;
               indentation += spacer;
               let res2 = `
 ${indentation}`;
-              const join8 = `,
+              const join9 = `,
 ${indentation}`;
               const maximumValuesToStringify = Math.min(value.length, maximumBreadth);
               let i = 0;
               for (; i < maximumValuesToStringify - 1; i++) {
                 const tmp2 = stringifyIndent(String(i), value[i], stack, spacer, indentation);
                 res2 += tmp2 !== void 0 ? tmp2 : "null";
-                res2 += join8;
+                res2 += join9;
               }
               const tmp = stringifyIndent(String(i), value[i], stack, spacer, indentation);
               res2 += tmp !== void 0 ? tmp : "null";
               if (value.length - 1 > maximumBreadth) {
                 const removedKeys = value.length - maximumBreadth - 1;
-                res2 += `${join8}"... ${getItemCount(removedKeys)} not stringified"`;
+                res2 += `${join9}"... ${getItemCount(removedKeys)} not stringified"`;
               }
               res2 += `
 ${originalIndentation}`;
@@ -13233,16 +13432,16 @@ ${originalIndentation}`;
               return '"[Object]"';
             }
             indentation += spacer;
-            const join7 = `,
+            const join8 = `,
 ${indentation}`;
             let res = "";
             let separator = "";
             let maximumPropertiesToStringify = Math.min(keyLength, maximumBreadth);
             if (isTypedArrayWithEntries(value)) {
-              res += stringifyTypedArray(value, join7, maximumBreadth);
+              res += stringifyTypedArray(value, join8, maximumBreadth);
               keys = keys.slice(value.length);
               maximumPropertiesToStringify -= value.length;
-              separator = join7;
+              separator = join8;
             }
             if (deterministic) {
               keys = sort(keys, comparator);
@@ -13253,13 +13452,13 @@ ${indentation}`;
               const tmp = stringifyIndent(key2, value[key2], stack, spacer, indentation);
               if (tmp !== void 0) {
                 res += `${separator}${strEscape(key2)}: ${tmp}`;
-                separator = join7;
+                separator = join8;
               }
             }
             if (keyLength > maximumBreadth) {
               const removedKeys = keyLength - maximumBreadth;
               res += `${separator}"...": "${getItemCount(removedKeys)} not stringified"`;
-              separator = join7;
+              separator = join8;
             }
             if (separator !== "") {
               res = `
@@ -61935,11 +62134,11 @@ var require_core = __commonJS({
     function mapOuter(r, f) {
       return r.matched ? f(r) : r;
     }
-    function ab(pa, pb, join7) {
-      return (data, i) => mapOuter(pa(data, i), (ma) => mapInner(pb(data, ma.position), (vb, j) => join7(ma.value, vb, data, i, j)));
+    function ab(pa, pb, join8) {
+      return (data, i) => mapOuter(pa(data, i), (ma) => mapInner(pb(data, ma.position), (vb, j) => join8(ma.value, vb, data, i, j)));
     }
-    function abc(pa, pb, pc, join7) {
-      return (data, i) => mapOuter(pa(data, i), (ma) => mapOuter(pb(data, ma.position), (mb) => mapInner(pc(data, mb.position), (vc, j) => join7(ma.value, mb.value, vc, data, i, j))));
+    function abc(pa, pb, pc, join8) {
+      return (data, i) => mapOuter(pa(data, i), (ma) => mapOuter(pb(data, ma.position), (mb) => mapInner(pc(data, mb.position), (vc, j) => join8(ma.value, mb.value, vc, data, i, j))));
     }
     function action(f) {
       return (data, i) => {
@@ -74445,6 +74644,7 @@ var require_mobile_explorer = __commonJS({
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.computeMobileSurveyBreadthContinuation = computeMobileSurveyBreadthContinuation;
     exports2.computeMobileBreadthFinishRedirectDecision = computeMobileBreadthFinishRedirectDecision;
+    exports2.hybridScreenFingerprint = hybridScreenFingerprint;
     exports2.runMobileExplorePhase = runMobileExplorePhase;
     var crypto_1 = require("crypto");
     var shared_1 = (init_dist(), __toCommonJS(dist_exports));
@@ -74898,11 +75098,12 @@ var require_mobile_explorer = __commonJS({
       const validSurfaceDigest = /^[0-9a-f]{16,64}$/.test(normalizedSurfaceDigest) ? normalizedSurfaceDigest : void 0;
       const legacyElementDigests = [...new Set(elements.map((element) => element.pageIdentityDigest?.trim().toLowerCase() ?? "").filter((digest) => /^[0-9a-f]{16,64}$/.test(digest)))];
       const pageIdentityDigest = validSurfaceDigest ?? (legacyElementDigests.length === 1 ? legacyElementDigests[0] : void 0);
+      const hasStableControlIdentity = elements.some((element) => Boolean(safeHybridIdentity(element.id, credentials) || safeHybridIdentity(element.name, credentials)));
       const descriptors = elements.map((element) => {
         const editable = element.editable === true || /^(?:input|textarea|select)$/i.test(element.tag) || /(?:textbox|searchbox|combobox)/i.test(element.role);
         const id = safeHybridIdentity(element.id, credentials)?.toLowerCase() ?? "";
         const name = safeHybridIdentity(element.name, credentials)?.toLowerCase() ?? "";
-        const semanticText = editable || id || name ? "" : stableHybridSemanticText(element.text, credentials);
+        const semanticText = editable || id || name || hasStableControlIdentity ? "" : stableHybridSemanticText(element.text, credentials);
         return [
           element.tag.trim().toLowerCase(),
           element.role.trim().toLowerCase(),
@@ -81167,10 +81368,14 @@ var require_mobile_generator = __commonJS({
   "../runner-core/dist/services/mobile/mobile-generator.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
+    exports2.structuralScreenKey = structuralScreenKey;
     exports2.collapseConsecutiveBacks = collapseConsecutiveBacks;
     exports2.scenarioIntentMismatchReason = scenarioIntentMismatchReason;
     exports2.dedupeConsecutiveIdenticalActions = dedupeConsecutiveIdenticalActions;
     exports2.collapseRetryCycles = collapseRetryCycles;
+    exports2.coalesceSameFieldTypes = coalesceSameFieldTypes;
+    exports2.coalesceRepeatedTaps = coalesceRepeatedTaps;
+    exports2.elideNoOpDetours = elideNoOpDetours;
     exports2.mobileActionsToPseudoPlaywright = mobileActionsToPseudoPlaywright;
     exports2.evaluateMobileAssertionStrength = evaluateMobileAssertionStrength;
     exports2.prepareMobileScenarioAppState = prepareMobileScenarioAppState;
@@ -81379,6 +81584,22 @@ var require_mobile_generator = __commonJS({
       MOBILE_ASSERT_TEXT_TOOL,
       FINISH_GENERATE_TOOL
     ];
+    var STRUCTURAL_KEY_MAX_ELEMENTS = 16;
+    function structuralScreenKey(resolved) {
+      if (!resolved)
+        return null;
+      const nativeElements = resolved.screen.elements;
+      const hybridElements = resolved.hybridWeb ? Array.from(resolved.hybridWeb.values()) : [];
+      if (nativeElements.length + hybridElements.length < 2)
+        return null;
+      const nativeSkeleton = [...nativeElements].sort((a, b) => a.role.localeCompare(b.role) || locatorLocalName(a.resourceId ?? "").localeCompare(locatorLocalName(b.resourceId ?? "")) || (a.accessibilityId ?? "").localeCompare(b.accessibilityId ?? "")).slice(0, STRUCTURAL_KEY_MAX_ELEMENTS).map((el) => `${el.role}|${locatorLocalName(el.resourceId ?? "")}|${el.accessibilityId ?? ""}`);
+      const hybridSkeleton = [...hybridElements].sort((a, b) => (a.id || a.role).localeCompare(b.id || b.role)).slice(0, STRUCTURAL_KEY_MAX_ELEMENTS).map((el) => `${el.role}|${el.id ?? ""}`);
+      const activityOrBundle = resolved.signal.activity ?? resolved.signal.bundleId ?? "";
+      const payload = `${activityOrBundle}
+${nativeSkeleton.join("\n")}
+${hybridSkeleton.join("\n")}`;
+      return (0, crypto_1.createHash)("sha1").update(payload).digest("hex");
+    }
     function platformForMedium(medium) {
       if (medium === "IOS_NATIVE")
         return "IOS";
@@ -81540,18 +81761,39 @@ var require_mobile_generator = __commonJS({
       }
       return `Typed value does not appear in the UI tree after typing into "${labelForElement(target)}". The field may not have been focused (common on WebView). Re-snapshot, tap the field, and type again.`;
     }
-    function metadataForElement(element, screenName, platform3) {
+    function alreadyFocusedWithEqualValue(element, value) {
+      return element.focused === true && typeof element.text === "string" && value.length > 0 && element.text === value;
+    }
+    function nativeElementsOf(resolved) {
+      return resolved?.screen.elements ?? [];
+    }
+    function hybridElementsOf(resolved) {
+      return resolved?.hybridWeb ? Array.from(resolved.hybridWeb.values()) : [];
+    }
+    function metadataForElement(element, screenName, platform3, elements = []) {
+      const match = (0, mobile_source_parser_js_2.identityMatchInfo)(element, elements);
       return {
         screenName,
         targetLabel: labelForElement(element),
         locatorBundle: (0, mobile_source_parser_js_2.buildLocatorBundle)(element, platform3),
-        bounds: element.bounds
+        bounds: element.bounds,
+        ...match ? { matchIndex: match.matchIndex, expectedMatchCount: match.expectedMatchCount } : {}
       };
     }
-    function metadataForHybridElement(element, screenName) {
+    function hybridIdentityMatchInfo(element, elements) {
+      const hybridIdentityValue = (candidate) => nonEmpty3(candidate.id) ?? (candidate.editable === true ? void 0 : nonEmpty3(candidate.text));
+      const chosenValue = hybridIdentityValue(element);
+      if (!chosenValue)
+        return void 0;
+      const sameValue = elements.filter((candidate) => hybridIdentityValue(candidate) === chosenValue);
+      const matchIndex = sameValue.indexOf(element);
+      return matchIndex >= 0 && sameValue.length > 1 ? { matchIndex, expectedMatchCount: sameValue.length } : void 0;
+    }
+    function metadataForHybridElement(element, screenName, elements = []) {
       const editable = isEditableHybridElement(element);
       const label = labelForHybridElement(element);
       const safeText = editable ? void 0 : nonEmpty3(element.text);
+      const match = hybridIdentityMatchInfo(element, elements);
       return {
         screenName,
         targetLabel: label,
@@ -81560,11 +81802,16 @@ var require_mobile_generator = __commonJS({
         webviewContext: element.webviewContext,
         bounds: element.bounds,
         locatorBundle: {
-          xpath: `css=${element.css}`,
+          // WebView controls resolve via `webCss` (above) in the WEBVIEW context, not
+          // by xpath. `LocatorBundle.xpath` is contractually an XPath, so never store a
+          // `css=` selector here — an empty xpath keeps the fallback chain honest and
+          // prevents the css selector being misread as an xpath at replay.
+          xpath: "",
           className: element.tag || "webview",
           ...element.id ? { accessibilityId: element.id } : {},
           ...safeText ? { text: safeText } : {}
-        }
+        },
+        ...match ? { matchIndex: match.matchIndex, expectedMatchCount: match.expectedMatchCount } : {}
       };
     }
     function isEditableHybridElement(element) {
@@ -82282,7 +82529,15 @@ ${statePacket}`, redactionCredentials) },
               screenName: () => lastScreenName || "UnknownScreen",
               recordAction: (action) => {
                 const screenHash = getLatest()?.signal.screenHash;
-                const stamped = screenHash && !action.metadata.screenHash ? { ...action, metadata: { ...action.metadata, screenHash } } : action;
+                const structuralKey = structuralScreenKey(getLatest());
+                const stamped = screenHash && !action.metadata.screenHash || structuralKey && !action.metadata.structuralKey ? {
+                  ...action,
+                  metadata: {
+                    ...action.metadata,
+                    ...screenHash && !action.metadata.screenHash ? { screenHash } : {},
+                    ...structuralKey && !action.metadata.structuralKey ? { structuralKey } : {}
+                  }
+                } : action;
                 actions.push((0, shared_1.placeholderizeRecordedMobileAction)(finalizeAction(stamped), credentials));
                 if (action.type === "ASSERT_VISIBLE" || action.type === "ASSERT_TEXT")
                   assertCount++;
@@ -82388,7 +82643,7 @@ ${statePacket}`, redactionCredentials) },
             const result2 = await driver.webTap(hybridTap.webviewContext, hybridTap.css);
             const absorbed2 = await absorbActionResult(result2, "mobile_tap(webview)", opensAuthenticationSurface(hybridTap));
             if (shouldRecordAction(result2, absorbed2)) {
-              const metadata = metadataForHybridElement(hybridTap, beforeScreenName2);
+              const metadata = metadataForHybridElement(hybridTap, beforeScreenName2, hybridElementsOf(before2));
               const label = metadata.targetLabel ?? hybridTap.css;
               const tapAction = {
                 type: "TAP",
@@ -82440,7 +82695,7 @@ ${statePacket}`, redactionCredentials) },
             const tapAction = {
               type: "TAP",
               selector: (0, mobile_source_parser_js_2.preferredLocator)(element),
-              metadata: metadataForElement(element, beforeScreenName, platform3),
+              metadata: metadataForElement(element, beforeScreenName, platform3, nativeElementsOf(before)),
               innerText: null,
               url: "",
               value: null
@@ -82480,10 +82735,11 @@ ${statePacket}`, redactionCredentials) },
               return { ok: false, error: "This driver does not support hybrid WEBVIEW typing." };
             }
             const beforeScreenName2 = screenName();
+            const before2 = latest();
             const result2 = await driver.webType(hybridType.webviewContext, hybridType.css, value);
             const absorbed2 = await absorbActionResult(result2, "mobile_type(webview)");
             if (shouldRecordAction(result2, absorbed2)) {
-              const metadata = metadataForHybridElement(hybridType, beforeScreenName2);
+              const metadata = metadataForHybridElement(hybridType, beforeScreenName2, hybridElementsOf(before2));
               const label = metadata.targetLabel ?? hybridType.css;
               recordAction({
                 type: "TYPE",
@@ -82498,7 +82754,14 @@ ${statePacket}`, redactionCredentials) },
           const element = resolveRef(toolArgs.ref);
           if (!element)
             return unknownRef(toolArgs.ref);
+          if (alreadyFocusedWithEqualValue(element, value)) {
+            return {
+              ok: false,
+              error: `"${labelForElement(element)}" is already focused and already contains exactly this value \u2014 typing it again is a no-op. Move on to the next step.`
+            };
+          }
           const beforeScreenName = screenName();
+          const before = latest();
           const result = await driver.type(value, element.bounds);
           const absorbed = await absorbActionResult(result, "mobile_type");
           if (shouldRecordAction(result, absorbed)) {
@@ -82506,7 +82769,7 @@ ${statePacket}`, redactionCredentials) },
               type: "TYPE",
               value,
               selector: (0, mobile_source_parser_js_2.preferredLocator)(element),
-              metadata: metadataForElement(element, beforeScreenName, platform3)
+              metadata: metadataForElement(element, beforeScreenName, platform3, nativeElementsOf(before))
             });
           }
           const payload = actionPayload(result, absorbed);
@@ -82524,6 +82787,7 @@ ${statePacket}`, redactionCredentials) },
               return { ok: false, error: "This driver does not support non-clearing WEBVIEW keyboard submit." };
             }
             const beforeScreenName2 = screenName();
+            const before2 = latest();
             const result2 = await driver.webSubmitKeyboard(hybridField.webviewContext, hybridField.css);
             const absorbed2 = await absorbActionResult(result2, "mobile_submit_keyboard(webview)");
             if (shouldRecordAction(result2, absorbed2)) {
@@ -82531,7 +82795,7 @@ ${statePacket}`, redactionCredentials) },
                 type: "TYPE",
                 value: "\n",
                 selector: `css=${hybridField.css}`,
-                metadata: metadataForHybridElement(hybridField, beforeScreenName2)
+                metadata: metadataForHybridElement(hybridField, beforeScreenName2, hybridElementsOf(before2))
               });
             }
             return actionPayload(result2, absorbed2);
@@ -82543,6 +82807,7 @@ ${statePacket}`, redactionCredentials) },
             return { ok: false, error: "This driver does not support non-clearing keyboard submit." };
           }
           const beforeScreenName = screenName();
+          const before = latest();
           const result = await driver.submitKeyboard(element.bounds);
           const absorbed = await absorbActionResult(result, "mobile_submit_keyboard");
           if (shouldRecordAction(result, absorbed)) {
@@ -82550,7 +82815,7 @@ ${statePacket}`, redactionCredentials) },
               type: "TYPE",
               value: "\n",
               selector: (0, mobile_source_parser_js_2.preferredLocator)(element),
-              metadata: metadataForElement(element, beforeScreenName, platform3)
+              metadata: metadataForElement(element, beforeScreenName, platform3, nativeElementsOf(before))
             });
           }
           return actionPayload(result, absorbed);
@@ -82575,10 +82840,11 @@ ${statePacket}`, redactionCredentials) },
               return { ok: false, error: "This driver does not support hybrid WEBVIEW typing." };
             }
             const beforeScreenName2 = screenName();
+            const before2 = latest();
             const result2 = await driver.webType(hybridFill.webviewContext, hybridFill.css, secret);
             const absorbed2 = await absorbActionResult(result2, "mobile_fill_credential(webview)");
             if (shouldRecordAction(result2, absorbed2)) {
-              const metadata = metadataForHybridElement(hybridFill, beforeScreenName2);
+              const metadata = metadataForHybridElement(hybridFill, beforeScreenName2, hybridElementsOf(before2));
               const label = metadata.targetLabel ?? hybridFill.css;
               recordAction({
                 type: "TYPE",
@@ -82593,7 +82859,14 @@ ${statePacket}`, redactionCredentials) },
           const element = resolveRef(toolArgs.ref);
           if (!element)
             return unknownRef(toolArgs.ref);
+          if (alreadyFocusedWithEqualValue(element, secret)) {
+            return {
+              ok: false,
+              error: `"${labelForElement(element)}" is already focused and already holds this exact credential value \u2014 typing it again is a no-op. Move on to the next step.`
+            };
+          }
           const beforeScreenName = screenName();
+          const before = latest();
           const result = await driver.type(secret, element.bounds);
           const absorbed = await absorbActionResult(result, "mobile_fill_credential");
           if (shouldRecordAction(result, absorbed)) {
@@ -82601,7 +82874,7 @@ ${statePacket}`, redactionCredentials) },
               type: "TYPE",
               value: (0, shared_1.mobileCredentialPlaceholder)(key),
               selector: (0, mobile_source_parser_js_2.preferredLocator)(element),
-              metadata: metadataForElement(element, beforeScreenName, platform3)
+              metadata: metadataForElement(element, beforeScreenName, platform3, nativeElementsOf(before))
             });
             log2(`  fill_credential: recorded {{${key}}} into ${labelForElement(element)}`);
           }
@@ -82629,13 +82902,14 @@ ${statePacket}`, redactionCredentials) },
           if (!element)
             return unknownRef(toolArgs.ref);
           const beforeScreenName = screenName();
+          const before = latest();
           const result = await driver.clear(element.bounds);
           const absorbed = await absorbActionResult(result, "mobile_clear");
           if (shouldRecordAction(result, absorbed)) {
             recordAction({
               type: "CLEAR",
               selector: (0, mobile_source_parser_js_2.preferredLocator)(element),
-              metadata: metadataForElement(element, beforeScreenName, platform3)
+              metadata: metadataForElement(element, beforeScreenName, platform3, nativeElementsOf(before))
             });
           }
           return actionPayload(result, absorbed);
@@ -82698,7 +82972,7 @@ ${statePacket}`, redactionCredentials) },
         case "mobile_assert_visible": {
           const hybrid = resolveHybridRef(toolArgs.ref);
           if (hybrid) {
-            const metadata = metadataForHybridElement(hybrid, screenName());
+            const metadata = metadataForHybridElement(hybrid, screenName(), hybridElementsOf(latest()));
             recordAction({
               type: "ASSERT_VISIBLE",
               selector: `css=${hybrid.css}`,
@@ -82738,7 +83012,7 @@ ${statePacket}`, redactionCredentials) },
                 error: `Live WEBVIEW text assertion failed: expected ${JSON.stringify(expected)} was not present on ref ${hybrid.ref}. Re-snapshot after the outcome appears and assert the text that is actually visible.`
               };
             }
-            const metadata2 = metadataForHybridElement(hybrid, screenName());
+            const metadata2 = metadataForHybridElement(hybrid, screenName(), hybridElementsOf(latest()));
             const stableWebIdentity = Boolean(nonEmpty3(hybrid.id) || nonEmpty3(hybrid.name));
             if (stableWebIdentity) {
               recordAction({
@@ -82791,7 +83065,7 @@ ${statePacket}`, redactionCredentials) },
               error: `Expected text ${JSON.stringify(expected)} is ${volatileExpected.tier === 1 ? "transient one-shot UI" : "session-dynamic content"} (${volatileExpected.reason}) \u2014 it changes between runs, so the test would fail forever on a healthy app. Assert durable post-state instead: an element unique to the destination screen, a stable label, or text your flow itself entered.`
             };
           }
-          const metadata = metadataForElement(element, screenName(), platform3);
+          const metadata = metadataForElement(element, screenName(), platform3, nativeElementsOf(latest()));
           const expectedNeedle = expected.trim().toLowerCase();
           const identityValues = [element.accessibilityId, element.resourceId].map((value) => value?.trim().toLowerCase()).filter((value) => Boolean(value));
           const visibleText = (element.text ?? "").trim().toLowerCase();
@@ -82837,7 +83111,7 @@ ${statePacket}`, redactionCredentials) },
             error: `Ref ${element.ref} is not a durable assertion target (${weakReason2}). Re-snapshot and assert a human-visible label, text, or stable control that proves the screen outcome.`
           };
         }
-        const metadata2 = metadataForElement(element, screenName(), platform3);
+        const metadata2 = metadataForElement(element, screenName(), platform3, nativeElementsOf(latest()));
         recordAction({ type: "ASSERT_VISIBLE", selector: (0, mobile_source_parser_js_2.preferredLocator)(element), metadata: metadata2 });
         return { ok: true, label: metadata2.targetLabel ?? "element" };
       }
@@ -82887,7 +83161,7 @@ ${statePacket}`, redactionCredentials) },
           error: `The live element matching ${JSON.stringify(accessibilityId ?? text)} is not a durable assertion target (${weakReason}).`
         };
       }
-      const metadata = metadataForElement(liveElement, screenName(), platform3);
+      const metadata = metadataForElement(liveElement, screenName(), platform3, live.screen.elements);
       recordAction({
         type: "ASSERT_VISIBLE",
         selector: (0, mobile_source_parser_js_2.preferredLocator)(liveElement),
@@ -83015,7 +83289,7 @@ ${statePacket}`, redactionCredentials) },
       actions.push(finalizeAction({
         type: "ASSERT_VISIBLE",
         selector: (0, mobile_source_parser_js_2.preferredLocator)(anchor),
-        metadata: metadataForElement(anchor, screen, platform3)
+        metadata: metadataForElement(anchor, screen, platform3, nativeElementsOf(recording.lastSnapshot))
       }));
       return true;
     }
@@ -83358,6 +83632,168 @@ ${statePacket}`, redactionCredentials) },
       }
       return out;
     }
+    function isDurableMutation(action) {
+      if (action.type === "TYPE" || action.type === "CLEAR")
+        return true;
+      if (action.type === "TAP")
+        return (0, shared_1.isStateValueMobileClassName)(action.metadata.locatorBundle?.className);
+      return false;
+    }
+    function mobileWanderTraceEnabled2() {
+      const v = (process.env.VALIDATEQA_MOBILE_WANDER_TRACE || "").trim().toLowerCase();
+      return v === "true" || v === "1";
+    }
+    function wanderTraceLabel(action) {
+      const identity = action.metadata.targetLabel || action.selector || action.metadata.locatorBundle?.accessibilityId || action.metadata.locatorBundle?.resourceId || "(no identity)";
+      return `${action.type} ${identity}`;
+    }
+    function logWanderDiff(pass, before, after, log2) {
+      if (after.length >= before.length)
+        return;
+      log2(`  ${pass}: collapsed ${before.length - after.length} step(s) (${before.length} \u2192 ${after.length}).`);
+      if (!mobileWanderTraceEnabled2())
+        return;
+      const survivors = new Set(after);
+      for (const action of before) {
+        if (!survivors.has(action)) {
+          log2(`  [wander] ${pass}: dropped ${wanderTraceLabel(action)}`);
+        }
+      }
+    }
+    function coalesceSameFieldTypes(actions) {
+      if (actions.length <= 1)
+        return actions;
+      const toDrop = /* @__PURE__ */ new Set();
+      const lastTypeIndexBySelector = /* @__PURE__ */ new Map();
+      const refocusTapIndexesBySelector = /* @__PURE__ */ new Map();
+      for (let i = 0; i < actions.length; i++) {
+        const current = actions[i];
+        if (current.type === "ASSERT_VISIBLE" || current.type === "ASSERT_TEXT") {
+          lastTypeIndexBySelector.clear();
+          refocusTapIndexesBySelector.clear();
+          continue;
+        }
+        if (current.type === "CLEAR") {
+          lastTypeIndexBySelector.delete(current.selector);
+          refocusTapIndexesBySelector.delete(current.selector);
+          continue;
+        }
+        if (isFormCommitAction(current)) {
+          lastTypeIndexBySelector.clear();
+          refocusTapIndexesBySelector.clear();
+          continue;
+        }
+        if (current.type === "TAP") {
+          if (current.selector) {
+            const list = refocusTapIndexesBySelector.get(current.selector) ?? [];
+            list.push(i);
+            refocusTapIndexesBySelector.set(current.selector, list);
+          }
+          continue;
+        }
+        if (current.type !== "TYPE" || !current.selector)
+          continue;
+        const priorIndex = lastTypeIndexBySelector.get(current.selector);
+        if (priorIndex !== void 0) {
+          toDrop.add(priorIndex);
+          for (const tapIndex of refocusTapIndexesBySelector.get(current.selector) ?? []) {
+            if (tapIndex > priorIndex && tapIndex < i)
+              toDrop.add(tapIndex);
+          }
+        }
+        lastTypeIndexBySelector.set(current.selector, i);
+        refocusTapIndexesBySelector.set(current.selector, []);
+      }
+      if (toDrop.size === 0)
+        return actions;
+      return actions.filter((_, index) => !toDrop.has(index));
+    }
+    function coalesceRepeatedTaps(actions) {
+      if (actions.length <= 1)
+        return actions;
+      const toDrop = /* @__PURE__ */ new Set();
+      const lastTapIndexBySelector = /* @__PURE__ */ new Map();
+      for (let i = 0; i < actions.length; i++) {
+        const action = actions[i];
+        if (action.type === "ASSERT_VISIBLE" || action.type === "ASSERT_TEXT") {
+          lastTapIndexBySelector.clear();
+          continue;
+        }
+        if (isDurableMutation(action)) {
+          lastTapIndexBySelector.clear();
+          continue;
+        }
+        if (action.type !== "TAP" || !action.selector)
+          continue;
+        const key = action.metadata.structuralKey;
+        const priorIndex = lastTapIndexBySelector.get(action.selector);
+        if (priorIndex !== void 0 && key && actions[priorIndex].metadata.structuralKey === key) {
+          const priorHash = actions[priorIndex].metadata.screenHash;
+          const currentHash = action.metadata.screenHash;
+          const screenAdvanced = !!priorHash && !!currentHash && priorHash !== currentHash;
+          if (!screenAdvanced) {
+            toDrop.add(priorIndex);
+          }
+        }
+        lastTapIndexBySelector.set(action.selector, i);
+      }
+      if (toDrop.size === 0)
+        return actions;
+      return actions.filter((_, index) => !toDrop.has(index));
+    }
+    var MAX_DETOUR_LENGTH = 6;
+    function isDetourClosingAction(action) {
+      if (action.type === "BACK" || action.type === "HOME")
+        return true;
+      return isNavigationChromeTap(action);
+    }
+    function isEvidenceAction(action) {
+      return action.type === "ASSERT_VISIBLE" || action.type === "ASSERT_TEXT" || action.type === "WAIT_FOR_ELEMENT";
+    }
+    function elideNoOpDetours(actions) {
+      if (actions.length < 2)
+        return actions;
+      const toDrop = /* @__PURE__ */ new Set();
+      for (let j = 0; j < actions.length; j++) {
+        if (toDrop.has(j))
+          continue;
+        if (!isDetourClosingAction(actions[j]))
+          continue;
+        const keyAfter = actions[j].metadata.structuralKey;
+        if (!keyAfter)
+          continue;
+        const next = actions[j + 1];
+        if (next && isEvidenceAction(next))
+          continue;
+        let bestStart = null;
+        let leftScreen = false;
+        const earliestStart = Math.max(0, j - MAX_DETOUR_LENGTH + 1);
+        for (let i = j; i >= earliestStart; i--) {
+          if (i < j) {
+            const inside = actions[i];
+            if (inside.type === "ASSERT_VISIBLE" || inside.type === "ASSERT_TEXT" || isDurableMutation(inside)) {
+              break;
+            }
+            const insideKey = inside.metadata.structuralKey;
+            if (insideKey && insideKey !== keyAfter)
+              leftScreen = true;
+          }
+          if (i === 0)
+            continue;
+          const keyBefore = actions[i - 1].metadata.structuralKey;
+          if (i < j && leftScreen && keyBefore && keyBefore === keyAfter) {
+            bestStart = i;
+          }
+        }
+        if (bestStart !== null) {
+          for (let k = bestStart; k <= j; k++)
+            toDrop.add(k);
+        }
+      }
+      if (toDrop.size === 0)
+        return actions;
+      return actions.filter((_, index) => !toDrop.has(index));
+    }
     function mobileActionsToPseudoPlaywright(actions) {
       const escape = (s) => s.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
       const lines = ["test('mobile', async ({ page }) => {"];
@@ -83445,6 +83881,15 @@ ${statePacket}`, redactionCredentials) },
       if (actions.length < beforeCycleCollapse) {
         log2(`  collapsed ${beforeCycleCollapse - actions.length} retry-cycle step(s) out of the recorded trace (${beforeCycleCollapse} \u2192 ${actions.length}).`);
       }
+      const beforeTypeCoalesce = actions;
+      actions = coalesceSameFieldTypes(actions);
+      logWanderDiff("coalesceSameFieldTypes", beforeTypeCoalesce, actions, log2);
+      const beforeTapCoalesce = actions;
+      actions = coalesceRepeatedTaps(actions);
+      logWanderDiff("coalesceRepeatedTaps", beforeTapCoalesce, actions, log2);
+      const beforeDetourElision = actions;
+      actions = elideNoOpDetours(actions);
+      logWanderDiff("elideNoOpDetours", beforeDetourElision, actions, log2);
       const beforeContainerDrop = actions.length;
       actions = actions.filter((a) => !isBareContainerTap(a));
       if (actions.length < beforeContainerDrop) {
@@ -83629,48 +84074,29 @@ ${statePacket}`, redactionCredentials) },
         log2("  app data reset skipped by policy \u2014 scenario records after relaunch with preserved data.");
         return applyScenarioEntryDeepLink(driver, target, { appDataCleared: false, coldResetUnavailable: false, refuseGenerate: false, reason: "preserve_policy" }, log2);
       }
-      if (platform3 !== "IOS") {
-        const appDataCleared = await driver.resetAppState?.().catch((err) => {
-          log2(`  app-data reset failed: ${err instanceof Error ? err.message : String(err)}`);
-          return false;
-        }) ?? false;
-        if (appDataCleared) {
-          return applyScenarioEntryDeepLink(driver, target, { appDataCleared: true, coldResetUnavailable: false, refuseGenerate: false }, log2);
-        }
-        await driver.relaunch();
-        if (resetPolicy === "CLEAR_APP_DATA") {
-          log2("  CLEAR_APP_DATA required but app-data reset was unavailable \u2014 refusing to generate from warm state.");
-          return {
-            appDataCleared: false,
-            coldResetUnavailable: true,
-            refuseGenerate: true,
-            reason: "clear_app_data_unavailable"
-          };
-        }
-        log2("  app-data reset unavailable \u2014 generating with @warm-state (relaunch only; may not match cold-boot replay).");
-        return applyScenarioEntryDeepLink(driver, target, {
-          appDataCleared: false,
-          coldResetUnavailable: true,
-          refuseGenerate: false,
-          reason: platform3 === "ANDROID" ? "android_reset_unavailable" : "reset_unavailable"
-        }, log2);
+      const appDataCleared = await driver.resetAppState?.().catch((err) => {
+        log2(`  app-data reset failed: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+      }) ?? false;
+      if (appDataCleared) {
+        return applyScenarioEntryDeepLink(driver, target, { appDataCleared: true, coldResetUnavailable: false, refuseGenerate: false }, log2);
       }
       await driver.relaunch();
       if (resetPolicy === "CLEAR_APP_DATA") {
-        log2("  CLEAR_APP_DATA required but iOS has no supported clearApp primitive \u2014 refusing to generate from warm state.");
+        log2(platform3 === "IOS" ? "  CLEAR_APP_DATA required but this iOS device cannot be cleared (simulator required) \u2014 refusing to generate from warm state." : "  CLEAR_APP_DATA required but app-data reset was unavailable \u2014 refusing to generate from warm state.");
         return {
           appDataCleared: false,
           coldResetUnavailable: true,
           refuseGenerate: true,
-          reason: "ios_clear_app_data_unavailable"
+          reason: platform3 === "IOS" ? "ios_clear_app_data_unavailable" : "clear_app_data_unavailable"
         };
       }
-      log2("  iOS has no clearApp \u2014 scenario records after relaunch (warm-state risk for auth flows).");
+      log2(platform3 === "IOS" ? "  iOS app-data reset unavailable (physical device or simctl failure) \u2014 generating with @warm-state (relaunch only; may not match cold-boot replay)." : "  app-data reset unavailable \u2014 generating with @warm-state (relaunch only; may not match cold-boot replay).");
       return applyScenarioEntryDeepLink(driver, target, {
         appDataCleared: false,
         coldResetUnavailable: true,
         refuseGenerate: false,
-        reason: "ios_no_clear_app"
+        reason: platform3 === "IOS" ? "ios_no_clear_app" : platform3 === "ANDROID" ? "android_reset_unavailable" : "reset_unavailable"
       }, log2);
     }
     async function runMobileGeneratePhase(args) {
@@ -84273,6 +84699,8 @@ var require_mobile_heal_loop = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.MOBILE_LIVE_HEAL_SYSTEM_PROMPT = exports2.MOBILE_SCRIPT_HEAL_SYSTEM_PROMPT = void 0;
+    exports2.timed = timed;
+    exports2.timedSync = timedSync;
     exports2.executeMobileScriptDrivenHeal = executeMobileScriptDrivenHeal;
     exports2.executeMobileTestWithHealing = executeMobileTestWithHealing2;
     exports2.executeMobileLiveHeal = executeMobileLiveHeal2;
@@ -84482,6 +84910,32 @@ For a fix, return the COMPLETE steps array (not a diff).`;
     function detectInvalidMobileAuthSetup(steps, error2) {
       return detectInvalidExternalAuthSetup(steps, error2) ?? detectInvalidAuthValidationSetup(steps, error2);
     }
+    function formatHealTimingLine(category, label, ms, failed, errMessage) {
+      const base2 = `\u{1FA7A}\u23F1 [${category}] ${label} \u2014 ${ms}ms`;
+      return failed ? `${base2} (FAILED: ${errMessage ?? "unknown error"})` : base2;
+    }
+    async function timed(category, label, onProgress, fn) {
+      const start = Date.now();
+      try {
+        const result = await fn();
+        onProgress?.(formatHealTimingLine(category, label, Date.now() - start, false));
+        return result;
+      } catch (err) {
+        onProgress?.(formatHealTimingLine(category, label, Date.now() - start, true, err instanceof Error ? err.message : String(err)));
+        throw err;
+      }
+    }
+    function timedSync(category, label, onProgress, fn) {
+      const start = Date.now();
+      try {
+        const result = fn();
+        onProgress?.(formatHealTimingLine(category, label, Date.now() - start, false));
+        return result;
+      } catch (err) {
+        onProgress?.(formatHealTimingLine(category, label, Date.now() - start, true, err instanceof Error ? err.message : String(err)));
+        throw err;
+      }
+    }
     var IDENTITY_GATE_ERROR_RE = /No identity locator \(accessibility id \/ resource id \/ text\) available for this step/;
     function isIdentityEqualityXpath(value) {
       return /@[A-Za-z_:][-A-Za-z0-9_:.]*\s*=/.test(value) && !/(?:contains|starts-with)\s*\(/i.test(value);
@@ -84699,21 +85153,23 @@ For a fix, return the COMPLETE steps array (not a diff).`;
       return JSON.stringify(base2?.target) !== JSON.stringify(healed.target);
     }
     function findMissingChangedLocators(baseSteps, healedSteps, screen) {
-      const missing = [];
+      const results = [];
       healedSteps.forEach((healed, index) => {
         if (!stepTargetChanged(baseSteps[index], healed))
           return;
         const candidate = stepToLocatorCandidate(healed);
         if (!candidate)
           return;
-        if ((0, mobile_source_parser_js_1.resolveLocatorAgainstScreen)(candidate, screen).length === 0) {
-          missing.push({
-            label: healed.target?.primary ?? JSON.stringify(candidate),
-            expressions: stepIdentityExpressions(healed)
-          });
+        const matchCount = (0, mobile_source_parser_js_1.resolveLocatorAgainstScreen)(candidate, screen).length;
+        const label = healed.target?.primary ?? JSON.stringify(candidate);
+        const expressions = stepIdentityExpressions(healed);
+        if (matchCount === 0) {
+          results.push({ label, expressions, kind: "missing" });
+        } else if (matchCount > 1) {
+          results.push({ label, expressions, kind: "ambiguous", matchCount });
         }
       });
-      return missing;
+      return results;
     }
     function changedStepExpressions(baseSteps, healedSteps) {
       const out = [];
@@ -84942,10 +85398,10 @@ ${args.directive}`);
         let content;
         let finishReason;
         try {
-          const response = await (0, ai_retry_js_1.resilientAICall)((signal, arm) => (0, ai_queue_js_1.queuedAICall)(() => {
+          const response = await timed("model", `phase1-attempt-${attempt}-model-call`, options.onProgress, () => (0, ai_retry_js_1.resilientAICall)((signal, arm) => (0, ai_queue_js_1.queuedAICall)(() => {
             arm();
-            return aiClient.chat.completions.create({ model, messages, max_tokens: 8e3, temperature: 0.1 }, { signal });
-          }), { label: `mobile-heal-attempt-${attempt}`, deferTimeoutUntilArmed: true });
+            return aiClient.chat.completions.create({ model, messages, max_tokens: 16e3, temperature: 0.1, ...(0, ai_provider_js_1.getNoThinkingRequestOptions)(model) }, { signal });
+          }), { label: `mobile-heal-attempt-${attempt}`, deferTimeoutUntilArmed: true }));
           content = response?.choices?.[0]?.message?.content ?? "";
           finishReason = response?.choices?.[0]?.finish_reason ?? void 0;
         } catch {
@@ -84988,14 +85444,18 @@ ${args.directive}`);
           continue;
         }
         if (activeFailingSource && isLocatorNotFound(activeError) && !isDrift(activeError)) {
-          const screen = (0, mobile_source_parser_js_1.parseMobileSource)(activeFailingSource, platform3);
-          const missing = findMissingChangedLocators(baseSteps, healedSteps, screen);
+          const failingSourceSnapshot = activeFailingSource;
+          const missing = timedSync("device-op", `phase1-attempt-${attempt}-static-verify`, options.onProgress, () => {
+            const screen = (0, mobile_source_parser_js_1.parseMobileSource)(failingSourceSnapshot, platform3);
+            return findMissingChangedLocators(baseSteps, healedSteps, screen);
+          });
           if (missing.length > 0) {
             for (const entry of missing)
               pushUnique(triedLocators, entry.expressions);
             markRecoverableTurn();
             lastVerdict = "fix";
-            pendingDirective = `Your proposed locator ${missing[0].label} does NOT exist in the captured screen tree. Pick an identity locator (resource-id, accessibility-id, or exact @text=) that is PRESENT in the tree.`;
+            const first = missing[0];
+            pendingDirective = first.kind === "ambiguous" ? `Your proposed locator ${first.label} matches ${first.matchCount ?? "more than one"} elements in the captured screen tree \u2014 it cannot identify the recorded instance. Pick an identity locator (resource-id, accessibility-id, or exact @text=) that resolves to EXACTLY ONE element in the tree.` : `Your proposed locator ${first.label} does NOT exist in the captured screen tree. Pick an identity locator (resource-id, accessibility-id, or exact @text=) that is PRESENT in the tree.`;
             continue;
           }
         }
@@ -85009,9 +85469,10 @@ ${args.directive}`);
           pendingDirective = "The proposed fix could not be device-verified here. If it is not clearly correct, revise it.";
           continue;
         }
+        const runNativeTest = options.runNativeTest;
         let verify;
         try {
-          verify = await options.runNativeTest({ steps: healedSteps, target, testVariables: ctx.testVariables });
+          verify = await timed("reexec", `phase1-attempt-${attempt}-device-verify`, options.onProgress, () => runNativeTest({ steps: healedSteps, target, testVariables: ctx.testVariables }));
         } catch {
           return {
             passed: false,
@@ -85118,6 +85579,9 @@ ${args.directive}`);
       }
     }
     async function executeMobileTestWithHealing2(steps, target, ctx, options) {
+      return timed("total", "heal-total", options.onProgress, () => executeMobileTestWithHealingImpl(steps, target, ctx, options));
+    }
+    async function executeMobileTestWithHealingImpl(steps, target, ctx, options) {
       const invalidAuthSetup = detectInvalidMobileAuthSetup(steps, ctx.error);
       if (invalidAuthSetup) {
         return { passed: false, verdict: "test_invalid", healReason: invalidAuthSetup };
@@ -85244,9 +85708,10 @@ For a fix, return the COMPLETE steps array (not a diff). Use "observe" only to r
       const candidate = partsToCandidate(parts);
       if (!hasIdentitySignal(candidate))
         return;
-      const first = (0, mobile_source_parser_js_1.resolveLocatorAgainstScreen)(candidate, screen)[0];
-      if (first)
-        await driver.tap(first.bounds);
+      const matches = (0, mobile_source_parser_js_1.resolveLocatorAgainstScreen)(candidate, screen);
+      const target = matches.find((el) => el.bounds.width > 0 && el.bounds.height > 0) ?? matches[0];
+      if (target)
+        await driver.tap(target.bounds);
     }
     function buildLiveUserContent(args) {
       const parts = [];
@@ -85311,7 +85776,7 @@ For a fix, return the COMPLETE steps array (not a diff). Use "observe" only to r
         options.onProgress?.(`Phase 2 pass ${pass}/${maxPasses} \u2014 observing the live screen...`);
         let snap;
         try {
-          snap = await liveDriver.snapshot();
+          snap = await timed("device-op", `phase2-pass-${pass}-snapshot`, options.onProgress, () => liveDriver.snapshot());
         } catch {
           return {
             passed: false,
@@ -85337,10 +85802,10 @@ For a fix, return the COMPLETE steps array (not a diff). Use "observe" only to r
         ];
         let content;
         try {
-          const response = await (0, mobile_session_keepalive_js_1.withMobileSessionKeepAlive)(keepAlivePingable, () => (0, ai_retry_js_1.resilientAICall)((signal, arm) => (0, ai_queue_js_1.queuedAICall)(() => {
+          const response = await timed("model", `phase2-pass-${pass}-model-call`, options.onProgress, () => (0, mobile_session_keepalive_js_1.withMobileSessionKeepAlive)(keepAlivePingable, () => (0, ai_retry_js_1.resilientAICall)((signal, arm) => (0, ai_queue_js_1.queuedAICall)(() => {
             arm();
-            return aiClient.chat.completions.create({ model, messages, max_tokens: 8e3, temperature: 0.1 }, { signal });
-          }), { label: `mobile-live-heal-pass-${pass}`, deferTimeoutUntilArmed: true }));
+            return aiClient.chat.completions.create({ model, messages, max_tokens: 16e3, temperature: 0.1, ...(0, ai_provider_js_1.getNoThinkingRequestOptions)(model) }, { signal });
+          }), { label: `mobile-live-heal-pass-${pass}`, deferTimeoutUntilArmed: true })));
           content = response?.choices?.[0]?.message?.content ?? "";
         } catch {
           continue;
@@ -85372,7 +85837,7 @@ For a fix, return the COMPLETE steps array (not a diff). Use "observe" only to r
         const healedSteps = parsed.steps;
         let verify;
         try {
-          verify = await runNativeTest({ steps: healedSteps, target, testVariables });
+          verify = await timed("reexec", `phase2-pass-${pass}-verify`, options.onProgress, () => runNativeTest({ steps: healedSteps, target, testVariables }));
         } catch {
           return {
             passed: false,
@@ -89226,7 +89691,7 @@ var require_kill_tree = __commonJS({
     var node_child_process_1 = require("child_process");
     var node_util_1 = require("util");
     var node_fs_1 = require("fs");
-    var execFileAsync3 = (0, node_util_1.promisify)(node_child_process_1.execFile);
+    var execFileAsync4 = (0, node_util_1.promisify)(node_child_process_1.execFile);
     var PS_TIMEOUT_MS = 2e3;
     var PS_BUFFER = 1024 * 1024;
     async function gracefulCloseWithTreeKill(options) {
@@ -89280,7 +89745,7 @@ var require_kill_tree = __commonJS({
       timer.unref?.();
       let stdout;
       try {
-        const result = await execFileAsync3("ps", ["-A", "-o", "pid=,ppid=,command="], {
+        const result = await execFileAsync4("ps", ["-A", "-o", "pid=,ppid=,command="], {
           maxBuffer: PS_BUFFER,
           signal: controller.signal
         });
@@ -89318,7 +89783,7 @@ var require_kill_tree = __commonJS({
       timer.unref?.();
       let stdout;
       try {
-        const result = await execFileAsync3("ps", ["-A", "-o", "pid=,ppid=,command="], {
+        const result = await execFileAsync4("ps", ["-A", "-o", "pid=,ppid=,command="], {
           maxBuffer: PS_BUFFER,
           signal: controller.signal
         });
@@ -89395,7 +89860,7 @@ var require_kill_tree = __commonJS({
       timer.unref?.();
       let stdout;
       try {
-        const result = await execFileAsync3("ps", ["-A", "-o", "pid=,ppid="], {
+        const result = await execFileAsync4("ps", ["-A", "-o", "pid=,ppid="], {
           maxBuffer: PS_BUFFER,
           signal: controller.signal
         });
@@ -99274,8 +99739,8 @@ Do NOT add steps you did not execute. Do NOT skip steps from the recording.${led
               onRetry: (attempt, reason, delayMs) => logs2.push(`    \u26A0 scenario-gen AI call retry ${attempt} (${reason}) \u2014 waiting ${delayMs}ms`)
             });
           } catch (aiErr) {
-            const errMsg2 = aiErr instanceof Error ? aiErr.message : String(aiErr);
-            logs2.push(`    AI call failed at iteration ${iteration} (after retries): ${errMsg2}`);
+            const errMsg3 = aiErr instanceof Error ? aiErr.message : String(aiErr);
+            logs2.push(`    AI call failed at iteration ${iteration} (after retries): ${errMsg3}`);
             throw (0, ai_retry_js_1.markAIProviderError)(aiErr);
           }
           const iterDuration = Date.now() - iterStart;
@@ -99318,8 +99783,8 @@ Do NOT add steps you did not execute. Do NOT skip steps from the recording.${led
             try {
               toolArgs = JSON.parse(toolCall.function.arguments);
             } catch (parseErr) {
-              const errMsg2 = `Invalid tool arguments: ${parseErr.message}`;
-              toolResults.push({ role: "tool", tool_call_id: toolCall.id, content: errMsg2 });
+              const errMsg3 = `Invalid tool arguments: ${parseErr.message}`;
+              toolResults.push({ role: "tool", tool_call_id: toolCall.id, content: errMsg3 });
               continue;
             }
             if (toolName === "finish_generate") {
@@ -100577,7 +101042,7 @@ var require_util4 = __commonJS({
         }
         path = url.path;
       }
-      var isAbsolute = exports2.isAbsolute(path);
+      var isAbsolute2 = exports2.isAbsolute(path);
       var parts = path.split(/\/+/);
       for (var part, up = 0, i = parts.length - 1; i >= 0; i--) {
         part = parts[i];
@@ -100597,7 +101062,7 @@ var require_util4 = __commonJS({
       }
       path = parts.join("/");
       if (path === "") {
-        path = isAbsolute ? "/" : ".";
+        path = isAbsolute2 ? "/" : ".";
       }
       if (url) {
         url.path = path;
@@ -100606,7 +101071,7 @@ var require_util4 = __commonJS({
       return path;
     }
     exports2.normalize = normalize;
-    function join7(aRoot, aPath) {
+    function join8(aRoot, aPath) {
       if (aRoot === "") {
         aRoot = ".";
       }
@@ -100638,7 +101103,7 @@ var require_util4 = __commonJS({
       }
       return joined;
     }
-    exports2.join = join7;
+    exports2.join = join8;
     exports2.isAbsolute = function(aPath) {
       return aPath.charAt(0) === "/" || urlRegexp.test(aPath);
     };
@@ -100811,7 +101276,7 @@ var require_util4 = __commonJS({
             parsed.path = parsed.path.substring(0, index + 1);
           }
         }
-        sourceURL = join7(urlGenerate(parsed), sourceURL);
+        sourceURL = join8(urlGenerate(parsed), sourceURL);
       }
       return normalize(sourceURL);
     }
@@ -314524,8 +314989,8 @@ Try a different fix approach. This is NOT your final script-driven attempt yet,
             ...(0, ai_provider_js_1.getJsonObjectResponseFormat)(agentModel)
           })), { label: `script-heal-${attempt}` });
         } catch (aiErr) {
-          const errMsg2 = aiErr instanceof Error ? aiErr.message : String(aiErr);
-          logs2.push(`\u26A0 AI call failed: ${errMsg2}`);
+          const errMsg3 = aiErr instanceof Error ? aiErr.message : String(aiErr);
+          logs2.push(`\u26A0 AI call failed: ${errMsg3}`);
           attemptHistory.push({
             phase: "script",
             attempt,
@@ -314533,13 +314998,13 @@ Try a different fix approach. This is NOT your final script-driven attempt yet,
             passed: false,
             changedCode: false,
             summary: "AI call failed before returning a heal result",
-            errorSummary: truncateForPrompt(errMsg2),
+            errorSummary: truncateForPrompt(errMsg3),
             failedStep: summarizeFailedStep(currentStepResults)
           });
           if (feedbackEnabled) {
-            lastTransportFailure = truncateForPrompt(errMsg2, 200) ?? "the AI request failed";
+            lastTransportFailure = truncateForPrompt(errMsg3, 200) ?? "the AI request failed";
           } else {
-            currentError = `AI call failed on attempt ${attempt}: ${errMsg2}`;
+            currentError = `AI call failed on attempt ${attempt}: ${errMsg3}`;
           }
           markRecoverableTurn();
           continue;
@@ -314823,8 +315288,8 @@ ${currentError.slice(0, 2e3)}`
             // item 5b
           });
         } catch (runErr) {
-          const errMsg2 = runErr instanceof Error ? runErr.message : String(runErr);
-          logs2.push(`\u{1F4A5} Native execution threw: ${errMsg2}`);
+          const errMsg3 = runErr instanceof Error ? runErr.message : String(runErr);
+          logs2.push(`\u{1F4A5} Native execution threw: ${errMsg3}`);
           attemptHistory.push({
             phase: "script",
             attempt,
@@ -314832,9 +315297,9 @@ ${currentError.slice(0, 2e3)}`
             passed: false,
             changedCode: true,
             summary: truncateForPrompt(changeDesc) ?? "Applied code fix, but native execution threw before verification completed",
-            errorSummary: truncateForPrompt(errMsg2)
+            errorSummary: truncateForPrompt(errMsg3)
           });
-          currentError = `Native execution threw: ${errMsg2}`;
+          currentError = `Native execution threw: ${errMsg3}`;
           currentStepResults = [];
           continue;
         }
@@ -315590,9 +316055,9 @@ Last error (after heal attempts): ${lastErrorSnippet}` : `Heal aborted: same err
                 previousErrorSignature = errorSig;
               }
             } catch (runErr) {
-              const errMsg2 = runErr instanceof Error ? runErr.message : String(runErr);
-              logs2.push(`\u{1F4A5} Native run threw: ${errMsg2}`);
-              currentError = errMsg2;
+              const errMsg3 = runErr instanceof Error ? runErr.message : String(runErr);
+              logs2.push(`\u{1F4A5} Native run threw: ${errMsg3}`);
+              currentError = errMsg3;
               currentStepResults = [];
             }
           } else {
@@ -316154,8 +316619,8 @@ When you call finish_fix, preserve locators only when they are stable structural
                     }
                   }
                 } catch (toolErr) {
-                  const errMsg2 = toolErr instanceof Error ? toolErr.message : String(toolErr);
-                  let errorContent = `Error: ${errMsg2}`;
+                  const errMsg3 = toolErr instanceof Error ? toolErr.message : String(toolErr);
+                  let errorContent = `Error: ${errMsg3}`;
                   try {
                     const consoleResult = await mcpClient.callTool({ name: "browser_console_messages", arguments: {} });
                     const consoleText = Array.isArray(consoleResult.content) ? consoleResult.content.map((c) => c.type === "text" ? c.text ?? "" : "").join("\n") : String(consoleResult.content ?? "");
@@ -316176,8 +316641,8 @@ ${errorContent}`;
               }
             }
           } catch (mcpErr) {
-            const errMsg2 = mcpErr instanceof Error ? mcpErr.message : String(mcpErr);
-            logs2.push(`\u{1F4A5} MCP exploration failed: ${errMsg2}`);
+            const errMsg3 = mcpErr instanceof Error ? mcpErr.message : String(mcpErr);
+            logs2.push(`\u{1F4A5} MCP exploration failed: ${errMsg3}`);
           }
           if (verdict === "app_bug") {
             phase2AttemptHistory.push({
@@ -316771,9 +317236,9 @@ ${testBlocks}
               }
               emit(`   \u2713 ${toolResultContent.slice(0, 200)}${toolResultContent.length > 200 ? "..." : ""}`);
             } catch (err) {
-              const errMsg2 = err instanceof Error ? err.message : String(err);
-              toolResultContent = `ERROR: ${errMsg2}`;
-              emit(`   \u2717 ${errMsg2}`);
+              const errMsg3 = err instanceof Error ? err.message : String(err);
+              toolResultContent = `ERROR: ${errMsg3}`;
+              emit(`   \u2717 ${errMsg3}`);
             }
             toolResults.push({ role: "tool", tool_call_id: toolCall.id, content: toolResultContent });
           }
@@ -323057,8 +323522,8 @@ var require_capture_page_normalizer = __commonJS({
         const snapItems = Array.isArray(snapResult.content) ? snapResult.content : [];
         snapshotText = extractInlineSnapshotYaml(snapItems.find((c) => c.type === "text")?.text || null);
       } catch (err) {
-        const errMsg2 = err instanceof Error ? err.message : String(err);
-        const isTimeout = /timeout|timed out|TimeoutError/i.test(errMsg2);
+        const errMsg3 = err instanceof Error ? err.message : String(err);
+        const isTimeout = /timeout|timed out|TimeoutError/i.test(errMsg3);
         return {
           snapshotText: null,
           meta: {
@@ -327134,9 +327599,9 @@ ${currentSummary}`;
                     });
                   }
                 } catch (err) {
-                  const errMsg2 = err instanceof Error ? err.message : String(err);
-                  logs2.push(`   Error persisting page: ${errMsg2}`);
-                  toolResults.push({ role: "tool", tool_call_id: toolCall.id, content: `ERROR persisting page: ${errMsg2}` });
+                  const errMsg3 = err instanceof Error ? err.message : String(err);
+                  logs2.push(`   Error persisting page: ${errMsg3}`);
+                  toolResults.push({ role: "tool", tool_call_id: toolCall.id, content: `ERROR persisting page: ${errMsg3}` });
                 }
                 continue;
               }
@@ -327338,12 +327803,12 @@ ${currentSummary}`;
                   })
                 });
               } catch (err) {
-                const errMsg2 = err instanceof Error ? err.message : String(err);
-                logs2.push(`   Error persisting page: ${errMsg2}`);
+                const errMsg3 = err instanceof Error ? err.message : String(err);
+                logs2.push(`   Error persisting page: ${errMsg3}`);
                 toolResults.push({
                   role: "tool",
                   tool_call_id: toolCall.id,
-                  content: `ERROR persisting page: ${errMsg2}`
+                  content: `ERROR persisting page: ${errMsg3}`
                 });
               }
               continue;
@@ -327378,12 +327843,12 @@ ${currentSummary}`;
                   content: JSON.stringify({ acknowledged: true })
                 });
               } catch (err) {
-                const errMsg2 = err instanceof Error ? err.message : String(err);
-                logs2.push(`   Error persisting transition: ${errMsg2}`);
+                const errMsg3 = err instanceof Error ? err.message : String(err);
+                logs2.push(`   Error persisting transition: ${errMsg3}`);
                 toolResults.push({
                   role: "tool",
                   tool_call_id: toolCall.id,
-                  content: `ERROR persisting transition: ${errMsg2}`
+                  content: `ERROR persisting transition: ${errMsg3}`
                 });
               }
               continue;
@@ -328079,15 +328544,15 @@ Exploration complete: ${summary}`);
               toolResultContent = (0, snapshot_context_compactor_js_1.formatMCPToolResult)(toolResultContent, MAX_TOOL_RESULT_CHARS);
               logs2.push(`   OK: ${toolResultContent.slice(0, 200)}${toolResultContent.length > 200 ? "..." : ""}`);
             } catch (err) {
-              const errMsg2 = err instanceof Error ? err.message : String(err);
-              toolResultContent = `ERROR: ${errMsg2}`;
-              logs2.push(`   Error: ${errMsg2}`);
+              const errMsg3 = err instanceof Error ? err.message : String(err);
+              toolResultContent = `ERROR: ${errMsg3}`;
+              logs2.push(`   Error: ${errMsg3}`);
               if (useV2) {
                 (0, exploration_state_js_1.reduceEvent)(state2, {
                   type: "ACTION_FAILED",
                   route: state2.currentRoute,
                   action: `${toolName}(${JSON.stringify(toolArgs).slice(0, 100)})`,
-                  error: errMsg2
+                  error: errMsg3
                 });
               }
             }
@@ -330936,10 +331401,10 @@ ${(0, inbox_tools_js_1.buildInboxAgentsGuidance)(inboxReg.email, inboxReg.passwo
           onLog: options.onLog,
           onProvenCommands: recordProvenCommands
         });
-        const errMsg2 = firstError?.message ?? (grokError instanceof Error ? grokError.message : "unknown error");
+        const errMsg3 = firstError?.message ?? (grokError instanceof Error ? grokError.message : "unknown error");
         const fixPrompt = [
           "Your previous attempt did not produce a valid result file.",
-          `Error: ${errMsg2}`,
+          `Error: ${errMsg3}`,
           `Re-read BRIEF.md and write a valid SurveyorOutput JSON to ${resultFilePath}.`,
           "Single JSON object. No prose. Then exit."
         ].join("\n");
@@ -333080,7 +333545,7 @@ ${(0, inbox_tools_js_1.buildInboxAgentsGuidance)(inboxReg.email, inboxReg.passwo
           log2(`First-pass discovery-result invalid or missing: ${firstError.message}`);
         }
         if (!parsedResult) {
-          const errMsg2 = firstError?.message ?? (grokError instanceof Error ? grokError.message : "unknown error");
+          const errMsg3 = firstError?.message ?? (grokError instanceof Error ? grokError.message : "unknown error");
           if (planDebounceTimerRef.current) {
             clearTimeout(planDebounceTimerRef.current);
             planDebounceTimerRef.current = void 0;
@@ -333105,7 +333570,7 @@ ${(0, inbox_tools_js_1.buildInboxAgentsGuidance)(inboxReg.email, inboxReg.passwo
             ""
           ].join("\n");
           const fixPrompt = [
-            `Your previous attempt did not produce a valid result file. Error: ${errMsg2}`,
+            `Your previous attempt did not produce a valid result file. Error: ${errMsg3}`,
             "Re-read BRIEF.md.",
             phaseContext,
             `Continue from where you left off \u2014 already verified tests are in ${testsDirPath}/`,
@@ -334734,10 +335199,10 @@ ${(0, inbox_tools_js_1.buildInboxAgentsGuidance)(inboxReg.email, inboxReg.passwo
           onLog: parserLog,
           onProvenCommands: recordProvenCommands
         });
-        const errMsg2 = firstError?.message ?? (claudeError instanceof Error ? claudeError.message : "unknown error");
+        const errMsg3 = firstError?.message ?? (claudeError instanceof Error ? claudeError.message : "unknown error");
         const fixPrompt = [
           "Your previous attempt did not leave a valid result file.",
-          `Error: ${errMsg2}`,
+          `Error: ${errMsg3}`,
           `Writing a valid SurveyorOutput JSON object to ${resultFilePath} is your ONLY priority now.`,
           "Procedure: navigate to at most 6-8 of the main pages, then IMMEDIATELY use",
           `the Write tool to save the SurveyorOutput JSON to ${resultFilePath}. Do this`,
@@ -338618,8 +339083,8 @@ var require_resource_governor = __commonJS({
     function isDiscoveryLike(mode) {
       return mode === "discovery";
     }
-    function evaluateRunAdmission2(options, request) {
-      const snapshot = getResourceSnapshot2();
+    function evaluateRunAdmission2(options, request, snapshotOverride) {
+      const snapshot = snapshotOverride ?? getResourceSnapshot2();
       const candidateWeight = modeWeight(request.mode, options.weights);
       const currentUnits = activeUnits(request.activeByType, options.weights);
       const memory = pressureFactor(snapshot.memoryPct, options.memorySoftPct, options.memoryHardPct);
@@ -341117,8 +341582,8 @@ var require_adm_zip = __commonJS({
         return null;
       }
       function fixPath(zipPath) {
-        const { join: join7, normalize, sep } = pth.posix;
-        return join7(pth.isAbsolute(zipPath) ? "/" : ".", normalize(sep + zipPath.split("\\").join(sep) + sep));
+        const { join: join8, normalize, sep } = pth.posix;
+        return join8(pth.isAbsolute(zipPath) ? "/" : ".", normalize(sep + zipPath.split("\\").join(sep) + sep));
       }
       function filenameFilter(filterfn) {
         if (filterfn instanceof RegExp) {
@@ -343953,11 +344418,11 @@ var require_winchars = __commonJS({
 var require_strip_absolute_path = __commonJS({
   "../../node_modules/tar/lib/strip-absolute-path.js"(exports2, module2) {
     "use strict";
-    var { isAbsolute, parse } = require("path").win32;
+    var { isAbsolute: isAbsolute2, parse } = require("path").win32;
     module2.exports = (path) => {
       let r = "";
       let parsed = parse(path);
-      while (isAbsolute(path) || parsed.root) {
+      while (isAbsolute2(path) || parsed.root) {
         const root = path.charAt(0) === "/" && path.slice(0, 4) !== "//?/" ? "/" : parsed.root;
         path = path.slice(root.length);
         r += root;
@@ -346469,7 +346934,7 @@ var require_update = __commonJS({
 var require_opts_arg = __commonJS({
   "../../node_modules/tar/node_modules/mkdirp/lib/opts-arg.js"(exports2, module2) {
     "use strict";
-    var { promisify: promisify3 } = require("util");
+    var { promisify: promisify4 } = require("util");
     var fs = require("fs");
     var optsArg = (opts) => {
       if (!opts)
@@ -346483,9 +346948,9 @@ var require_opts_arg = __commonJS({
       else
         throw new TypeError("invalid options argument");
       opts.mkdir = opts.mkdir || opts.fs.mkdir || fs.mkdir;
-      opts.mkdirAsync = promisify3(opts.mkdir);
+      opts.mkdirAsync = promisify4(opts.mkdir);
       opts.stat = opts.stat || opts.fs.stat || fs.stat;
-      opts.statAsync = promisify3(opts.stat);
+      opts.statAsync = promisify4(opts.stat);
       opts.statSync = opts.statSync || opts.fs.statSync || fs.statSync;
       opts.mkdirSync = opts.mkdirSync || opts.fs.mkdirSync || fs.mkdirSync;
       return opts;
@@ -346738,10 +347203,10 @@ var require_chownr = __commonJS({
       }
     } : (path2, uid, gid) => lchownSync(path2, uid, gid);
     var nodeVersion = process.version;
-    var readdir2 = (path2, options, cb) => fs.readdir(path2, options, cb);
+    var readdir3 = (path2, options, cb) => fs.readdir(path2, options, cb);
     var readdirSync = (path2, options) => fs.readdirSync(path2, options);
     if (/^v4\./.test(nodeVersion))
-      readdir2 = (path2, options, cb) => fs.readdir(path2, cb);
+      readdir3 = (path2, options, cb) => fs.readdir(path2, cb);
     var chown = (cpath, uid, gid, cb) => {
       fs[LCHOWN](cpath, uid, gid, handleEISDIR(cpath, uid, gid, (er) => {
         cb(er && er.code !== "ENOENT" ? er : null);
@@ -346768,7 +347233,7 @@ var require_chownr = __commonJS({
       }
     };
     var chownr = (p, uid, gid, cb) => {
-      readdir2(p, { withFileTypes: true }, (er, children) => {
+      readdir3(p, { withFileTypes: true }, (er, children) => {
         if (er) {
           if (er.code === "ENOENT")
             return cb();
@@ -347042,7 +347507,7 @@ var require_path_reservations = __commonJS({
     var assert = require("assert");
     var normalize = require_normalize_unicode();
     var stripSlashes = require_strip_trailing_slashes();
-    var { join: join7 } = require("path");
+    var { join: join8 } = require("path");
     var platform3 = process.env.TESTING_TAR_FAKE_PLATFORM || process.platform;
     var isWindows = platform3 === "win32";
     module2.exports = () => {
@@ -347051,7 +347516,7 @@ var require_path_reservations = __commonJS({
       const getDirs = (path) => {
         const dirs = path.split("/").slice(0, -1).reduce((set, path2) => {
           if (set.length) {
-            path2 = join7(set[set.length - 1], path2);
+            path2 = join8(set[set.length - 1], path2);
           }
           set.push(path2 || "/");
           return set;
@@ -347119,7 +347584,7 @@ var require_path_reservations = __commonJS({
       };
       const reserve = (paths, fn) => {
         paths = isWindows ? ["win32 parallelization disabled"] : paths.map((p) => {
-          return stripSlashes(join7(normalize(p))).toLowerCase();
+          return stripSlashes(join8(normalize(p))).toLowerCase();
         });
         const dirs = new Set(
           paths.map((path) => getDirs(path)).reduce((a, b) => a.concat(b))
@@ -347174,7 +347639,7 @@ var require_unpack = __commonJS({
     var fs = require("fs");
     var fsm = require_fs_minipass();
     var path = require("path");
-    var mkdir2 = require_mkdir();
+    var mkdir3 = require_mkdir();
     var wc = require_winchars();
     var pathReservations = require_path_reservations();
     var stripAbsolutePath = require_strip_absolute_path();
@@ -347425,7 +347890,7 @@ var require_unpack = __commonJS({
         }
       }
       [MKDIR](dir, mode, cb) {
-        mkdir2(normPath(dir), {
+        mkdir3(normPath(dir), {
           uid: this.uid,
           gid: this.gid,
           processUid: this.processUid,
@@ -347828,7 +348293,7 @@ var require_unpack = __commonJS({
       }
       [MKDIR](dir, mode) {
         try {
-          return mkdir2.sync(normPath(dir), {
+          return mkdir3.sync(normPath(dir), {
             uid: this.uid,
             gid: this.gid,
             processUid: this.processUid,
@@ -351334,7 +351799,7 @@ var require_process_inventory = __commonJS({
     var node_child_process_1 = require("child_process");
     var node_os_1 = __importDefault(require("os"));
     var node_util_1 = require("util");
-    var execFileAsync3 = (0, node_util_1.promisify)(node_child_process_1.execFile);
+    var execFileAsync4 = (0, node_util_1.promisify)(node_child_process_1.execFile);
     var DEFAULT_LIMIT = 60;
     var DEFAULT_TIMEOUT_MS2 = 800;
     var MAX_COMMAND_LENGTH = 320;
@@ -351396,7 +351861,7 @@ var require_process_inventory = __commonJS({
       const timer = setTimeout(() => controller.abort(), timeoutMs);
       timer.unref?.();
       try {
-        const { stdout } = await execFileAsync3(command, args, {
+        const { stdout } = await execFileAsync4(command, args, {
           maxBuffer: 1024 * 1024,
           signal: controller.signal
         });
@@ -352542,7 +353007,7 @@ var require_package4 = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@validate.qa/runner",
-      version: "1.0.70",
+      version: "1.0.72",
       description: "validate local test runner - execute Playwright tests on your machine, connected to validate.qa cloud.",
       bin: {
         "validate-runner": "dist/cli.js"
@@ -352551,7 +353016,7 @@ var require_package4 = __commonJS({
         build: "tsup",
         dev: "tsx src/cli.ts",
         test: "node --import tsx --test src/version-check.test.ts src/services/auth-state.test.ts",
-        "test:mobile": "node --import tsx --test --test-concurrency=2 src/runner.mobile-ai-env.test.ts src/mobile-device-queue.test.ts src/device-lease.test.ts src/result-payload-budget.test.ts src/services/appium-*.test.ts src/services/*mobile*.test.ts src/services/mobile/*.test.ts",
+        "test:mobile": "node --import tsx --test --test-concurrency=2 src/runner.mobile-ai-env.test.ts src/mobile-device-queue.test.ts src/device-lease.test.ts src/runner-watchdog.test.ts src/result-payload-budget.test.ts src/services/appium-*.test.ts src/services/*mobile*.test.ts src/services/mobile/*.test.ts",
         prepublishOnly: "npm run build"
       },
       files: [
@@ -352629,7 +353094,7 @@ function getConfigDir() {
 }
 
 // src/runner.ts
-var import_path4 = require("path");
+var import_path5 = require("path");
 var import_os6 = require("os");
 var import_node_crypto2 = require("crypto");
 
@@ -353224,6 +353689,69 @@ function resetServerState(port = APPIUM_PORT, restartCount = 0) {
   };
 }
 
+// src/services/mobile/ios-simulator-reset.ts
+var import_child_process2 = require("child_process");
+var import_util = require("util");
+var import_promises = require("fs/promises");
+var import_path3 = require("path");
+var execFileAsync = (0, import_util.promisify)(import_child_process2.execFile);
+var SIMCTL_TIMEOUT_MS = 15e3;
+var SIMULATOR_UDID_RE = /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/i;
+function isIosSimulatorUdid(udid) {
+  return typeof udid === "string" && SIMULATOR_UDID_RE.test(udid.trim());
+}
+function errMsg(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+async function simctl(args) {
+  const { stdout } = await execFileAsync("xcrun", ["simctl", ...args], {
+    timeout: SIMCTL_TIMEOUT_MS,
+    encoding: "utf-8"
+  });
+  return stdout.trim();
+}
+async function clearIosSimulatorAppData(udid, bundleId, env = process.env) {
+  if (!isIosSimulatorUdid(udid)) {
+    return { ok: false, detail: `'${udid}' is not a simulator UDID \u2014 physical iOS devices cannot be cleared` };
+  }
+  let container;
+  try {
+    container = await simctl(["get_app_container", udid, bundleId, "data"]);
+  } catch (err) {
+    return { ok: false, detail: `simctl get_app_container failed (app not installed?): ${errMsg(err)}` };
+  }
+  if (!(0, import_path3.isAbsolute)(container) || !container.includes("/Containers/Data/Application/")) {
+    return { ok: false, detail: `unexpected app container path: ${container}` };
+  }
+  try {
+    await simctl(["spawn", udid, "defaults", "delete", bundleId]);
+  } catch {
+  }
+  try {
+    const entries = await (0, import_promises.readdir)(container);
+    for (const entry of entries) {
+      await (0, import_promises.rm)((0, import_path3.join)(container, entry), { recursive: true, force: true });
+    }
+    for (const dir of ["Documents", "Library/Caches", "Library/Preferences", "tmp"]) {
+      await (0, import_promises.mkdir)((0, import_path3.join)(container, dir), { recursive: true });
+    }
+  } catch (err) {
+    return { ok: false, detail: `app container wipe failed: ${errMsg(err)}` };
+  }
+  const keychainPolicy = (env.VALIDATEQA_MOBILE_IOS_KEYCHAIN_RESET ?? "").trim().toLowerCase();
+  if (keychainPolicy !== "never") {
+    try {
+      await simctl(["keychain", udid, "reset"]);
+    } catch (err) {
+      return {
+        ok: false,
+        detail: `simulator keychain reset failed (${errMsg(err)}) \u2014 app data was wiped but keychain items (e.g. auth tokens) may survive. Set VALIDATEQA_MOBILE_IOS_KEYCHAIN_RESET=never to skip the keychain step.`
+      };
+    }
+  }
+  return { ok: true };
+}
+
 // src/services/mobile/appium-actions.ts
 var APPIUM_REQUEST_TIMEOUT_MS = 1e4;
 var APPIUM_WEBVIEW_CONTEXT_TIMEOUT_MS = 12e4;
@@ -353406,9 +353934,12 @@ async function tapAt(sessionPath, bounds) {
   }
 }
 function shouldResetMobileAppData(platform3, deviceId, env = process.env) {
-  if (platform3 !== "ANDROID") return false;
   const policy = (env.VALIDATEQA_MOBILE_APP_RESET ?? "").trim().toLowerCase();
   if (policy === "never") return false;
+  if (platform3 === "IOS") {
+    return isIosSimulatorUdid(deviceId);
+  }
+  if (platform3 !== "ANDROID") return false;
   if (policy === "always") return true;
   return !!deviceId && deviceId.startsWith("emulator-");
 }
@@ -354287,6 +354818,45 @@ async function pressHome(sessionPath, platform3) {
   });
 }
 
+// src/services/device-quarantine.ts
+var QUARANTINE_MAX_MS = (() => {
+  const raw = Number(process.env.VALIDATEQA_DEVICE_QUARANTINE_MAX_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : 10 * 60 * 1e3;
+})();
+var quarantinedAt = /* @__PURE__ */ new Map();
+var DeviceQuarantinedError = class extends Error {
+  constructor(deviceId) {
+    super(
+      `Device ${deviceId} is quarantined: a previous run on it was force-released by the watchdog and has not settled yet. Refusing to open a new Appium session until it does.`
+    );
+    this.name = "DeviceQuarantinedError";
+  }
+};
+function quarantineDevice(deviceId, now = Date.now()) {
+  quarantinedAt.set(deviceId, now);
+}
+function unquarantineDevice(deviceId) {
+  quarantinedAt.delete(deviceId);
+}
+function isDeviceQuarantined(deviceId, now = Date.now()) {
+  if (typeof deviceId !== "string") return false;
+  const since = quarantinedAt.get(deviceId);
+  if (since === void 0) return false;
+  if (now - since >= QUARANTINE_MAX_MS) {
+    quarantinedAt.delete(deviceId);
+    console.warn(
+      `[device-quarantine] Quarantine on ${deviceId} exceeded its ${Math.round(QUARANTINE_MAX_MS / 6e4)}min ceiling without the original run settling \u2014 lifting it so the device is usable again. If this recurs, the zombie run is wedged in non-device work (check the runner log).`
+    );
+    return false;
+  }
+  return true;
+}
+function assertDeviceNotQuarantined(deviceId, now = Date.now()) {
+  if (isDeviceQuarantined(deviceId, now)) {
+    throw new DeviceQuarantinedError(deviceId);
+  }
+}
+
 // src/services/appium-executor.ts
 var import_node_child_process2 = require("child_process");
 var import_node_util2 = require("util");
@@ -354295,11 +354865,11 @@ var import_node_path2 = require("path");
 var import_runner_core8 = __toESM(require_dist2());
 
 // src/services/device-discovery.ts
-var import_child_process2 = require("child_process");
+var import_child_process3 = require("child_process");
 var import_os3 = require("os");
 function runCommand(command, args, timeout = 1e4) {
   try {
-    return (0, import_child_process2.execFileSync)(command, args, {
+    return (0, import_child_process3.execFileSync)(command, args, {
       encoding: "utf-8",
       timeout,
       stdio: ["pipe", "pipe", "pipe"]
@@ -354599,9 +355169,6 @@ function countReadyDevicesByKind(platform3, snapshot = getCachedDeviceSnapshot()
 function selectFreeDevice(platform3, leased, snapshot = getCachedDeviceSnapshot(), requirements = {}) {
   const ready = snapshot.filter((d) => d.platform === platform3 && d.isAvailable && d.state === "BOOTED");
   if (ready.length === 0) return { kind: "busy", reason: `no booted ${platform3} device` };
-  if (requirements.resetPolicy === "CLEAR_APP_DATA" && platform3 !== "ANDROID") {
-    return { kind: "unsatisfiable", reason: "CLEAR_APP_DATA is unsupported on iOS" };
-  }
   let candidates = requirements.resetPolicy === "CLEAR_APP_DATA" ? ready.filter((d) => !d.isPhysical) : [...ready];
   const appId = requirements.appId?.trim();
   if (appId) {
@@ -354651,13 +355218,13 @@ function pickFreeDevice(platform3, leased, snapshot = getCachedDeviceSnapshot(),
 // src/services/mobile/mobile-network-capture.ts
 var import_node_child_process = require("child_process");
 var import_node_crypto = require("crypto");
-var import_promises = require("fs/promises");
+var import_promises2 = require("fs/promises");
 var import_node_os = require("os");
 var import_node_path = require("path");
 var import_node_util = require("util");
 var import_mockttp = require("mockttp");
 var import_runner_core7 = __toESM(require_dist2());
-var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
+var execFileAsync2 = (0, import_node_util.promisify)(import_node_child_process.execFile);
 var MAX_CALLS = 1e3;
 var MAX_BODY_CAPTURE_BYTES = 64 * 1024;
 var DEVICE_CMD_TIMEOUT_MS = 15e3;
@@ -354845,7 +355412,7 @@ var MitmProxy = class {
     try {
       await server3.stop();
     } catch (err) {
-      this.onLog?.(`[mobile-net] proxy stop error (ignored): ${errMsg(err)}`);
+      this.onLog?.(`[mobile-net] proxy stop error (ignored): ${errMsg2(err)}`);
     }
     this.onLog?.(
       `[mobile-net] proxy closed: ${this.calls.length} calls captured` + (this.dropped > 0 ? ` (${this.dropped} dropped over cap)` : "")
@@ -354870,7 +355437,7 @@ var MitmProxy = class {
         isHttps
       });
     } catch (err) {
-      this.onLog?.(`[mobile-net] request capture error (ignored): ${errMsg(err)}`);
+      this.onLog?.(`[mobile-net] request capture error (ignored): ${errMsg2(err)}`);
     }
   }
   // ── response → finalize the matched request ───────────────────────────────
@@ -354913,7 +355480,7 @@ var MitmProxy = class {
         intercepted: true
       });
     } catch (err) {
-      this.onLog?.(`[mobile-net] response capture error (ignored): ${errMsg(err)}`);
+      this.onLog?.(`[mobile-net] response capture error (ignored): ${errMsg2(err)}`);
     }
   }
   // ── tls-client-error → record WHY interception failed ─────────────────────
@@ -354991,16 +355558,16 @@ async function generateCaCert(dir, onLog) {
       // rather than on a short expiry.
     });
     const caCertPath = (0, import_node_path.join)(dir, "validateqa-mobile-ca.pem");
-    await (0, import_promises.writeFile)(caCertPath, cert, "utf-8");
+    await (0, import_promises2.writeFile)(caCertPath, cert, "utf-8");
     return { caCertPath, caKeyPem: key, caCertPem: cert };
   } catch (err) {
-    onLog?.(`[mobile-net] CA generation failed; running plaintext-only: ${errMsg(err)}`);
+    onLog?.(`[mobile-net] CA generation failed; running plaintext-only: ${errMsg2(err)}`);
     return null;
   }
 }
 async function androidReadProxy(deviceId) {
   try {
-    const { stdout } = await execFileAsync(
+    const { stdout } = await execFileAsync2(
       "adb",
       ["-s", deviceId, "shell", "settings", "get", "global", "http_proxy"],
       { timeout: DEVICE_CMD_TIMEOUT_MS }
@@ -355013,33 +355580,33 @@ async function androidReadProxy(deviceId) {
 }
 async function androidSetProxy(deviceId, hostPort, onLog) {
   try {
-    await execFileAsync(
+    await execFileAsync2(
       "adb",
       ["-s", deviceId, "shell", "settings", "put", "global", "http_proxy", hostPort],
       { timeout: DEVICE_CMD_TIMEOUT_MS }
     );
     return true;
   } catch (err) {
-    onLog?.(`[mobile-net] adb set http_proxy failed: ${errMsg(err)}`);
+    onLog?.(`[mobile-net] adb set http_proxy failed: ${errMsg2(err)}`);
     return false;
   }
 }
 async function androidClearProxy(deviceId, originalProxy, onLog) {
   const restoreValue = originalProxy && originalProxy.length > 0 ? originalProxy : ":0";
   try {
-    await execFileAsync(
+    await execFileAsync2(
       "adb",
       ["-s", deviceId, "shell", "settings", "put", "global", "http_proxy", restoreValue],
       { timeout: DEVICE_CMD_TIMEOUT_MS }
     );
   } catch (err) {
-    onLog?.(`[mobile-net] adb restore http_proxy failed: ${errMsg(err)}`);
+    onLog?.(`[mobile-net] adb restore http_proxy failed: ${errMsg2(err)}`);
   }
 }
 async function androidInstallCa(deviceId, caCertPath) {
   const devicePath = "/sdcard/validateqa-mobile-ca.pem";
   try {
-    await execFileAsync("adb", ["-s", deviceId, "push", caCertPath, devicePath], {
+    await execFileAsync2("adb", ["-s", deviceId, "push", caCertPath, devicePath], {
       timeout: DEVICE_CMD_TIMEOUT_MS
     });
     return {
@@ -355047,23 +355614,23 @@ async function androidInstallCa(deviceId, caCertPath) {
       note: `CA copied from ${caCertPath} to ${devicePath} but NOT auto-trusted: Android 7+ apps must opt into user CAs (network_security_config), and the system store requires a rooted/writable image. HTTPS bodies decrypt only for apps that trust user CAs; pinned apps never decrypt.`
     };
   } catch (err) {
-    return { installed: false, note: `CA push failed: ${errMsg(err)}` };
+    return { installed: false, note: `CA push failed: ${errMsg2(err)}` };
   }
 }
 async function androidRemoveCa(deviceId, onLog) {
   try {
-    await execFileAsync(
+    await execFileAsync2(
       "adb",
       ["-s", deviceId, "shell", "rm", "-f", "/sdcard/validateqa-mobile-ca.pem"],
       { timeout: DEVICE_CMD_TIMEOUT_MS }
     );
   } catch (err) {
-    onLog?.(`[mobile-net] adb remove CA failed: ${errMsg(err)}`);
+    onLog?.(`[mobile-net] adb remove CA failed: ${errMsg2(err)}`);
   }
 }
 async function iosSimTrustCa(deviceId, caCertPath) {
   try {
-    await execFileAsync("xcrun", ["simctl", "keychain", deviceId, "add-root-cert", caCertPath], {
+    await execFileAsync2("xcrun", ["simctl", "keychain", deviceId, "add-root-cert", caCertPath], {
       timeout: DEVICE_CMD_TIMEOUT_MS
     });
     return {
@@ -355071,18 +355638,18 @@ async function iosSimTrustCa(deviceId, caCertPath) {
       note: "CA added to simulator keychain (add-root-cert). NOTE: the simulator has no per-app HTTP proxy setting controllable via simctl \u2014 it shares the host network, so only traffic that actually routes through the proxy is intercepted; pinned apps still never decrypt."
     };
   } catch (err) {
-    return { trusted: false, note: `simctl add-root-cert failed: ${errMsg(err)}` };
+    return { trusted: false, note: `simctl add-root-cert failed: ${errMsg2(err)}` };
   }
 }
 async function iosSimRemoveCa(deviceId, onLog) {
   if (process.env.VALIDATEQA_MOBILE_SIM_KEYCHAIN_RESET === "1") {
     try {
-      await execFileAsync("xcrun", ["simctl", "keychain", deviceId, "reset"], {
+      await execFileAsync2("xcrun", ["simctl", "keychain", deviceId, "reset"], {
         timeout: DEVICE_CMD_TIMEOUT_MS
       });
       onLog?.(`[mobile-net] simctl keychain reset run for ${deviceId} (opt-in; cleared ALL sim certs).`);
     } catch (err) {
-      onLog?.(`[mobile-net] simctl keychain reset failed: ${errMsg(err)}`);
+      onLog?.(`[mobile-net] simctl keychain reset failed: ${errMsg2(err)}`);
     }
     return;
   }
@@ -355090,7 +355657,7 @@ async function iosSimRemoveCa(deviceId, onLog) {
     `[mobile-net] NOTE: the validate.qa capture CA remains TRUSTED in simulator ${deviceId}. simctl has no scoped remove (only a full keychain reset that wipes ALL certs), so we leave the single CA in place. Use a throwaway simulator, or set VALIDATEQA_MOBILE_SIM_KEYCHAIN_RESET=1 to reset the whole sim keychain on teardown.`
   );
 }
-function errMsg(err) {
+function errMsg2(err) {
   return err instanceof Error ? err.message : String(err);
 }
 function isProcessAlive(pid) {
@@ -355181,7 +355748,7 @@ async function iosSimConfigureHostProxy(host, port, onLog) {
   let service;
   let prior;
   try {
-    const { stdout: order } = await execFileAsync("networksetup", ["-listnetworkserviceorder"], {
+    const { stdout: order } = await execFileAsync2("networksetup", ["-listnetworkserviceorder"], {
       timeout: DEVICE_CMD_TIMEOUT_MS
     });
     const svc = parsePrimaryNetworkService(order);
@@ -355190,26 +355757,26 @@ async function iosSimConfigureHostProxy(host, port, onLog) {
     }
     service = svc;
     const [{ stdout: webOut }, { stdout: secureOut }] = await Promise.all([
-      execFileAsync("networksetup", ["-getwebproxy", service], { timeout: DEVICE_CMD_TIMEOUT_MS }),
-      execFileAsync("networksetup", ["-getsecurewebproxy", service], { timeout: DEVICE_CMD_TIMEOUT_MS })
+      execFileAsync2("networksetup", ["-getwebproxy", service], { timeout: DEVICE_CMD_TIMEOUT_MS }),
+      execFileAsync2("networksetup", ["-getsecurewebproxy", service], { timeout: DEVICE_CMD_TIMEOUT_MS })
     ]);
     prior = { web: parseWebProxyState(webOut), secure: parseWebProxyState(secureOut) };
     for (const args of buildHostProxySetCommands(service, host, port)) {
-      await execFileAsync("networksetup", args, { timeout: DEVICE_CMD_TIMEOUT_MS });
+      await execFileAsync2("networksetup", args, { timeout: DEVICE_CMD_TIMEOUT_MS });
     }
     onLog?.(`[mobile-net] macOS host proxy set on "${service}" \u2192 ${host}:${port} (iOS simulator shares the host network).`);
     return { configured: true, service, prior };
   } catch (err) {
     if (service && prior) {
-      onLog?.(`[mobile-net] host proxy set failed mid-way \u2014 rolling back "${service}" to prior state: ${errMsg(err)}`);
+      onLog?.(`[mobile-net] host proxy set failed mid-way \u2014 rolling back "${service}" to prior state: ${errMsg2(err)}`);
       for (const args of buildHostProxyRestoreCommands(service, prior)) {
         try {
-          await execFileAsync("networksetup", args, { timeout: DEVICE_CMD_TIMEOUT_MS });
+          await execFileAsync2("networksetup", args, { timeout: DEVICE_CMD_TIMEOUT_MS });
         } catch {
         }
       }
     }
-    return { configured: false, reason: `iOS simulator host proxy could not be configured: ${errMsg(err)}` };
+    return { configured: false, reason: `iOS simulator host proxy could not be configured: ${errMsg2(err)}` };
   }
 }
 async function iosSimRestoreHostProxy(service, prior, onLog) {
@@ -355219,9 +355786,9 @@ async function iosSimRestoreHostProxy(service, prior, onLog) {
   };
   for (const args of buildHostProxyRestoreCommands(service, restore)) {
     try {
-      await execFileAsync("networksetup", args, { timeout: DEVICE_CMD_TIMEOUT_MS });
+      await execFileAsync2("networksetup", args, { timeout: DEVICE_CMD_TIMEOUT_MS });
     } catch (err) {
-      onLog?.(`[mobile-net] networksetup restore (${args[0]}) failed: ${errMsg(err)}`);
+      onLog?.(`[mobile-net] networksetup restore (${args[0]}) failed: ${errMsg2(err)}`);
     }
   }
   onLog?.(`[mobile-net] macOS host proxy restored on "${service}".`);
@@ -355233,14 +355800,14 @@ function markerPath(sessionKey) {
 }
 async function writePendingCleanup(sessionKey, marker) {
   try {
-    await (0, import_promises.mkdir)(PENDING_CLEANUP_DIR, { recursive: true });
-    await (0, import_promises.writeFile)(markerPath(sessionKey), JSON.stringify(marker), "utf-8");
+    await (0, import_promises2.mkdir)(PENDING_CLEANUP_DIR, { recursive: true });
+    await (0, import_promises2.writeFile)(markerPath(sessionKey), JSON.stringify(marker), "utf-8");
   } catch {
   }
 }
 async function removePendingCleanup(sessionKey) {
   try {
-    await (0, import_promises.unlink)(markerPath(sessionKey));
+    await (0, import_promises2.unlink)(markerPath(sessionKey));
   } catch {
   }
 }
@@ -355273,7 +355840,7 @@ function restoreDeviceSync(marker, onLog) {
 async function reconcilePendingCleanups(onLog) {
   let files;
   try {
-    files = await (0, import_promises.readdir)(PENDING_CLEANUP_DIR);
+    files = await (0, import_promises2.readdir)(PENDING_CLEANUP_DIR);
   } catch {
     return;
   }
@@ -355283,7 +355850,7 @@ async function reconcilePendingCleanups(onLog) {
     if (activeCleanups.has(sessionKey)) continue;
     const full = (0, import_node_path.join)(PENDING_CLEANUP_DIR, file);
     try {
-      const raw = await (0, import_promises.readFile)(full, "utf-8");
+      const raw = await (0, import_promises2.readFile)(full, "utf-8");
       const marker = JSON.parse(raw);
       if (marker && typeof marker.deviceId === "string" && marker.platform) {
         if (!shouldReconcilePendingCleanup(marker)) {
@@ -355296,7 +355863,7 @@ async function reconcilePendingCleanups(onLog) {
     } catch {
     }
     try {
-      await (0, import_promises.unlink)(full);
+      await (0, import_promises2.unlink)(full);
     } catch {
     }
   }
@@ -355334,7 +355901,7 @@ async function startMobileNetworkCapture(options) {
   let caKeyPem = null;
   let caCertPem = null;
   try {
-    tmpDir = await (0, import_promises.mkdtemp)((0, import_node_path.join)((0, import_node_os.tmpdir)(), "validateqa-mobile-ca-"));
+    tmpDir = await (0, import_promises2.mkdtemp)((0, import_node_path.join)((0, import_node_os.tmpdir)(), "validateqa-mobile-ca-"));
     const ca = await generateCaCert(tmpDir, onLog);
     if (ca) {
       caCertPath = ca.caCertPath;
@@ -355342,7 +355909,7 @@ async function startMobileNetworkCapture(options) {
       caCertPem = ca.caCertPem;
     }
   } catch (err) {
-    onLog?.(`[mobile-net] CA setup degraded: ${errMsg(err)}`);
+    onLog?.(`[mobile-net] CA setup degraded: ${errMsg2(err)}`);
   }
   if (!caKeyPem || !caCertPem) {
     try {
@@ -355350,9 +355917,9 @@ async function startMobileNetworkCapture(options) {
       caKeyPem = fallback.key;
       caCertPem = fallback.cert;
     } catch (err) {
-      onLog?.(`[mobile-net] fatal CA failure, cannot start proxy: ${errMsg(err)}`);
+      onLog?.(`[mobile-net] fatal CA failure, cannot start proxy: ${errMsg2(err)}`);
       if (tmpDir) {
-        await (0, import_promises.rm)(tmpDir, { recursive: true, force: true }).catch(() => void 0);
+        await (0, import_promises2.rm)(tmpDir, { recursive: true, force: true }).catch(() => void 0);
       }
       throw err instanceof Error ? err : new Error(String(err));
     }
@@ -355407,7 +355974,7 @@ async function startMobileNetworkCapture(options) {
       }
     }
   } catch (err) {
-    wiringReason = `device wiring degraded: ${errMsg(err)}`;
+    wiringReason = `device wiring degraded: ${errMsg2(err)}`;
     onLog?.(`[mobile-net] ${wiringReason}`);
   }
   if (proxySet || caInstalledOnDevice || hostProxySet) {
@@ -355496,9 +356063,9 @@ async function startMobileNetworkCapture(options) {
       await proxy.close();
       if (capturedTmpDir) {
         try {
-          await (0, import_promises.rm)(capturedTmpDir, { recursive: true, force: true });
+          await (0, import_promises2.rm)(capturedTmpDir, { recursive: true, force: true });
         } catch (err) {
-          onLog?.(`[mobile-net] temp CA cleanup failed: ${errMsg(err)}`);
+          onLog?.(`[mobile-net] temp CA cleanup failed: ${errMsg2(err)}`);
         }
       }
       const apiCount = finalCalls.filter((c) => c.isApi).length;
@@ -355531,11 +356098,11 @@ var MOBILE_NEW_COMMAND_TIMEOUT_SECONDS = (() => {
 })();
 var COLD_BOOT_ENTRY_TIMEOUT_MS = 3e4;
 var VERIFICATION_ACTIONS = /* @__PURE__ */ new Set(["assertVisible", "assertText", "waitForElement"]);
-var WD_SESSION_CREATE_TIMEOUT_MS = 12e4;
+var WD_SESSION_CREATE_TIMEOUT_MS = Number(process.env.VALIDATEQA_WD_SESSION_CREATE_TIMEOUT_MS) || 3e5;
 var WD_ACTION_TIMEOUT_MS = 3e4;
 var APPIUM_DRIVER_DEAD_RE2 = /instrumentation process is not running|cannot be proxied to UiAutomator2 server|socket hang up|ECONNRESET/i;
 var MAX_SESSION_CREATE_ATTEMPTS = 3;
-var execFileAsync2 = (0, import_node_util2.promisify)(import_node_child_process2.execFile);
+var execFileAsync3 = (0, import_node_util2.promisify)(import_node_child_process2.execFile);
 var MOBILE_TEXT_ATTRIBUTE_NAMES = ["text", "content-desc", "contentDescription", "name", "label", "value"];
 var WebDriverTransportError = class extends Error {
   isTransport = true;
@@ -355547,6 +356114,13 @@ var WebDriverTransportError = class extends Error {
 function isTransportError(err) {
   return err instanceof WebDriverTransportError || typeof err === "object" && err !== null && err.isTransport === true;
 }
+var MobileAmbiguousMatchError = class extends Error {
+  isAmbiguousMatch = true;
+  constructor(message) {
+    super(message);
+    this.name = "MobileAmbiguousMatchError";
+  }
+};
 function crossPlatformRunReadinessError(steps, authoringPlatform, runPlatform) {
   if (!authoringPlatform || authoringPlatform === runPlatform) return null;
   const missing = stepsMissingPlatformLocators(steps, runPlatform);
@@ -355692,6 +356266,7 @@ function androidSystemPortForwardRemovalArgs(target, error2, env = process.env)
   return ["-s", deviceId, "forward", "--remove", `tcp:${systemPort}`];
 }
 async function createSession(target) {
+  assertDeviceNotQuarantined(target.deviceId);
   const realCaps = target.isPhysical ? realDeviceCapabilities(target.platform) : {};
   const parallelCaps = mobileParallelSessionCapabilities(
     target.platform,
@@ -355713,6 +356288,13 @@ async function createSession(target) {
     // whole survey. The runner owns session teardown explicitly, so a long
     // idle window is safe. Env-overridable.
     "appium:newCommandTimeout": MOBILE_NEW_COMMAND_TIMEOUT_SECONDS,
+    // Xcode 27+ relocates Simulator.app out of <DEVELOPER_DIR>/Applications, so
+    // XCUITest's default "open Simulator UI" step fails ("Simulator.app does not
+    // exist") on this toolchain. The simulator is already booted and driven
+    // headlessly via CoreSimulator, so tell XCUITest to skip opening the GUI.
+    // Scoped to simulator UDIDs (a physical iOS device has no such step);
+    // override with APPIUM_IOS_HEADLESS=false to force a visible Simulator run.
+    ...isIosSimulatorUdid(target.deviceId) && process.env.APPIUM_IOS_HEADLESS !== "false" ? { "appium:isHeadless": true } : {},
     ...parallelCaps,
     ...realCaps
   } : {
@@ -355752,7 +356334,7 @@ async function removeStaleAndroidSystemPortForward(target, error2) {
   const args = androidSystemPortForwardRemovalArgs(target, error2);
   if (!args) return false;
   try {
-    await execFileAsync2("adb", args, { timeout: 1e4, windowsHide: true });
+    await execFileAsync3("adb", args, { timeout: 1e4, windowsHide: true });
     return true;
   } catch {
     return false;
@@ -355919,6 +356501,9 @@ async function deleteSession(sessionId) {
   } catch {
   }
 }
+async function deleteAppiumSession(sessionId) {
+  await deleteSession(sessionId);
+}
 async function takeScreenshot(sessionId) {
   try {
     const result = await wdRequest(`/session/${sessionId}/screenshot`);
@@ -355990,10 +356575,9 @@ async function stopScreenRecording(sessionId, log2) {
     return void 0;
   }
 }
-function boundsFromStep(step) {
-  const bounds = step.metadata?.bounds;
-  if (bounds && typeof bounds === "object" && !Array.isArray(bounds) && typeof bounds.x === "number" && typeof bounds.y === "number" && typeof bounds.width === "number" && typeof bounds.height === "number") {
-    const parsed = bounds;
+function parseMobileBoundsLike(value) {
+  if (value && typeof value === "object" && !Array.isArray(value) && typeof value.x === "number" && typeof value.y === "number" && typeof value.width === "number" && typeof value.height === "number") {
+    const parsed = value;
     if ([parsed.x, parsed.y, parsed.width, parsed.height].every(Number.isFinite)) {
       return {
         x: parsed.x,
@@ -356005,6 +356589,9 @@ function boundsFromStep(step) {
   }
   return null;
 }
+function boundsFromStep(step) {
+  return parseMobileBoundsLike(step.metadata?.bounds);
+}
 function boundsForRun(step, platform3, isCrossPlatform) {
   if (isCrossPlatform) return null;
   if (platform3 && hasPlatformLocator(step.target, platform3)) return null;
@@ -356156,6 +356743,131 @@ async function revealLikelyOffscreenElement(sessionId) {
   });
   await new Promise((resolve2) => setTimeout(resolve2, 250));
 }
+function strictMatchMode() {
+  const raw = (process.env.VALIDATEQA_MOBILE_STRICT_MATCH ?? "").trim().toLowerCase();
+  if (raw === "strict") return "strict";
+  if (raw === "off") return "off";
+  return "lenient";
+}
+var MOBILE_MAX_DISAMBIG_CANDIDATES = 20;
+var COINCIDENT_CENTER_EPSILON_PX = 2;
+function isRealElementRect(rect) {
+  return rect.width > 1 && rect.height > 1;
+}
+function rectContainsPoint(rect, x, y) {
+  return x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height;
+}
+function rectCenter(rect) {
+  return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+}
+function centerDistance(rect, point) {
+  const center = rectCenter(rect);
+  return Math.hypot(center.x - point.x, center.y - point.y);
+}
+function chooseRecordedMatch(candidates, opts) {
+  if (candidates.length === 0) return { kind: "ambiguous", count: 0 };
+  if (candidates.length === 1) {
+    return { kind: "matched", elementId: candidates[0].elementId, reason: "single" };
+  }
+  if (typeof opts.matchIndex === "number" && Number.isInteger(opts.matchIndex) && opts.matchIndex >= 0 && opts.matchIndex < candidates.length && typeof opts.expectedMatchCount === "number" && opts.expectedMatchCount === candidates.length) {
+    return { kind: "matched", elementId: candidates[opts.matchIndex].elementId, reason: "matchIndex" };
+  }
+  {
+    const withRect = candidates.filter(
+      (candidate) => candidate.rect != null
+    );
+    if (withRect.length === candidates.length) {
+      const real = withRect.filter((candidate) => isRealElementRect(candidate.rect));
+      if (real.length === 1) {
+        return { kind: "matched", elementId: real[0].elementId, reason: "visible" };
+      }
+      const centers = withRect.map((candidate) => rectCenter(candidate.rect));
+      const coincident = centers.every((center) => Math.abs(center.x - centers[0].x) <= COINCIDENT_CENTER_EPSILON_PX && Math.abs(center.y - centers[0].y) <= COINCIDENT_CENTER_EPSILON_PX);
+      if (coincident) {
+        return { kind: "matched", elementId: withRect[0].elementId, reason: "coincident" };
+      }
+    }
+  }
+  if (opts.recordedBounds) {
+    const bounds = opts.recordedBounds;
+    const center = rectCenter(bounds);
+    const withRect = candidates.filter(
+      (candidate) => candidate.rect != null
+    );
+    const containing = withRect.filter((candidate) => rectContainsPoint(candidate.rect, center.x, center.y));
+    if (containing.length > 0) {
+      const best = [...containing].sort(
+        (a, b) => a.rect.width * a.rect.height - b.rect.width * b.rect.height || centerDistance(a.rect, center) - centerDistance(b.rect, center)
+      )[0];
+      return { kind: "matched", elementId: best.elementId, reason: "bounds" };
+    }
+    if (withRect.length > 0) {
+      const tolerance = Math.max(bounds.height, 1);
+      const nearest = [...withRect].sort(
+        (a, b) => centerDistance(a.rect, center) - centerDistance(b.rect, center)
+      )[0];
+      if (centerDistance(nearest.rect, center) <= tolerance) {
+        return { kind: "matched", elementId: nearest.elementId, reason: "bounds" };
+      }
+    }
+  }
+  return opts.strict === "strict" ? { kind: "ambiguous", count: candidates.length } : { kind: "fallback", elementId: candidates[0].elementId, count: candidates.length };
+}
+function extractElementIdsFromPluralResponse(result) {
+  const rawList = result?.value;
+  if (!Array.isArray(rawList)) return [];
+  const ids = [];
+  for (const entry of rawList) {
+    const record = entry;
+    const id = validateElementId(record?.ELEMENT ?? record?.["element-6066-11e4-a52e-4f735466cecf"]);
+    if (id) ids.push(id);
+  }
+  return ids;
+}
+async function findElements(sessionId, strategy) {
+  const result = await wdRequest(`/session/${sessionId}/elements`, {
+    method: "POST",
+    body: JSON.stringify({ using: strategy.using, value: strategy.value })
+  });
+  return extractElementIdsFromPluralResponse(result);
+}
+async function findWebViewElements(sessionPath, css) {
+  const result = await wdRequest(`${sessionPath}/elements`, {
+    method: "POST",
+    body: JSON.stringify({ using: "css selector", value: css })
+  });
+  return extractElementIdsFromPluralResponse(result);
+}
+async function readElementRect(sessionId, elementId) {
+  try {
+    const result = await wdRequest(`/session/${sessionId}/element/${elementId}/rect`);
+    return parseMobileBoundsLike(result?.value);
+  } catch (err) {
+    if (isTransportError(err)) throw err;
+    return null;
+  }
+}
+async function disambiguateElementIds(sessionId, candidateIds, opts) {
+  const indexOnly = candidateIds.map((elementId) => ({ elementId }));
+  const indexResult = chooseRecordedMatch(indexOnly, {
+    recordedBounds: null,
+    matchIndex: opts.matchIndex,
+    expectedMatchCount: opts.expectedMatchCount,
+    strict: opts.strict
+  });
+  if (indexResult.kind === "matched" || candidateIds.length > MOBILE_MAX_DISAMBIG_CANDIDATES) {
+    return indexResult;
+  }
+  const withRects = await Promise.all(
+    candidateIds.map(async (elementId) => ({ elementId, rect: await readElementRect(sessionId, elementId) }))
+  );
+  return chooseRecordedMatch(withRects, {
+    recordedBounds: opts.recordedBounds ?? null,
+    matchIndex: opts.matchIndex,
+    expectedMatchCount: opts.expectedMatchCount,
+    strict: opts.strict
+  });
+}
 async function findElement(sessionId, target, timeoutMs = DEFAULT_STEP_TIMEOUT_MS, opts) {
   const strategies = opts?.identityOnly ? buildIdentityLocatorStrategies(target, opts?.platform) : buildLocatorStrategies(target, opts?.platform);
   if (strategies.length === 0) {
@@ -356163,22 +356875,45 @@ async function findElement(sessionId, target, timeoutMs = DEFAULT_STEP_TIMEOUT_M
       opts?.identityOnly ? "No identity locator (accessibility id / resource id / text) available for this step \u2014 cannot verify the screen" : "No locator strategies available for this step"
     );
   }
+  const mode = strictMatchMode();
+  const matchIndex = typeof target?.matchIndex === "number" ? target.matchIndex : void 0;
+  const expectedMatchCount = typeof target?.expectedMatchCount === "number" ? target.expectedMatchCount : void 0;
   const startTime = Date.now();
   let lastError = "";
+  let lastAmbiguity = null;
   let revealAttempted = false;
   while (Date.now() - startTime < timeoutMs) {
     for (const strategy of strategies) {
       try {
-        const result = await wdRequest(`/session/${sessionId}/element`, {
-          method: "POST",
-          body: JSON.stringify({ using: strategy.using, value: strategy.value })
+        const ids = await findElements(sessionId, strategy);
+        if (ids.length === 0) continue;
+        if (ids.length === 1 || opts?.disambiguate === false || mode === "off") {
+          return ids[0];
+        }
+        const result = await disambiguateElementIds(sessionId, ids, {
+          recordedBounds: opts?.recordedBounds,
+          matchIndex,
+          expectedMatchCount,
+          strict: mode
         });
-        const elementId = validateElementId(
-          result?.value?.ELEMENT || result?.value?.["element-6066-11e4-a52e-4f735466cecf"]
+        if (result.kind === "matched") return result.elementId;
+        const shouldFailClosed = opts?.failClosedOnAmbiguity || result.kind === "ambiguous" && !opts?.tolerateAmbiguity;
+        if (shouldFailClosed) {
+          throw new MobileAmbiguousMatchError(
+            `ambiguous locator: ${result.count} matches, cannot identify the recorded instance (strategy=${strategy.using} value=${strategy.value})`
+          );
+        }
+        opts?.log?.(
+          `\u26A0 ambiguous locator (${result.count} matches for strategy=${strategy.using} value=${strategy.value}) \u2014 using the first match. Set VALIDATEQA_MOBILE_STRICT_MATCH=strict to fail instead.`
         );
-        if (elementId) return elementId;
+        return result.kind === "ambiguous" ? ids[0] : result.elementId;
       } catch (err) {
         if (isTransportError(err)) throw err;
+        if (err instanceof MobileAmbiguousMatchError) {
+          lastAmbiguity = err;
+          lastError = err.message;
+          continue;
+        }
         lastError = err instanceof Error ? err.message : String(err);
       }
     }
@@ -356193,6 +356928,7 @@ async function findElement(sessionId, target, timeoutMs = DEFAULT_STEP_TIMEOUT_M
     }
     await new Promise((resolve2) => setTimeout(resolve2, 500));
   }
+  if (lastAmbiguity) throw lastAmbiguity;
   throw new Error(`Element not found after ${timeoutMs}ms. Tried ${strategies.length} strategies${revealAttempted ? " plus one reveal scroll" : ""}. Last error: ${lastError}`);
 }
 async function tapCoordinates(sessionId, bounds) {
@@ -356226,7 +356962,7 @@ async function prepareAndroidInputEnvironment(deviceId) {
   ];
   for (const [namespace, key, value] of settingsToDisable) {
     try {
-      await execFileAsync2("adb", ["-s", deviceId, "shell", "settings", "put", namespace, key, value], {
+      await execFileAsync3("adb", ["-s", deviceId, "shell", "settings", "put", namespace, key, value], {
         timeout: 8e3,
         windowsHide: true
       });
@@ -356238,14 +356974,14 @@ async function sendAndroidTextToFocusedInput(deviceId, value) {
   if (!deviceId) {
     throw new Error("Android keyboard fallback requires a device id");
   }
-  await execFileAsync2("adb", ["-s", deviceId, "shell", "input", "text", encodeAndroidInputText(value)], {
+  await execFileAsync3("adb", ["-s", deviceId, "shell", "input", "text", encodeAndroidInputText(value)], {
     timeout: 1e4,
     windowsHide: true
   });
 }
 async function pressAndroidKeyboardEnter(deviceId) {
   if (!deviceId) throw new Error("Android keyboard Enter fallback requires a device id");
-  await execFileAsync2("adb", ["-s", deviceId, "shell", "input", "keyevent", "66"], {
+  await execFileAsync3("adb", ["-s", deviceId, "shell", "input", "keyevent", "66"], {
     timeout: 1e4,
     windowsHide: true
   });
@@ -356333,21 +357069,40 @@ async function executeInWebViewContext(sessionId, step, css, body) {
   const cleanCss = css.startsWith("css=") ? css.slice(4) : css;
   await withWebViewContext(sessionPath, webview, () => body(sessionPath, cleanCss));
 }
-async function findWebViewElement(sessionPath, css, timeoutMs = DEFAULT_STEP_TIMEOUT_MS) {
+async function findWebViewElement(sessionPath, css, timeoutMs = DEFAULT_STEP_TIMEOUT_MS, opts) {
+  const mode = strictMatchMode();
   const startedAt = Date.now();
   let lastError = "";
   while (Date.now() - startedAt < timeoutMs) {
     try {
-      const result = await wdRequest(`${sessionPath}/element`, {
-        method: "POST",
-        body: JSON.stringify({ using: "css selector", value: css })
-      });
-      const elementId = validateElementId(
-        result?.value?.ELEMENT || result?.value?.["element-6066-11e4-a52e-4f735466cecf"]
-      );
-      if (elementId) return elementId;
+      const ids = await findWebViewElements(sessionPath, css);
+      if (ids.length === 0) {
+        lastError = `no match for css=${css}`;
+      } else if (ids.length === 1 || opts?.disambiguate === false || mode === "off") {
+        return ids[0];
+      } else {
+        const candidates = ids.map((elementId) => ({ elementId }));
+        const result = chooseRecordedMatch(candidates, {
+          recordedBounds: null,
+          matchIndex: opts?.matchIndex,
+          expectedMatchCount: opts?.expectedMatchCount,
+          strict: mode
+        });
+        if (result.kind === "matched") {
+          return result.elementId;
+        }
+        if (result.kind === "ambiguous" && !opts?.tolerateAmbiguity) {
+          throw new MobileAmbiguousMatchError(
+            `ambiguous WEBVIEW locator: ${result.count} matches for css=${css}, cannot identify the recorded instance`
+          );
+        }
+        opts?.log?.(
+          `\u26A0 ambiguous WEBVIEW locator (${result.count} matches for css=${css}) \u2014 using the first match. Set VALIDATEQA_MOBILE_STRICT_MATCH=strict to fail instead.`
+        );
+        return result.kind === "ambiguous" ? ids[0] : result.elementId;
+      }
     } catch (err) {
-      if (isTransportError(err)) throw err;
+      if (isTransportError(err) || err instanceof MobileAmbiguousMatchError) throw err;
       lastError = err instanceof Error ? err.message : String(err);
     }
     await new Promise((resolve2) => setTimeout(resolve2, 250));
@@ -356356,21 +357111,42 @@ async function findWebViewElement(sessionPath, css, timeoutMs = DEFAULT_STEP_TIM
     `WEBVIEW element not found for css=${css} after ${timeoutMs}ms` + (lastError ? `. Last error: ${lastError}` : "")
   );
 }
+function isWebViewHydrationTransient(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return /no such element|NoSuchElement|element not interactable|stale element|WEBVIEW step requires|Empty page dictionary|not connectable|no WEBVIEW context|chrome not reachable/i.test(message);
+}
+var WEBVIEW_HYDRATION_TIMEOUT_MS = Number(process.env.VALIDATEQA_WEBVIEW_HYDRATION_TIMEOUT_MS) || 3e4;
+async function executeInWebViewContextWithHydrationRetry(sessionId, step, css, body, timeoutMs) {
+  const deadline = Date.now() + Math.max(1e3, timeoutMs);
+  for (; ; ) {
+    try {
+      await executeInWebViewContext(sessionId, step, css, body);
+      return;
+    } catch (err) {
+      if (!isWebViewHydrationTransient(err) || Date.now() >= deadline) throw err;
+      await new Promise((resolve2) => setTimeout(resolve2, 1e3));
+    }
+  }
+}
 async function executeTap(sessionId, step, platform3, isCrossPlatform = false) {
   const webCss = stepWebViewCss(step);
   if (webCss) {
-    await executeInWebViewContext(
+    await executeInWebViewContextWithHydrationRetry(
       sessionId,
       step,
       webCss,
-      (sessionPath, css) => clickCssInCurrentContext(sessionPath, css)
+      (sessionPath, css) => clickCssInCurrentContext(sessionPath, css),
+      Math.max(readStepTimeout(step) ?? DEFAULT_STEP_TIMEOUT_MS, WEBVIEW_HYDRATION_TIMEOUT_MS)
     );
     return;
   }
   const bounds = boundsForRun(step, platform3, isCrossPlatform);
   if (step.target) {
     try {
-      const elementId = await findElement(sessionId, step.target, readStepTimeout(step), { platform: platform3 });
+      const elementId = await findElement(sessionId, step.target, readStepTimeout(step), {
+        platform: platform3,
+        recordedBounds: bounds
+      });
       await wdRequest(`/session/${sessionId}/element/${elementId}/click`, {
         method: "POST",
         body: "{}"
@@ -356392,11 +357168,12 @@ async function executeType(sessionId, step, context) {
   const keysValue = keyboardSubmitOnly ? WEBDRIVER_ENTER_KEY : value;
   const webCss = stepWebViewCss(step);
   if (webCss) {
-    await executeInWebViewContext(
+    await executeInWebViewContextWithHydrationRetry(
       sessionId,
       step,
       webCss,
-      (sessionPath2, css) => keyboardSubmitOnly ? submitCssKeyboardInCurrentContext(sessionPath2, css) : typeCssInCurrentContext(sessionPath2, css, value)
+      (sessionPath2, css) => keyboardSubmitOnly ? submitCssKeyboardInCurrentContext(sessionPath2, css) : typeCssInCurrentContext(sessionPath2, css, value),
+      Math.max(readStepTimeout(step) ?? DEFAULT_STEP_TIMEOUT_MS, WEBVIEW_HYDRATION_TIMEOUT_MS)
     );
     return;
   }
@@ -356407,7 +357184,9 @@ async function executeType(sessionId, step, context) {
     const locatorStrategies = buildLocatorStrategies(step.target, context.platform);
     if (step.target && locatorStrategies.length > 0) {
       const elementId = await findElement(sessionId, step.target, readStepTimeout(step), {
-        platform: context.platform
+        platform: context.platform,
+        recordedBounds: bounds,
+        log: context.log
       });
       await wdRequest(`/session/${sessionId}/element/${elementId}/click`, {
         method: "POST",
@@ -356448,22 +357227,28 @@ async function executeType(sessionId, step, context) {
 }
 async function executeClear(sessionId, step, platform3, isCrossPlatform = false) {
   const webCss = stepWebViewCss(step);
+  const bounds = boundsForRun(step, platform3, isCrossPlatform);
   if (webCss) {
     await executeInWebViewContext(sessionId, step, webCss, async (sessionPath, css) => {
-      const elementId = await findWebViewElement(sessionPath, css, readStepTimeout(step));
+      const elementId = await findWebViewElement(sessionPath, css, readStepTimeout(step), {
+        matchIndex: step.target?.matchIndex,
+        expectedMatchCount: step.target?.expectedMatchCount
+      });
       await wdRequest(`${sessionPath}/element/${elementId}/clear`, { method: "POST", body: "{}" });
     });
     return;
   }
   const locatorStrategies = buildLocatorStrategies(step.target, platform3);
   if (step.target && locatorStrategies.length > 0) {
-    const elementId = await findElement(sessionId, step.target, readStepTimeout(step), { platform: platform3 });
+    const elementId = await findElement(sessionId, step.target, readStepTimeout(step), {
+      platform: platform3,
+      recordedBounds: bounds
+    });
     await wdRequest(`/session/${sessionId}/element/${elementId}/click`, { method: "POST", body: "{}" });
     await new Promise((resolve2) => setTimeout(resolve2, MOBILE_FOCUS_SETTLE_MS));
     await wdRequest(`/session/${sessionId}/element/${elementId}/clear`, { method: "POST", body: "{}" });
     return;
   }
-  const bounds = boundsForRun(step, platform3, isCrossPlatform);
   await clearField(`/session/${sessionId}`, bounds ?? void 0);
 }
 async function executeSwipe(sessionId, step) {
@@ -356524,34 +357309,47 @@ async function executeWaitForElement(sessionId, step, platform3) {
       sessionId,
       step,
       webCss,
-      (sessionPath, css) => findWebViewElement(sessionPath, css, timeout).then(() => void 0)
+      (sessionPath, css) => findWebViewElement(sessionPath, css, timeout, { disambiguate: false }).then(() => void 0)
     );
     return;
   }
-  await findElement(sessionId, step.target, timeout, { identityOnly: true, platform: platform3 });
+  await findElement(sessionId, step.target, timeout, { identityOnly: true, platform: platform3, disambiguate: false });
 }
-async function executeAssertVisible(sessionId, step, platform3) {
+async function executeAssertVisible(sessionId, step, platform3, isCrossPlatform = false) {
   const webCss = stepWebViewCss(step);
   if (webCss) {
     await executeInWebViewContext(sessionId, step, webCss, async (sessionPath, css) => {
-      const elementId2 = await findWebViewElement(sessionPath, css, readStepTimeout(step));
+      const elementId2 = await findWebViewElement(sessionPath, css, readStepTimeout(step), {
+        matchIndex: step.target?.matchIndex,
+        expectedMatchCount: step.target?.expectedMatchCount,
+        tolerateAmbiguity: true
+      });
       const result2 = await wdRequest(`${sessionPath}/element/${elementId2}/displayed`);
       if (!result2?.value) throw new Error(`WEBVIEW element found but not visible: css=${css}`);
     });
     return;
   }
-  const elementId = await findElement(sessionId, step.target, readStepTimeout(step), { identityOnly: true, platform: platform3 });
+  const elementId = await findElement(sessionId, step.target, readStepTimeout(step), {
+    identityOnly: true,
+    platform: platform3,
+    recordedBounds: boundsForRun(step, platform3, isCrossPlatform),
+    tolerateAmbiguity: true
+  });
   const result = await wdRequest(`/session/${sessionId}/element/${elementId}/displayed`);
   if (!result?.value) {
     throw new Error(`Element found but not visible: ${step.target?.primary ?? "unknown"}`);
   }
 }
-async function executeAssertText(sessionId, step, platform3) {
+async function executeAssertText(sessionId, step, platform3, isCrossPlatform = false) {
   if (!step.assertion) throw new Error("assertText step requires an assertion value");
   const webCss = stepWebViewCss(step);
   if (webCss) {
     await executeInWebViewContext(sessionId, step, webCss, async (sessionPath, css) => {
-      const elementId2 = await findWebViewElement(sessionPath, css, readStepTimeout(step));
+      const elementId2 = await findWebViewElement(sessionPath, css, readStepTimeout(step), {
+        matchIndex: step.target?.matchIndex,
+        expectedMatchCount: step.target?.expectedMatchCount,
+        tolerateAmbiguity: true
+      });
       const result2 = await wdRequest(`${sessionPath}/element/${elementId2}/text`);
       const actualText2 = typeof result2?.value === "string" ? result2.value : "";
       const textCandidates2 = await readElementTextCandidates(sessionId, elementId2, actualText2);
@@ -356563,7 +357361,12 @@ async function executeAssertText(sessionId, step, platform3) {
     });
     return;
   }
-  const elementId = await findElement(sessionId, step.target, readStepTimeout(step), { identityOnly: true, platform: platform3 });
+  const elementId = await findElement(sessionId, step.target, readStepTimeout(step), {
+    identityOnly: true,
+    platform: platform3,
+    recordedBounds: boundsForRun(step, platform3, isCrossPlatform),
+    tolerateAmbiguity: true
+  });
   const result = await wdRequest(`/session/${sessionId}/element/${elementId}/text`);
   const actualText = typeof result?.value === "string" ? result.value : "";
   const textCandidates = await readElementTextCandidates(sessionId, elementId, actualText);
@@ -356603,6 +357406,8 @@ function acquireControlPortSlot(deviceId) {
 function releaseControlPortSlot(deviceId) {
   controlPortSlotsByDevice.delete(deviceId);
 }
+var PINNED_DEVICE_SNAPSHOT_TTL_MS = 25 * 6e4;
+var pinnedDeviceSnapshot = null;
 async function executeMobileTest(options) {
   const logLines = [];
   const log2 = (msg) => logLines.push(`[${(/* @__PURE__ */ new Date()).toISOString()}] ${msg}`);
@@ -356610,6 +357415,7 @@ async function executeMobileTest(options) {
   const { steps: runSteps, missingKeys: missingVariableKeys } = resolveMobileStepValuePlaceholders(options.steps, options.testVariables);
   const runPlatform = options.target.platform;
   const isCrossPlatform = options.target.authoringPlatform != null && options.target.authoringPlatform !== runPlatform;
+  const captureStepScreenshots = options.captureStepScreenshots !== false;
   if (missingVariableKeys.length > 0) {
     log2(`\u26A0 Unresolved step-value placeholder(s): ${missingVariableKeys.map((k) => `{{${k}}}`).join(", ")} \u2014 no matching test variable configured for this project/run.`);
   }
@@ -356674,32 +357480,42 @@ async function executeMobileTest(options) {
       await startAppiumServer();
       log2("Appium server started");
     }
-    log2("Discovering devices...");
-    const devices = discoverAllDevices({ includeApps: true });
     const platformFilter = options.target.platform;
-    const matchingDevices = devices.filter(
-      (d) => d.platform === platformFilter && d.isAvailable && d.state === "BOOTED"
-    );
-    if (matchingDevices.length === 0) {
-      throw new Error(
-        `No ${platformFilter} ${platformFilter === "IOS" ? "simulator" : "emulator"} booted. Start one via ${platformFilter === "IOS" ? "Simulator.app" : "Android Studio"} first.`
+    const pinnedDeviceId = options.target.assignedDeviceId;
+    const candidateSnapshot = pinnedDeviceSnapshot;
+    const reusablePinnedSnapshot = pinnedDeviceId && candidateSnapshot && candidateSnapshot.deviceId === pinnedDeviceId && Date.now() - candidateSnapshot.at < PINNED_DEVICE_SNAPSHOT_TTL_MS ? candidateSnapshot : null;
+    if (reusablePinnedSnapshot) {
+      assertDeviceNotQuarantined(reusablePinnedSnapshot.device.id);
+      selectedDevice = reusablePinnedSnapshot.device;
+      log2(`Reusing known device (skipped device re-scan): ${selectedDevice.name} (${selectedDevice.id})`);
+    } else {
+      log2("Discovering devices...");
+      const devices = discoverAllDevices({ includeApps: true });
+      const matchingDevices = devices.filter(
+        (d) => d.platform === platformFilter && d.isAvailable && d.state === "BOOTED"
       );
-    }
-    if (options.target.assignedDeviceId) {
-      selectedDevice = matchingDevices.find((d) => d.id === options.target.assignedDeviceId);
-      if (!selectedDevice) {
+      if (matchingDevices.length === 0) {
         throw new Error(
-          `Assigned ${platformFilter} device ${options.target.assignedDeviceId} is no longer booted/available (booted: ${matchingDevices.map((d) => d.id).join(", ") || "none"}). Refusing to fall back to another device.`
+          `No ${platformFilter} ${platformFilter === "IOS" ? "simulator" : "emulator"} booted. Start one via ${platformFilter === "IOS" ? "Simulator.app" : "Android Studio"} first.`
         );
       }
+      if (options.target.assignedDeviceId) {
+        selectedDevice = matchingDevices.find((d) => d.id === options.target.assignedDeviceId);
+        if (!selectedDevice) {
+          throw new Error(
+            `Assigned ${platformFilter} device ${options.target.assignedDeviceId} is no longer booted/available (booted: ${matchingDevices.map((d) => d.id).join(", ") || "none"}). Refusing to fall back to another device.`
+          );
+        }
+      }
+      if (!selectedDevice && options.target.recordedDeviceId) {
+        selectedDevice = matchingDevices.find((d) => d.id === options.target.recordedDeviceId);
+      }
+      if (!selectedDevice) {
+        selectedDevice = matchingDevices[0];
+      }
+      log2(`Using device: ${selectedDevice.name} (${selectedDevice.id})`);
+      pinnedDeviceSnapshot = options.target.assignedDeviceId ? { deviceId: options.target.assignedDeviceId, device: selectedDevice, at: Date.now() } : null;
     }
-    if (!selectedDevice && options.target.recordedDeviceId) {
-      selectedDevice = matchingDevices.find((d) => d.id === options.target.recordedDeviceId);
-    }
-    if (!selectedDevice) {
-      selectedDevice = matchingDevices[0];
-    }
-    log2(`Using device: ${selectedDevice.name} (${selectedDevice.id})`);
     try {
       capture = await startMobileNetworkCapture({
         platform: options.target.platform,
@@ -356766,7 +357582,14 @@ async function executeMobileTest(options) {
       const resetAllowed = shouldResetMobileAppData(options.target.platform, selectedDevice.id);
       if (resetAllowed) {
         try {
-          await executeMobileScript(sessionId, "mobile: clearApp", [{ appId: options.target.appId }]);
+          if (options.target.platform === "IOS") {
+            await terminateTargetApp(sessionId, "IOS", options.target.appId).catch(() => {
+            });
+            const wiped = await clearIosSimulatorAppData(selectedDevice.id, options.target.appId);
+            if (!wiped.ok) throw new Error(wiped.detail);
+          } else {
+            await executeMobileScript(sessionId, "mobile: clearApp", [{ appId: options.target.appId }]);
+          }
           clearedAppDataBeforeLaunch = true;
           log2(resetPolicy === "CLEAR_APP_DATA" ? "App data cleared before launch (target resetPolicy=CLEAR_APP_DATA)." : "App data cleared before launch (test was recorded from a cold logged-out state).");
         } catch (err) {
@@ -356819,17 +357642,21 @@ async function executeMobileTest(options) {
     const entryStep = selectEntryDriftGateStep(runSteps, runPlatform);
     if (entryStep) {
       try {
-        const entryTimeout = recordedFromClearedState ? Math.max(DEFAULT_STEP_TIMEOUT_MS, COLD_BOOT_ENTRY_TIMEOUT_MS) : DEFAULT_STEP_TIMEOUT_MS;
+        const entryTimeout = Math.max(DEFAULT_STEP_TIMEOUT_MS, COLD_BOOT_ENTRY_TIMEOUT_MS);
         const entryWebCss = stepWebViewCss(entryStep);
         if (entryWebCss) {
           await executeInWebViewContext(
             sessionId,
             entryStep,
             entryWebCss,
-            (sessionPath, css) => findWebViewElement(sessionPath, css, entryTimeout).then(() => void 0)
+            (sessionPath, css) => findWebViewElement(sessionPath, css, entryTimeout, { disambiguate: false }).then(() => void 0)
           );
         } else {
-          await findElement(sessionId, entryStep.target, entryTimeout, { identityOnly: true, platform: runPlatform });
+          await findElement(sessionId, entryStep.target, entryTimeout, {
+            identityOnly: true,
+            platform: runPlatform,
+            disambiguate: false
+          });
         }
       } catch (err) {
         if (isTransportError(err)) throw err;
@@ -356889,10 +357716,10 @@ async function executeMobileTest(options) {
             await executeWaitForElement(sessionId, step, runPlatform);
             break;
           case "assertVisible":
-            await executeAssertVisible(sessionId, step, runPlatform);
+            await executeAssertVisible(sessionId, step, runPlatform, isCrossPlatform);
             break;
           case "assertText":
-            await executeAssertText(sessionId, step, runPlatform);
+            await executeAssertText(sessionId, step, runPlatform, isCrossPlatform);
             break;
           default: {
             const _exhaustive = step.action;
@@ -356911,7 +357738,7 @@ async function executeMobileTest(options) {
           environmental = stepError;
         }
       }
-      const screenshot = await takeScreenshot(sessionId).catch(() => null);
+      const screenshot = captureStepScreenshots ? await takeScreenshot(sessionId).catch(() => null) : null;
       screenshots.push(screenshot ?? "");
       if (status === "failed") {
         await recordFirstFailingSource();
@@ -357173,10 +358000,10 @@ async function driveHarvestStep(sessionId, step, elementId, platform3) {
         await executeWaitForElement(sessionId, step, platform3);
         return true;
       case "assertVisible":
-        await executeAssertVisible(sessionId, step, platform3);
+        await executeAssertVisible(sessionId, step, platform3, true);
         return true;
       case "assertText":
-        await executeAssertText(sessionId, step, platform3);
+        await executeAssertText(sessionId, step, platform3, true);
         return true;
       default:
         break;
@@ -357258,7 +358085,15 @@ async function harvestPlatformLocators(options) {
       const identityStrategies = webViewCss ? [] : buildIdentityLocatorStrategies(step.target);
       if (!webViewCss && identityStrategies.length > 0 && step.target) {
         try {
-          elementId = await findElement(session.sessionId, step.target, DEFAULT_STEP_TIMEOUT_MS, { identityOnly: true });
+          elementId = await findElement(
+            session.sessionId,
+            step.target,
+            Math.max(DEFAULT_STEP_TIMEOUT_MS, WEBVIEW_HYDRATION_TIMEOUT_MS),
+            {
+              identityOnly: true,
+              failClosedOnAmbiguity: true
+            }
+          );
         } catch (err) {
           if (isTransportError(err)) throw err;
           elementId = null;
@@ -357354,6 +358189,86 @@ function validateRunnerMobileTarget(value) {
   };
 }
 
+// src/services/heartbeat-keepalive.ts
+var import_node_worker_threads = require("worker_threads");
+var KEEPALIVE_INTERVAL_MS = (() => {
+  const raw = Number(process.env.VALIDATEQA_HEARTBEAT_KEEPALIVE_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : 2e4;
+})();
+function isHeartbeatKeepaliveEnabled(env = process.env) {
+  return (env.VALIDATEQA_HEARTBEAT_KEEPALIVE ?? "").trim().toLowerCase() !== "off";
+}
+var WORKER_SOURCE = `
+const { parentPort } = require('node:worker_threads');
+let url = null;
+let headers = null;
+let body = null;
+let intervalMs = 20000;
+let timer = null;
+
+async function post() {
+  if (!url || !headers || !body) return; // inert until the first real heartbeat
+  try {
+    await fetch(url, {
+      method: 'POST',
+      headers,
+      body,
+      signal: AbortSignal.timeout(10000),
+    });
+  } catch {
+    // Best-effort by design: the next tick retries; the main loop's own
+    // heartbeat error handling owns logging/upgrade signals.
+  }
+}
+
+parentPort.on('message', (msg) => {
+  if (!msg || typeof msg !== 'object') return;
+  if (msg.type === 'update') {
+    url = msg.url;
+    headers = msg.headers;
+    body = msg.body;
+    intervalMs = msg.intervalMs || intervalMs;
+    if (!timer) {
+      timer = setInterval(post, intervalMs);
+      if (timer.unref) timer.unref();
+    }
+  } else if (msg.type === 'stop') {
+    if (timer) clearInterval(timer);
+    timer = null;
+    parentPort.close();
+  }
+});
+`;
+var NOOP_KEEPALIVE = { update: () => {
+}, stop: () => {
+} };
+function startHeartbeatKeepalive(options = {}) {
+  if (!isHeartbeatKeepaliveEnabled(options.env)) return NOOP_KEEPALIVE;
+  const intervalMs = options.intervalMs ?? KEEPALIVE_INTERVAL_MS;
+  let worker;
+  try {
+    worker = new import_node_worker_threads.Worker(WORKER_SOURCE, { eval: true });
+    worker.unref();
+    worker.on("error", () => {
+      worker = null;
+    });
+  } catch {
+    return NOOP_KEEPALIVE;
+  }
+  return {
+    update(url, headers, body) {
+      worker?.postMessage({ type: "update", url, headers, body, intervalMs });
+    },
+    stop() {
+      try {
+        worker?.postMessage({ type: "stop" });
+      } catch {
+      }
+      worker = null;
+    }
+  };
+}
+
 // src/mobile-device-queue.ts
 function isNativeMobileDiscoveryContext(ctx) {
   if (!ctx) return false;
@@ -357424,10 +358339,10 @@ function decideMobileDeviceGate(input) {
 
 // src/services/mobile-bridge.ts
 var import_http = require("http");
-var import_child_process3 = require("child_process");
+var import_child_process4 = require("child_process");
 var import_crypto = require("crypto");
 var import_os4 = require("os");
-var import_path3 = require("path");
+var import_path4 = require("path");
 var import_fs3 = require("fs");
 init_dist();
 var MOBILE_BRIDGE_PORT2 = 9515;
@@ -357534,7 +358449,7 @@ async function getWindowSize3() {
 }
 var BRIDGE_PROCESS_MARKER = "validateqa-mobile-bridge";
 var BRIDGE_PORT = MOBILE_BRIDGE_PORT2;
-var BRIDGE_PID_FILE = (0, import_path3.join)((0, import_os4.homedir)(), ".validate.qa", "mobile-bridge.pid");
+var BRIDGE_PID_FILE = (0, import_path4.join)((0, import_os4.homedir)(), ".validate.qa", "mobile-bridge.pid");
 function readBridgePidFile() {
   try {
     const raw = (0, import_fs3.readFileSync)(BRIDGE_PID_FILE, "utf-8").trim();
@@ -357546,7 +358461,7 @@ function readBridgePidFile() {
 }
 function writeBridgePidFile(pid) {
   try {
-    (0, import_fs3.mkdirSync)((0, import_path3.dirname)(BRIDGE_PID_FILE), { recursive: true, mode: 448 });
+    (0, import_fs3.mkdirSync)((0, import_path4.dirname)(BRIDGE_PID_FILE), { recursive: true, mode: 448 });
     (0, import_fs3.writeFileSync)(BRIDGE_PID_FILE, String(pid), { mode: 384 });
   } catch {
   }
@@ -357561,19 +358476,19 @@ function killStaleBridge() {
   const pid = readBridgePidFile();
   if (!pid) return;
   try {
-    (0, import_child_process3.execFileSync)("kill", ["-0", String(pid)], { stdio: "ignore" });
+    (0, import_child_process4.execFileSync)("kill", ["-0", String(pid)], { stdio: "ignore" });
   } catch {
     clearBridgePidFile();
     return;
   }
   try {
-    const pidsOnPort = (0, import_child_process3.execFileSync)("lsof", ["-ti", `:${BRIDGE_PORT}`], { encoding: "utf-8" }).trim();
+    const pidsOnPort = (0, import_child_process4.execFileSync)("lsof", ["-ti", `:${BRIDGE_PORT}`], { encoding: "utf-8" }).trim();
     const pidList = pidsOnPort.split("\n").filter(Boolean);
     if (!pidList.includes(String(pid))) {
       return;
     }
-    (0, import_child_process3.execFileSync)("kill", ["-9", String(pid)], { stdio: "ignore" });
-    (0, import_child_process3.execFileSync)("sleep", ["1"], { stdio: "ignore" });
+    (0, import_child_process4.execFileSync)("kill", ["-9", String(pid)], { stdio: "ignore" });
+    (0, import_child_process4.execFileSync)("sleep", ["1"], { stdio: "ignore" });
   } catch {
   } finally {
     clearBridgePidFile();
@@ -357846,6 +358761,13 @@ async function startSession(validated, res) {
     ...deviceId ? { "appium:udid": deviceId } : {},
     ...platformVersion ? { "appium:platformVersion": platformVersion } : {},
     "appium:noReset": true,
+    // Same Xcode 27+ workaround as the executor's createSession (appium-executor.ts):
+    // Simulator.app is no longer at <DEVELOPER_DIR>/Applications, so XCUITest's
+    // "open Simulator UI" step fails. The sim is already booted via CoreSimulator;
+    // skip the GUI open. Scoped to simulator UDIDs; APPIUM_IOS_HEADLESS=false
+    // overrides. Verified live: without this, recorder/mirror sessions on iOS
+    // die with "Simulator.app does not exist" while executor sessions work.
+    ...isIosSimulatorUdid(deviceId) && process.env.APPIUM_IOS_HEADLESS !== "false" ? { "appium:isHeadless": true } : {},
     ...realCaps
   } : {
     platformName: "Android",
@@ -357864,7 +358786,12 @@ async function startSession(validated, res) {
         capabilities: {
           alwaysMatch: capabilities
         }
-      })
+      }),
+      // Session creation is the one legitimately slow WebDriver call (iOS WDA
+      // build/launch can take minutes on a cold toolchain) — same ceiling as
+      // the executor's wdRequest session-create path. Without this, the shared
+      // appiumRequest 10s default aborts every iOS recorder session.
+      signal: AbortSignal.timeout(WD_SESSION_CREATE_TIMEOUT_MS)
     });
     state.appiumSessionId = result?.value?.sessionId ?? result?.sessionId ?? null;
     if (!state.appiumSessionId) {
@@ -358642,6 +359569,9 @@ function detachMirrorSession(deviceId) {
   stopAllMirrorClients();
   stopSessionReaper();
 }
+function getMirrorSessionId(deviceId) {
+  return runnerChannels.get(deviceId)?.sessionId;
+}
 
 // src/services/mobile/mobile-bridge-driver.ts
 var import_runner_core9 = __toESM(require_dist2());
@@ -358672,6 +359602,7 @@ var MobileBridgeDriver = class {
   sessionId;
   platform;
   appId;
+  deviceId;
   allowAppReset;
   recoverSession;
   maxSessionRecoveries;
@@ -358692,6 +359623,7 @@ var MobileBridgeDriver = class {
     this.sessionId = config.sessionId;
     this.platform = config.platform;
     this.appId = config.appId;
+    this.deviceId = config.deviceId;
     this.allowAppReset = config.allowAppReset === true;
     this.recoverSession = config.recoverSession;
     this.maxSessionRecoveries = Math.max(0, Math.floor(config.maxSessionRecoveries ?? 1));
@@ -358989,17 +359921,34 @@ var MobileBridgeDriver = class {
     });
   }
   /**
-   * Deterministic state reset: clear app data + relaunch (Android emulators
-   * only, per the runner-computed allowAppReset policy). Returns false when
-   * unsupported/disallowed or when clearApp throws — callers fall back to
-   * relaunch(), preserving today's behavior. On success, waits for cold-boot
-   * content so recording and replay agree on the true entry screen.
+   * Deterministic state reset: clear app data + relaunch, per the
+   * runner-computed allowAppReset policy (Android emulators / iOS simulators
+   * only — a personal physical device is never wiped). Android clears via
+   * `mobile: clearApp`; iOS terminates the app and wipes its simulator data
+   * container + keychain through `simctl` (see ios-simulator-reset.ts).
+   * Returns false when unsupported/disallowed or when the clear fails —
+   * callers fall back to relaunch(), preserving today's behavior. On success,
+   * waits for cold-boot content so recording and replay agree on the true
+   * entry screen.
    */
   async resetAppState() {
-    if (!this.allowAppReset || this.platform !== "ANDROID") return false;
+    if (!this.allowAppReset) return false;
+    if (this.platform === "IOS" && !isIosSimulatorUdid(this.deviceId)) return false;
     return this.withSessionRecovery("app data reset", async () => {
       try {
-        await this.executeScript("mobile: clearApp", [{ appId: this.appId }]);
+        if (this.platform === "IOS") {
+          try {
+            await this.executeScript("mobile: terminateApp", [{ ...this.appLifecycleArgs(), timeout: 5e3 }]);
+          } catch (err) {
+            if (isRecoverableAppiumSessionFailure(err)) throw err;
+          }
+          const wiped = await clearIosSimulatorAppData(this.deviceId ?? "", this.appId);
+          if (!wiped.ok) {
+            throw new Error(`iOS simulator app-data reset failed: ${wiped.detail}`);
+          }
+        } else {
+          await this.executeScript("mobile: clearApp", [{ appId: this.appId }]);
+        }
         await this.executeScript("mobile: activateApp", [this.appLifecycleArgs()]);
         try {
           await waitForColdBootSettle(this.sessionPath);
@@ -359138,7 +360087,7 @@ function readActiveBundleId2(result) {
 }
 
 // src/services/doctor.ts
-var import_child_process4 = require("child_process");
+var import_child_process5 = require("child_process");
 var import_fs4 = require("fs");
 var import_os5 = require("os");
 var C = {
@@ -359158,7 +360107,7 @@ function computeDoctorReadiness(web, ios, android) {
 }
 function run(cmd) {
   try {
-    return (0, import_child_process4.execSync)(cmd, { encoding: "utf-8", timeout: 15e3, stdio: ["pipe", "pipe", "pipe"] }).trim();
+    return (0, import_child_process5.execSync)(cmd, { encoding: "utf-8", timeout: 15e3, stdio: ["pipe", "pipe", "pipe"] }).trim();
   } catch {
     return null;
   }
@@ -359590,6 +360539,113 @@ function envInt(name, fallback) {
 }
 var MOBILE_DEVICE_CEILING = Math.max(0, envInt("MOBILE_DEVICE_CEILING", 0));
 var MOBILE_HEAL_HOLD_MS = Math.max(0, envInt("MOBILE_HEAL_HOLD_MS", 2e4));
+var MOBILE_RUN_WATCHDOG_MS = Math.max(0, envInt("MOBILE_RUN_WATCHDOG_MS", 30 * 6e4));
+var MOBILE_RUN_ABORT_GRACE_MS = Math.max(0, envInt("MOBILE_RUN_ABORT_GRACE_MS", 2 * 6e4));
+var MOBILE_CANCEL_POLL_MS = Math.max(0, envInt("MOBILE_CANCEL_POLL_MS", 15e3));
+var MobileRunWatchdog = class {
+  constructor(options) {
+    this.options = options;
+  }
+  phase = "idle";
+  released = false;
+  quarantined = false;
+  cancelAbortTimer = null;
+  cancelGraceTimer = null;
+  /** Current phase (exposed for tests / observability). */
+  getPhase() {
+    return this.phase;
+  }
+  /** Arm the wall-clock abort timer. Call once, immediately after dispatch. */
+  start() {
+    if (this.phase !== "idle") return;
+    this.phase = "active";
+    if (this.options.abortMs > 0) {
+      this.cancelAbortTimer = this.options.schedule(
+        () => this.triggerAbort(`exceeded the ${Math.round(this.options.abortMs / 6e4)}min wall-clock ceiling`),
+        this.options.abortMs
+      );
+    }
+  }
+  /** Stage 1. Idempotent (a no-op unless still ACTIVE). Also called by the
+   *  cancellation observer. Quarantines the device (blocking the run's own
+   *  session-recovery from resurrecting the killed session — observed live),
+   *  kills the run's session (best-effort), and starts the grace clock;
+   *  deliberately does NOT release the lease. */
+  triggerAbort(reason) {
+    if (this.phase !== "active") return;
+    this.phase = "aborting";
+    this.clearAbortTimer();
+    if (this.options.deviceId) {
+      this.quarantined = true;
+      this.options.callbacks.quarantine(this.options.deviceId);
+      this.options.callbacks.abort(this.options.deviceId, this.options.runId, reason);
+    } else {
+      this.options.callbacks.log("warn", `Run ${this.options.runId} ${reason} \u2014 no leased device to abort; awaiting the run's own settle.`);
+    }
+    if (this.options.graceMs > 0) {
+      this.cancelGraceTimer = this.options.schedule(() => this.forceRelease(), this.options.graceMs);
+    } else {
+      this.forceRelease();
+    }
+  }
+  /** The run's promise settled (normal completion, or after an abort). The single
+   *  release owner: releases at most once and lifts any quarantine. Idempotent. */
+  settle() {
+    if (this.phase === "settled") return;
+    const wasForceReleased = this.released;
+    this.phase = "settled";
+    this.clearAbortTimer();
+    this.clearGraceTimer();
+    if (!this.released) {
+      this.released = true;
+      this.options.callbacks.release();
+    }
+    if (this.quarantined && this.options.deviceId) {
+      this.quarantined = false;
+      this.options.callbacks.unquarantine(this.options.deviceId);
+      if (wasForceReleased) {
+        this.options.callbacks.log("info", `Run ${this.options.runId} finally settled \u2014 lifted the quarantine on device ${this.options.deviceId}.`);
+      }
+    }
+  }
+  /** Stage 2. The run did not settle within the grace window after the abort. Force-
+   *  release the slot to unwedge capacity; the device stays quarantined (since the
+   *  stage-1 abort) until the promise eventually settles. Idempotent and guarded
+   *  against a late settle. */
+  forceRelease() {
+    if (this.released || this.phase === "settled") return;
+    this.clearGraceTimer();
+    this.released = true;
+    this.options.callbacks.release();
+    if (this.options.deviceId) {
+      if (!this.quarantined) {
+        this.quarantined = true;
+        this.options.callbacks.quarantine(this.options.deviceId);
+      }
+      this.options.callbacks.log(
+        "warn",
+        `Run ${this.options.runId} did not settle ${Math.round(this.options.graceMs / 1e3)}s after abort \u2014 force-released its slot; device ${this.options.deviceId} stays quarantined from re-lease until the run's promise settles.`
+      );
+    } else {
+      this.options.callbacks.log("warn", `Run ${this.options.runId} did not settle after abort \u2014 force-released its slot to unwedge mobile capacity.`);
+    }
+  }
+  clearAbortTimer() {
+    if (this.cancelAbortTimer) {
+      this.cancelAbortTimer();
+      this.cancelAbortTimer = null;
+    }
+  }
+  clearGraceTimer() {
+    if (this.cancelGraceTimer) {
+      this.cancelGraceTimer();
+      this.cancelGraceTimer = null;
+    }
+  }
+};
+function isServerCancelledRunStatus(status) {
+  return status === "ERROR" || status === "CANCELLED" || status === "CANCELLING";
+}
 function scrubAuditMessages(messages, testVariables) {
   if (messages === void 0 || messages === null) return messages;
   const compacted = compactForAudit(messages);
@@ -359665,7 +360721,7 @@ var log = {
   dim: (msg) => console.log(`${C2.gray}${msg}${C2.reset}`)
 };
 function getRunsDir() {
-  const dir = process.env.RUNS_DIR || (0, import_path4.join)((0, import_os6.homedir)(), ".validate.qa", "runs");
+  const dir = process.env.RUNS_DIR || (0, import_path5.join)((0, import_os6.homedir)(), ".validate.qa", "runs");
   (0, import_runner_core12.ensurePrivateDirectory)(dir);
   return dir;
 }
@@ -361151,9 +362207,15 @@ ${finalVerifyResult.logs ?? ""}`;
                 // flip the test to needs_manual_authoring), so an environmentally
                 // aborted pass — wrong screen, system dialog, transport flake —
                 // must not persist step divergences it could not fairly judge.
-                // Harvested bundles are still posted: they were positively
-                // resolved before the abort and the merge is idempotent.
-                divergentOrders: harvest.environmentalError ? [] : harvest.divergentOrders,
+                // The same applies to a harvest that ADVANCED THROUGH NOTHING
+                // (reachedOrder null): it never got past the entry screen, so its
+                // step judgments are cold-boot/entry noise, not app knowledge —
+                // observed live: a slow WKWebView hydration marked step 1
+                // divergent and permanently dead-ended the test in
+                // needs_manual_authoring with no retry path. Harvested bundles
+                // are still posted: they were positively resolved and the merge
+                // is idempotent.
+                divergentOrders: harvest.environmentalError || harvest.reachedOrder == null ? [] : harvest.divergentOrders,
                 reachedOrder: harvest.reachedOrder,
                 logs: harvest.logs,
                 ...harvest.environmentalError ? { environmentalError: harvest.environmentalError } : {}
@@ -361597,9 +362659,11 @@ ${finalVerifyResult.logs ?? ""}`;
               sessionId: session.sessionId,
               platform: platform3,
               appId: session.appId,
-              // Deterministic-state authorization: Android emulators only by
-              // default (VALIDATEQA_MOBILE_APP_RESET overrides) — a personal
-              // physical device must never have its app data wiped.
+              deviceId: session.deviceId,
+              // Deterministic-state authorization: Android emulators / iOS
+              // simulators only (VALIDATEQA_MOBILE_APP_RESET overrides the
+              // Android default) — a personal physical device must never have
+              // its app data wiped.
               allowAppReset: mobileTarget.resetPolicy !== "PRESERVE_APP_DATA" && shouldResetMobileAppData(platform3, session.deviceId),
               maxSessionRecoveries: 1,
               recoverSession: async (cause) => {
@@ -362115,6 +363179,7 @@ ${finalVerifyResult.logs ?? ""}`;
                   sessionId: opened.sessionId,
                   platform: target.platform,
                   appId: opened.appId,
+                  deviceId: opened.deviceId,
                   allowAppReset: target.resetPolicy !== "PRESERVE_APP_DATA" && shouldResetMobileAppData(target.platform, opened.deviceId)
                 });
               };
@@ -362727,6 +363792,7 @@ async function startRunner(opts) {
     else activeMobileOpsByPlatform.set(p, next);
   };
   const leasedDeviceIds = /* @__PURE__ */ new Map();
+  const activeMobileRuns = /* @__PURE__ */ new Map();
   let activeMobileDiscoveries = 0;
   const mobileHealHold = /* @__PURE__ */ new Map();
   const pruneMobileHealHolds = () => {
@@ -362807,6 +363873,7 @@ async function startRunner(opts) {
       }
     }
   };
+  const heartbeatKeepalive = startHeartbeatKeepalive();
   const sendHeartbeat = async () => {
     try {
       const devices = enableMobile ? getCachedDeviceSnapshot() : [];
@@ -362821,41 +363888,44 @@ async function startRunner(opts) {
       lastInventoryPids = new Set(processInventory.processes.map((p) => p.pid));
       lastInventoryKinds.clear();
       for (const p of processInventory.processes) lastInventoryKinds.set(p.pid, p.kind);
-      const response = await fetch(`${serverUrl}/api/runner/heartbeat`, {
+      const heartbeatUrl = `${serverUrl}/api/runner/heartbeat`;
+      const heartbeatBody = JSON.stringify({
+        runnerName: RUNNER_NAME,
+        runnerVersion: RUNNER_VERSION,
+        runnerBuildId: RUNNER_BUILD_ID,
+        runsCompleted,
+        activeRuns,
+        maxConcurrent: MAX_CONCURRENT,
+        uptimeMs: Date.now() - startedAt,
+        capabilities,
+        devices,
+        mobileBridge: bridge ? {
+          online: bridge.running,
+          port: bridge.port,
+          tunnelUrl: bridge.tunnelUrl,
+          tunnelToken: bridge.tunnelToken
+        } : void 0,
+        activeByType: Object.fromEntries(activeByType),
+        activeByProject: Object.fromEntries(activeByProject),
+        typeLimits: TYPE_LIMITS,
+        maxProjectConcurrent: MAX_PROJECT_CONCURRENT,
+        resourceSnapshot: resourceStatus.snapshot,
+        resourceGovernor: resourceStatus.governor,
+        processInventory,
+        aiQueue: (0, import_runner_core13.getRunnerAIQueueStats)(),
+        liveBrowsers: import_runner_core11.liveBrowserRegistry.snapshotForHeartbeat(),
+        // Pre-flight checks (ANDROID_HOME, Xcode, Appium drivers, adb, etc).
+        // Cached & cheap — see getCachedDoctor above.
+        doctor: getCachedDoctor()
+      });
+      const response = await fetch(heartbeatUrl, {
         method: "POST",
         headers,
-        body: JSON.stringify({
-          runnerName: RUNNER_NAME,
-          runnerVersion: RUNNER_VERSION,
-          runnerBuildId: RUNNER_BUILD_ID,
-          runsCompleted,
-          activeRuns,
-          maxConcurrent: MAX_CONCURRENT,
-          uptimeMs: Date.now() - startedAt,
-          capabilities,
-          devices,
-          mobileBridge: bridge ? {
-            online: bridge.running,
-            port: bridge.port,
-            tunnelUrl: bridge.tunnelUrl,
-            tunnelToken: bridge.tunnelToken
-          } : void 0,
-          activeByType: Object.fromEntries(activeByType),
-          activeByProject: Object.fromEntries(activeByProject),
-          typeLimits: TYPE_LIMITS,
-          maxProjectConcurrent: MAX_PROJECT_CONCURRENT,
-          resourceSnapshot: resourceStatus.snapshot,
-          resourceGovernor: resourceStatus.governor,
-          processInventory,
-          aiQueue: (0, import_runner_core13.getRunnerAIQueueStats)(),
-          liveBrowsers: import_runner_core11.liveBrowserRegistry.snapshotForHeartbeat(),
-          // Pre-flight checks (ANDROID_HOME, Xcode, Appium drivers, adb, etc).
-          // Cached & cheap — see getCachedDoctor above.
-          doctor: getCachedDoctor()
-        }),
+        body: heartbeatBody,
         signal: AbortSignal.timeout(1e4)
       });
       if (response.ok) {
+        heartbeatKeepalive.update(heartbeatUrl, headers, heartbeatBody);
         const body = await response.json().catch(() => null);
         if (body && Array.isArray(body.commands) && body.commands.length > 0) {
           void handleControlCommands(body.commands);
@@ -362926,6 +363996,7 @@ async function startRunner(opts) {
       process.exit(1);
     }, SHUTDOWN_TIMEOUT_MS).unref();
     clearInterval(heartbeat);
+    heartbeatKeepalive.stop();
     if (liveBrowserHeartbeatTimer) {
       clearTimeout(liveBrowserHeartbeatTimer);
       liveBrowserHeartbeatTimer = null;
@@ -362977,6 +364048,32 @@ async function startRunner(opts) {
     }
   }, PIDS_WATCHDOG_INTERVAL_MS);
   pidsWatchdog.unref();
+  const pollMobileRunCancellations = async () => {
+    if (shuttingDown || activeMobileRuns.size === 0) return;
+    const runIds = [...activeMobileRuns.keys()];
+    try {
+      const res = await fetch(`${serverUrl}/api/runner/runs/status`, {
+        method: "POST",
+        headers: { ...headers, "Content-Type": "application/json" },
+        body: JSON.stringify({ runIds }),
+        signal: AbortSignal.timeout(1e4)
+      });
+      if (!res.ok) return;
+      const body = await res.json().catch(() => null);
+      if (!body || !Array.isArray(body.runs)) return;
+      for (const row of body.runs) {
+        if (!row || typeof row.id !== "string" || typeof row.status !== "string") continue;
+        if (!isServerCancelledRunStatus(row.status)) continue;
+        const watchdog = activeMobileRuns.get(row.id);
+        if (watchdog) watchdog.triggerAbort(`was cancelled server-side (status ${row.status})`);
+      }
+    } catch {
+    }
+  };
+  const mobileCancelPoll = enableMobile && MOBILE_CANCEL_POLL_MS > 0 ? setInterval(() => {
+    void pollMobileRunCancellations();
+  }, MOBILE_CANCEL_POLL_MS) : null;
+  mobileCancelPoll?.unref?.();
   const deferralLogged = /* @__PURE__ */ new Map();
   const logDeferredOnce = (runId, line) => {
     if (deferralLogged.get(runId) === line) return;
@@ -363059,14 +364156,17 @@ async function startRunner(opts) {
               });
               const capacity = MOBILE_DEVICE_CEILING > 0 ? Math.min(derived, MOBILE_DEVICE_CEILING) : derived;
               const leaseTarget = run2.target ?? run2.deviceRequirements;
-              const leaseSelection = selectFreeDevice(mobilePlatform, leasedDeviceIds, leaseSnapshot, {
+              const leaseExclusions = {
+                has: (id) => leasedDeviceIds.has(id) || isDeviceQuarantined(id)
+              };
+              const leaseSelection = selectFreeDevice(mobilePlatform, leaseExclusions, leaseSnapshot, {
                 appId: typeof leaseTarget?.appId === "string" ? leaseTarget.appId : void 0,
                 recordedDeviceId: typeof leaseTarget?.recordedDeviceId === "string" ? leaseTarget.recordedDeviceId : void 0,
                 platformVersion: typeof leaseTarget?.platformVersion === "string" ? leaseTarget.platformVersion : void 0,
                 deviceName: typeof run2.deviceRequirements?.deviceName === "string" ? run2.deviceRequirements.deviceName : void 0,
                 resetPolicy: leaseTarget?.resetPolicy
               });
-              const freeDeviceId = leaseSelection.kind === "selected" ? leaseSelection.deviceId : leaseSelection.kind === "unsatisfiable" ? pickFreeDevice(mobilePlatform, leasedDeviceIds, leaseSnapshot) : null;
+              const freeDeviceId = leaseSelection.kind === "selected" ? leaseSelection.deviceId : leaseSelection.kind === "unsatisfiable" ? pickFreeDevice(mobilePlatform, leaseExclusions, leaseSnapshot) : null;
               if (leaseSelection.kind === "unsatisfiable") {
                 mobileLeaseError = leaseSelection.reason;
                 log.warn(`  Mobile requirements unsatisfiable for ${run2.runId}: ${leaseSelection.reason}; claiming once to report the configuration error`);
@@ -363124,6 +364224,54 @@ async function startRunner(opts) {
               await new Promise((r) => setTimeout(r, staggerMs));
             }
             claimedThisPoll++;
+            const applyRelease = () => {
+              activeRuns--;
+              decrementType(runMode);
+              decrementProject(runProject);
+              if (isMobileOp) {
+                if (mobilePlatform) bumpActiveMobileOps(mobilePlatform, -1);
+                if (isDiscovery) activeMobileDiscoveries--;
+                if (leasedDeviceId) leasedDeviceIds.delete(leasedDeviceId);
+                activeMobileRuns.delete(run2.runId);
+              }
+            };
+            const runWatchdog = isMobileOp ? new MobileRunWatchdog({
+              runId: run2.runId,
+              deviceId: leasedDeviceId ?? void 0,
+              abortMs: MOBILE_RUN_WATCHDOG_MS,
+              graceMs: MOBILE_RUN_ABORT_GRACE_MS,
+              // Real timers, unref'd so a pending watchdog never keeps the process
+              // alive on shutdown.
+              schedule: (fn, ms) => {
+                const t = setTimeout(fn, ms);
+                if (typeof t.unref === "function") t.unref();
+                return () => clearTimeout(t);
+              },
+              callbacks: {
+                abort: (deviceId, rid, reason) => {
+                  const sessionId = getMirrorSessionId(deviceId);
+                  log.warn(
+                    `Run ${rid} ${reason} \u2014 aborting its in-flight Appium session${sessionId ? ` ${sessionId}` : " (no live session found)"} on device ${deviceId} so it fails fast and frees the lease.`
+                  );
+                  if (sessionId) void deleteAppiumSession(sessionId);
+                },
+                release: applyRelease,
+                quarantine: (deviceId) => {
+                  quarantineDevice(deviceId);
+                },
+                unquarantine: (deviceId) => {
+                  unquarantineDevice(deviceId);
+                },
+                log: (level, message) => {
+                  if (level === "warn") log.warn(message);
+                  else log.info(message);
+                }
+              }
+            }) : null;
+            if (runWatchdog) {
+              activeMobileRuns.set(run2.runId, runWatchdog);
+              runWatchdog.start();
+            }
             executeRun(run2, opts, headers, requestLiveBrowserHeartbeat, (testCaseId) => {
               if (mobilePlatform) {
                 mobileHealHold.set(testCaseId, { expiry: Date.now() + MOBILE_HEAL_HOLD_MS, platform: mobilePlatform });
@@ -363134,14 +364282,8 @@ async function startRunner(opts) {
               const msg = err instanceof Error ? err.message : String(err);
               log.warn(`Run ${run2.runId} crashed: ${msg}`);
             }).finally(() => {
-              activeRuns--;
-              decrementType(runMode);
-              decrementProject(runProject);
-              if (isMobileOp) {
-                if (mobilePlatform) bumpActiveMobileOps(mobilePlatform, -1);
-                if (isDiscovery) activeMobileDiscoveries--;
-                if (leasedDeviceId) leasedDeviceIds.delete(leasedDeviceId);
-              }
+              if (runWatchdog) runWatchdog.settle();
+              else applyRelease();
             });
           }
         }