@validate.qa/runner 1.0.22 → 1.0.24

package/dist/cli.js

@@ -245,8 +245,8 @@ var require_ai_provider = __commonJS({
     exports2.resetAIClient = resetAIClient;
     exports2.getServerProxiedAIClient = getServerProxiedAIClient;
     exports2.getServerProxiedClientForModel = getServerProxiedClientForModel;
-    exports2.getMobileAIClient = getMobileAIClient;
-    exports2.getMobileClientForModel = getMobileClientForModel;
+    exports2.getMobileAIClient = getMobileAIClient2;
+    exports2.getMobileClientForModel = getMobileClientForModel2;
     var openai_1 = __importDefault(require("openai"));
     var async_hooks_1 = require("async_hooks");
     var ai_retry_js_1 = require_ai_retry();
@@ -643,14 +643,14 @@ var require_ai_provider = __commonJS({
     function getServerProxiedClientForModel(_modelId) {
       return getServerProxiedAIClient();
     }
-    function getMobileAIClient() {
+    function getMobileAIClient2() {
       if ((process.env.SERVER_URL ?? "").trim().length > 0)
         return getServerProxiedAIClient();
       if (isMobileAiUnitTestMode())
         return getAIClient();
       throw new Error("Mobile AI requires the platform server URL (SERVER_URL). Customer runners do not provision provider API keys \u2014 the platform proxies every mobile AI completion through /api/runner/ai/execute, which lives on the shared server with the keys. If you reached this from `validate-runner start`, the credentials file is missing `serverUrl` or the install is broken; re-run `npx @validate.qa/runner login`. If you are calling the runner-core library directly, pass `options.aiClient` in tests or set VALIDATEQA_TEST_MODE=1 to opt into the local-provider fallback.");
     }
-    function getMobileClientForModel(modelId) {
+    function getMobileClientForModel2(modelId) {
       if ((process.env.SERVER_URL ?? "").trim().length > 0)
         return getServerProxiedClientForModel(modelId);
       if (isMobileAiUnitTestMode())
@@ -328483,7 +328483,7 @@ var require_package4 = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@validate.qa/runner",
-      version: "1.0.22",
+      version: "1.0.24",
       description: "validate local test runner - execute Playwright tests on your machine, connected to validate.qa cloud.",
       bin: {
         "validate-runner": "dist/cli.js"
@@ -330256,6 +330256,7 @@ var MOBILE_NEW_COMMAND_TIMEOUT_SECONDS = (() => {
   const raw = Number(process.env.VALIDATEQA_MOBILE_NEW_COMMAND_TIMEOUT);
   return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 600;
 })();
+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_ACTION_TIMEOUT_MS = 3e4;
@@ -330490,18 +330491,24 @@ async function freshLaunchTargetApp(sessionId, platform3, appId, log2) {
 }
 async function waitForColdBootContent(sessionId, log2, timeoutMs = 2e4) {
   const deadline = Date.now() + timeoutMs;
-  const MIN_ELEMENTS = 3;
+  const MIN_ELEMENTS = 12;
   let lastCount = 0;
+  let stableFrames = 0;
   while (Date.now() < deadline) {
     try {
       const res = await wdRequest(`/session/${sessionId}/source`);
       const xml = typeof res?.value === "string" ? res.value : "";
       const count = (xml.match(/<(android\.|XCUIElementType)/g) ?? []).length;
-      lastCount = count;
-      if (count >= MIN_ELEMENTS) {
-        log2(`  Cold-boot ready: UI tree has ${count} node(s).`);
-        return;
+      if (count >= MIN_ELEMENTS && count === lastCount) {
+        stableFrames++;
+        if (stableFrames >= 2) {
+          log2(`  Cold-boot ready: UI tree settled at ${count} node(s).`);
+          return;
+        }
+      } else {
+        stableFrames = 0;
       }
+      lastCount = count;
     } catch {
     }
     await new Promise((r) => setTimeout(r, 750));
@@ -330545,6 +330552,14 @@ async function takeScreenshot(sessionId) {
     return null;
   }
 }
+async function captureFailingSource(sessionId) {
+  try {
+    const result = await wdRequest(`/session/${sessionId}/source`);
+    return typeof result?.value === "string" ? result.value : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function mobileRecordingEnabled() {
   const value = process.env.VALIDATEQA_MOBILE_RUN_VIDEO;
   return value !== "0" && value !== "false";
@@ -330674,9 +330689,12 @@ function identityTextXpath(value) {
   const lit = xpathLiteral(value);
   return `//*[@text=${lit} or @content-desc=${lit} or @label=${lit} or @name=${lit} or @value=${lit}]`;
 }
+function isIdentityXpath(value) {
+  return value.includes("@") && !/(?:contains|starts-with)\s*\(/i.test(value);
+}
 function isIdentityStrategy(strategy) {
   if (strategy.using === "accessibility id" || strategy.using === "id") return true;
-  if (strategy.using === "xpath") return strategy.value.includes("@");
+  if (strategy.using === "xpath") return isIdentityXpath(strategy.value);
   return false;
 }
 function buildIdentityLocatorStrategies(target, platform3) {
@@ -330690,7 +330708,7 @@ function buildIdentityLocatorStrategies(target, platform3) {
       const trimmed = value?.trim();
       if (trimmed) strategies.push({ using: "xpath", value: identityTextXpath(trimmed) });
     }
-    if (bundle.xpath && bundle.xpath.includes("@")) strategies.push({ using: "xpath", value: bundle.xpath });
+    if (bundle.xpath && isIdentityXpath(bundle.xpath)) strategies.push({ using: "xpath", value: bundle.xpath });
   }
   if (!(platform3 && hasPlatformLocator(target, platform3))) {
     for (const value of [target.primary, ...target.fallbacks ?? []]) {
@@ -331037,6 +331055,7 @@ async function executeMobileTest(options) {
   let recordingStarted = false;
   let recordingStopped = false;
   let video;
+  let failingSource;
   const stopCapture = async () => {
     if (!capture || captureStopped) return apiCalls;
     captureStopped = true;
@@ -331060,6 +331079,10 @@ async function executeMobileTest(options) {
     }
     return video;
   };
+  const recordFirstFailingSource = async () => {
+    if (failingSource != null || !sessionId) return;
+    failingSource = await captureFailingSource(sessionId);
+  };
   try {
     log2("Checking Appium server health...");
     const health = await checkAppiumHealth();
@@ -331186,12 +331209,14 @@ async function executeMobileTest(options) {
     );
     if (entryStep) {
       try {
-        await findElement(sessionId, entryStep.target, DEFAULT_STEP_TIMEOUT_MS, { identityOnly: true, platform: runPlatform });
+        const entryTimeout = recordedFromClearedState ? Math.max(DEFAULT_STEP_TIMEOUT_MS, COLD_BOOT_ENTRY_TIMEOUT_MS) : DEFAULT_STEP_TIMEOUT_MS;
+        await findElement(sessionId, entryStep.target, entryTimeout, { identityOnly: true, platform: runPlatform });
       } catch (err) {
         if (isTransportError(err)) throw err;
         entryDrift = true;
         const driftMsg = `App started on an unexpected screen \u2014 the recorded flow's first element ("${entryStep.target?.primary ?? entryStep.description}") is not present, so the replay was aborted before it could blind-tap stale coordinates (screen drift; the app may be on onboarding or a different screen than when the test was recorded).`;
         log2(`  \u2717 Entry-screen drift: ${driftMsg}`);
+        await recordFirstFailingSource();
         stepResults.push({ stepOrder: entryStep.order, status: "failed", duration: 0, error: driftMsg });
         const driftShot = await takeScreenshot(sessionId).catch(() => null);
         screenshots.push(driftShot ?? "");
@@ -331268,6 +331293,9 @@ async function executeMobileTest(options) {
       }
       const screenshot = await takeScreenshot(sessionId).catch(() => null);
       screenshots.push(screenshot ?? "");
+      if (status === "failed") {
+        await recordFirstFailingSource();
+      }
       stepResults.push({
         stepOrder: step.order,
         status,
@@ -331305,7 +331333,8 @@ async function executeMobileTest(options) {
       duration: Date.now() - startTime,
       deviceId: selectedDevice?.id,
       deviceName: selectedDevice?.name,
-      environmental: environmental ?? void 0
+      environmental: environmental ?? void 0,
+      failingSource
     };
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
@@ -331326,7 +331355,8 @@ async function executeMobileTest(options) {
       // A throw before/around the step loop is a setup/environment problem
       // (no device booted, app not installed, session could not be created,
       // Appium unreachable) — never a genuine test assertion failure.
-      environmental: errorMsg
+      environmental: errorMsg,
+      failingSource
     };
   } finally {
     await stopCapture();
@@ -333295,6 +333325,9 @@ function budgetResultPayload(result, maxBytes = RESULT_BODY_BUDGET_BYTES, videoS
   if ((bytes > maxBytes || oversizedVideo) && payload.video != null) {
     drop(["video", "videoMimeType"], "video");
   }
+  if (bytes > maxBytes && payload.failingSource != null) {
+    drop(["failingSource"], "failingSource");
+  }
   if (bytes > maxBytes && Array.isArray(payload.screenshots) && payload.screenshots.length > 0) {
     const shots = [...payload.screenshots];
     const bySizeDesc = shots.map((shot, i) => ({ i, len: typeof shot === "string" ? shot.length : 0 })).sort((a, b) => b.len - a.len);
@@ -333346,6 +333379,7 @@ ${tail}` };
 // src/runner.ts
 init_dist();
 var import_runner_core12 = __toESM(require_dist2());
+var import_runner_core13 = __toESM(require_dist2());
 function fingerprintTest(test) {
   const code = test.framework === "APPIUM" ? [test.appiumCode ?? "", JSON.stringify(test.steps ?? [])].join("\n--steps--\n") : test.playwrightCode ?? "";
   return (0, import_node_crypto2.createHash)("sha256").update(test.name).update("\n--suite--\n").update(test.suiteName ?? "").update("\n--type--\n").update(test.testType ?? "").update("\n--framework--\n").update(test.framework ?? "").update("\n--code--\n").update(code).digest("hex").slice(0, 24);
@@ -333583,6 +333617,33 @@ async function postHealResult(serverUrl, headers, runId, healedCode, testCaseId,
   }
   throw new Error(`Failed to post heal result after ${MAX_ATTEMPTS} attempts: ${lastError?.message}`);
 }
+async function postMobileHealResult(serverUrl, headers, runId, body) {
+  const MAX_ATTEMPTS = 3;
+  let lastError;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    try {
+      const res = await fetch(`${serverUrl}/api/runner/runs/${runId}/mobile-heal-result`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(6e4)
+      });
+      if (res.ok) return;
+      lastError = new Error(`HTTP ${res.status}`);
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+    }
+    if (attempt < MAX_ATTEMPTS) {
+      const delay = Math.pow(2, attempt) * 1e3;
+      console.warn(`[runner] postMobileHealResult attempt ${attempt} failed (${lastError.message}), retrying in ${delay}ms...`);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+  throw new Error(`Failed to post mobile heal result after ${MAX_ATTEMPTS} attempts: ${lastError?.message}`);
+}
+function narrowMobileLaunchMode(mode) {
+  return mode === "LAUNCH_APP" || mode === "DEEP_LINK" || mode === "RESUME" ? mode : void 0;
+}
 async function postBatchHealResult(serverUrl, headers, runId, body) {
   const res = await fetch(`${serverUrl}/api/runner/runs/${runId}/batch-heal-result`, {
     method: "POST",
@@ -335491,6 +335552,218 @@ ${finalVerifyResult.logs ?? ""}`;
         log.fail("ERROR - No mobile steps");
         return;
       }
+      if (runMode === "heal" && run2.mobileAiHeal === true) {
+        if (getBridgeState().hasActiveSession) {
+          await postResult(opts.serverUrl, headers, run2.runId, {
+            status: "ERROR",
+            error: "CONFIG_ISSUE: the shared mobile device is busy with an active recording session; the AI heal will retry once it ends.",
+            duration: Date.now() - startTime
+          });
+          log.warn("Skipped mobile AI heal (device busy with a recording)");
+          return;
+        }
+        const healTarget = {
+          appId: target.appId,
+          platform: target.platform,
+          platformVersion: target.platformVersion,
+          recordedDeviceId: target.recordedDeviceId,
+          assignedDeviceId,
+          launchMode: target.launchMode,
+          deeplink: target.deeplink,
+          authoringPlatform: mobilePlatformFromMedium(run2.authoringMedium) ?? void 0
+        };
+        const nativeVerify = { last: null };
+        const runNativeTest = async ({ steps, target: t, testVariables }) => {
+          const res = await executeMobileTest({
+            steps,
+            target: {
+              appId: t.appId,
+              platform: t.platform,
+              platformVersion: t.platformVersion,
+              recordedDeviceId: t.recordedDeviceId,
+              assignedDeviceId: t.assignedDeviceId,
+              launchMode: narrowMobileLaunchMode(t.launchMode),
+              deeplink: t.deeplink,
+              authoringPlatform: t.authoringPlatform
+            },
+            testVariables
+          });
+          nativeVerify.last = res;
+          return {
+            passed: res.passed,
+            error: res.error,
+            stepResults: res.stepResults.map((s) => ({ stepOrder: s.stepOrder, status: s.status, error: s.error })),
+            failingSource: res.failingSource,
+            logs: res.logs
+          };
+        };
+        setExecutorBusy(true);
+        try {
+          log.info("\u{1FA7A} Mobile AI heal \u2014 reproducing the failure on device...");
+          const reproduce = await runNativeTest({ steps: mobileSteps, target: healTarget, testVariables: run2.testVariables });
+          if (reproduce.passed) {
+            const recovered = nativeVerify.last;
+            await postResult(opts.serverUrl, headers, run2.runId, {
+              status: "PASSED",
+              stepResults: recovered?.stepResults,
+              screenshots: recovered?.screenshots,
+              video: recovered?.video,
+              videoMimeType: recovered?.videoMimeType,
+              apiCalls: recovered?.apiCalls,
+              logs: recovered?.logs,
+              duration: Date.now() - startTime
+            });
+            try {
+              await postMobileHealResult(opts.serverUrl, headers, run2.runId, {
+                healedSteps: mobileSteps,
+                healedAppiumCode: "",
+                healReason: "recovered on reproduce",
+                verdict: "fix",
+                recovered: true,
+                priorStepsHash: run2.priorStepsHash
+              });
+              log.ok("\u{1FA7A} Reproduce PASSED \u2014 test recovered (flaky); promotion posted");
+            } catch (patchErr) {
+              log.warn(`Failed to post recovered heal result: ${patchErr instanceof Error ? patchErr.message : String(patchErr)}`);
+            }
+            return;
+          }
+          const reproduceError = reproduce.error;
+          const modelOverride = run2.healerModel ?? void 0;
+          const healerOptions = {
+            aiClient: modelOverride ? (0, import_runner_core13.getMobileClientForModel)(modelOverride) : (0, import_runner_core13.getMobileAIClient)(),
+            ...modelOverride ? { model: modelOverride } : {},
+            runNativeTest,
+            selectorRegistryContext: run2.selectorRegistryContext ?? null,
+            runLiveHeal: async (a) => {
+              let liveSession = null;
+              try {
+                liveSession = await createMobileDiscoverySession({
+                  appId: target.appId,
+                  platform: target.platform,
+                  platformVersion: target.platformVersion,
+                  recordedDeviceId: target.recordedDeviceId,
+                  assignedDeviceId,
+                  launchMode: target.launchMode,
+                  deeplink: target.deeplink
+                });
+                attachMirrorSession(liveSession.sessionId, target.platform, liveSession.deviceId);
+                const bridgeDriver = new MobileBridgeDriver({
+                  sessionId: liveSession.sessionId,
+                  platform: target.platform,
+                  appId: liveSession.appId,
+                  allowAppReset: shouldResetMobileAppData(target.platform, liveSession.deviceId)
+                });
+                const liveDriver = {
+                  snapshot: async () => {
+                    const snap = await bridgeDriver.snapshot();
+                    return { xml: snap.xml, screenshot: snap.screenshot, windowSize: snap.windowSize };
+                  },
+                  tap: async (bounds) => {
+                    await bridgeDriver.tap(bounds);
+                  },
+                  type: async (value, bounds) => {
+                    await bridgeDriver.type(value, bounds);
+                  },
+                  clear: async (bounds) => {
+                    await bridgeDriver.clear(bounds);
+                  },
+                  swipe: async (direction, distance) => {
+                    await bridgeDriver.swipe(direction, distance);
+                  },
+                  back: async () => {
+                    await bridgeDriver.back();
+                  },
+                  home: async () => {
+                    await bridgeDriver.home();
+                  },
+                  relaunch: async () => {
+                    await bridgeDriver.relaunch();
+                  },
+                  resetAppState: async () => bridgeDriver.resetAppState()
+                };
+                return await (0, import_runner_core13.executeMobileLiveHeal)({
+                  steps: a.steps,
+                  target: a.target,
+                  testVariables: a.testVariables,
+                  priorError: reproduceError,
+                  options: { ...a.options ?? healerOptions, liveDriver }
+                });
+              } finally {
+                if (liveSession) {
+                  detachMirrorSession(liveSession.deviceId);
+                  try {
+                    await liveSession.stop();
+                  } catch {
+                  }
+                }
+              }
+            }
+          };
+          log.info("\u{1FA7A} Mobile AI heal \u2014 Phase 1 (script) \u2192 Phase 2 (live device, lazy)...");
+          const heal = await (0, import_runner_core13.executeMobileTestWithHealing)(
+            mobileSteps,
+            healTarget,
+            { error: reproduceError, logs: reproduce.logs, failingSource: reproduce.failingSource, testVariables: run2.testVariables },
+            healerOptions
+          );
+          const finalRes = nativeVerify.last;
+          const outcome = (0, import_runner_core13.computeMobileHealOutcome)({
+            heal,
+            finalError: finalRes?.error ?? null,
+            reproduceError,
+            testVariables: run2.testVariables
+          });
+          await postResult(opts.serverUrl, headers, run2.runId, {
+            status: outcome.status,
+            stepResults: finalRes?.stepResults,
+            screenshots: finalRes?.screenshots,
+            video: finalRes?.video,
+            videoMimeType: finalRes?.videoMimeType,
+            apiCalls: finalRes?.apiCalls,
+            logs: finalRes?.logs,
+            error: outcome.error,
+            healReason: heal.healReason,
+            // NB: the loop's numeric `confidence` (0-1) is intentionally NOT posted
+            // here — RunnerResultPayload.confidence is the web healer's categorical
+            // 'high'|'medium'|'low'. The numeric value rides /mobile-heal-result via
+            // the healReason instead. Mapping the two would be lossy and misleading.
+            // extraTags carries @needs-review for the non-fix verdicts (applied by
+            // the server's mobileAiHeal /result tag hook); PASSED heals apply tags
+            // via /mobile-heal-result instead.
+            extraTags: outcome.extraTags,
+            removeTags: outcome.removeTags,
+            duration: Date.now() - startTime,
+            failingSource: finalRes?.failingSource
+          });
+          if (outcome.shouldPatch && heal.healedSteps && heal.healedSteps.length > 0) {
+            const healedAppiumCode = heal.healedAppiumCode ?? buildAppiumCode(run2.testName ?? run2.testCaseId ?? "Healed mobile test", run2.target ?? null, heal.healedSteps);
+            try {
+              await postMobileHealResult(opts.serverUrl, headers, run2.runId, {
+                healedSteps: heal.healedSteps,
+                healedAppiumCode,
+                healReason: heal.healReason ?? "",
+                verdict: heal.verdict,
+                extraTags: heal.extraTags,
+                removeTags: heal.removeTags,
+                priorStepsHash: run2.priorStepsHash
+              });
+              log.ok(`\u{1FA7A} Mobile heal patch posted for test ${run2.testCaseId ?? "(unknown)"} (verdict: ${heal.verdict})`);
+            } catch (patchErr) {
+              log.warn(`Failed to post mobile heal patch: ${patchErr instanceof Error ? patchErr.message : String(patchErr)}`);
+            }
+          } else if (outcome.secretLeak) {
+            log.warn(`\u{1FA7A} Mobile heal patch DROPPED \u2014 healed steps contained a secret (${outcome.secretLeak}); tagged @needs-review`);
+          }
+          const duration3 = Date.now() - startTime;
+          log[outcome.status === "PASSED" ? "ok" : "fail"](
+            `\u{1FA7A} Mobile AI heal ${outcome.status} (verdict: ${heal.verdict}, ${duration3}ms)${outcome.error ? ` - ${outcome.error}` : ""}`
+          );
+        } finally {
+          setExecutorBusy(false);
+        }
+        return;
+      }
       const maxRetries = typeof run2.retryCount === "number" && Number.isFinite(run2.retryCount) ? Math.max(0, Math.min(2, Math.floor(run2.retryCount))) : 0;
       setExecutorBusy(true);
       let result2 = null;
@@ -335560,7 +335833,10 @@ ${result2.logs}`);
         apiCalls: result2.apiCalls,
         logs: result2.logs,
         error: reportedError,
-        duration: duration2
+        duration: duration2,
+        // Point-of-failure page-source XML (mobile) for the AI healer. Budget-
+        // droppable (see result-payload-budget.ts); the verdict is never dropped.
+        failingSource: result2.failingSource
       });
       log[result2.passed ? "ok" : "fail"](
         `\u{1F4F1} ${status}  (${duration2}ms)${reportedError ? ` - ${reportedError}` : ""}`

package/dist/cli.mjs

@@ -250,8 +250,8 @@ var require_ai_provider = __commonJS({
     exports.resetAIClient = resetAIClient;
     exports.getServerProxiedAIClient = getServerProxiedAIClient;
     exports.getServerProxiedClientForModel = getServerProxiedClientForModel;
-    exports.getMobileAIClient = getMobileAIClient;
-    exports.getMobileClientForModel = getMobileClientForModel;
+    exports.getMobileAIClient = getMobileAIClient2;
+    exports.getMobileClientForModel = getMobileClientForModel2;
     var openai_1 = __importDefault(__require("openai"));
     var async_hooks_1 = __require("async_hooks");
     var ai_retry_js_1 = require_ai_retry();
@@ -648,14 +648,14 @@ var require_ai_provider = __commonJS({
     function getServerProxiedClientForModel(_modelId) {
       return getServerProxiedAIClient();
     }
-    function getMobileAIClient() {
+    function getMobileAIClient2() {
       if ((process.env.SERVER_URL ?? "").trim().length > 0)
         return getServerProxiedAIClient();
       if (isMobileAiUnitTestMode())
         return getAIClient();
       throw new Error("Mobile AI requires the platform server URL (SERVER_URL). Customer runners do not provision provider API keys \u2014 the platform proxies every mobile AI completion through /api/runner/ai/execute, which lives on the shared server with the keys. If you reached this from `validate-runner start`, the credentials file is missing `serverUrl` or the install is broken; re-run `npx @validate.qa/runner login`. If you are calling the runner-core library directly, pass `options.aiClient` in tests or set VALIDATEQA_TEST_MODE=1 to opt into the local-provider fallback.");
     }
-    function getMobileClientForModel(modelId) {
+    function getMobileClientForModel2(modelId) {
       if ((process.env.SERVER_URL ?? "").trim().length > 0)
         return getServerProxiedClientForModel(modelId);
       if (isMobileAiUnitTestMode())
@@ -328488,7 +328488,7 @@ var require_package4 = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@validate.qa/runner",
-      version: "1.0.22",
+      version: "1.0.24",
       description: "validate local test runner - execute Playwright tests on your machine, connected to validate.qa cloud.",
       bin: {
         "validate-runner": "dist/cli.js"
@@ -330264,6 +330264,7 @@ var MOBILE_NEW_COMMAND_TIMEOUT_SECONDS = (() => {
   const raw = Number(process.env.VALIDATEQA_MOBILE_NEW_COMMAND_TIMEOUT);
   return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 600;
 })();
+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_ACTION_TIMEOUT_MS = 3e4;
@@ -330498,18 +330499,24 @@ async function freshLaunchTargetApp(sessionId, platform3, appId, log2) {
 }
 async function waitForColdBootContent(sessionId, log2, timeoutMs = 2e4) {
   const deadline = Date.now() + timeoutMs;
-  const MIN_ELEMENTS = 3;
+  const MIN_ELEMENTS = 12;
   let lastCount = 0;
+  let stableFrames = 0;
   while (Date.now() < deadline) {
     try {
       const res = await wdRequest(`/session/${sessionId}/source`);
       const xml = typeof res?.value === "string" ? res.value : "";
       const count = (xml.match(/<(android\.|XCUIElementType)/g) ?? []).length;
-      lastCount = count;
-      if (count >= MIN_ELEMENTS) {
-        log2(`  Cold-boot ready: UI tree has ${count} node(s).`);
-        return;
+      if (count >= MIN_ELEMENTS && count === lastCount) {
+        stableFrames++;
+        if (stableFrames >= 2) {
+          log2(`  Cold-boot ready: UI tree settled at ${count} node(s).`);
+          return;
+        }
+      } else {
+        stableFrames = 0;
       }
+      lastCount = count;
     } catch {
     }
     await new Promise((r) => setTimeout(r, 750));
@@ -330553,6 +330560,14 @@ async function takeScreenshot(sessionId) {
     return null;
   }
 }
+async function captureFailingSource(sessionId) {
+  try {
+    const result = await wdRequest(`/session/${sessionId}/source`);
+    return typeof result?.value === "string" ? result.value : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function mobileRecordingEnabled() {
   const value = process.env.VALIDATEQA_MOBILE_RUN_VIDEO;
   return value !== "0" && value !== "false";
@@ -330682,9 +330697,12 @@ function identityTextXpath(value) {
   const lit = xpathLiteral(value);
   return `//*[@text=${lit} or @content-desc=${lit} or @label=${lit} or @name=${lit} or @value=${lit}]`;
 }
+function isIdentityXpath(value) {
+  return value.includes("@") && !/(?:contains|starts-with)\s*\(/i.test(value);
+}
 function isIdentityStrategy(strategy) {
   if (strategy.using === "accessibility id" || strategy.using === "id") return true;
-  if (strategy.using === "xpath") return strategy.value.includes("@");
+  if (strategy.using === "xpath") return isIdentityXpath(strategy.value);
   return false;
 }
 function buildIdentityLocatorStrategies(target, platform3) {
@@ -330698,7 +330716,7 @@ function buildIdentityLocatorStrategies(target, platform3) {
       const trimmed = value?.trim();
       if (trimmed) strategies.push({ using: "xpath", value: identityTextXpath(trimmed) });
     }
-    if (bundle.xpath && bundle.xpath.includes("@")) strategies.push({ using: "xpath", value: bundle.xpath });
+    if (bundle.xpath && isIdentityXpath(bundle.xpath)) strategies.push({ using: "xpath", value: bundle.xpath });
   }
   if (!(platform3 && hasPlatformLocator(target, platform3))) {
     for (const value of [target.primary, ...target.fallbacks ?? []]) {
@@ -331045,6 +331063,7 @@ async function executeMobileTest(options) {
   let recordingStarted = false;
   let recordingStopped = false;
   let video;
+  let failingSource;
   const stopCapture = async () => {
     if (!capture || captureStopped) return apiCalls;
     captureStopped = true;
@@ -331068,6 +331087,10 @@ async function executeMobileTest(options) {
     }
     return video;
   };
+  const recordFirstFailingSource = async () => {
+    if (failingSource != null || !sessionId) return;
+    failingSource = await captureFailingSource(sessionId);
+  };
   try {
     log2("Checking Appium server health...");
     const health = await checkAppiumHealth();
@@ -331194,12 +331217,14 @@ async function executeMobileTest(options) {
     );
     if (entryStep) {
       try {
-        await findElement(sessionId, entryStep.target, DEFAULT_STEP_TIMEOUT_MS, { identityOnly: true, platform: runPlatform });
+        const entryTimeout = recordedFromClearedState ? Math.max(DEFAULT_STEP_TIMEOUT_MS, COLD_BOOT_ENTRY_TIMEOUT_MS) : DEFAULT_STEP_TIMEOUT_MS;
+        await findElement(sessionId, entryStep.target, entryTimeout, { identityOnly: true, platform: runPlatform });
       } catch (err) {
         if (isTransportError(err)) throw err;
         entryDrift = true;
         const driftMsg = `App started on an unexpected screen \u2014 the recorded flow's first element ("${entryStep.target?.primary ?? entryStep.description}") is not present, so the replay was aborted before it could blind-tap stale coordinates (screen drift; the app may be on onboarding or a different screen than when the test was recorded).`;
         log2(`  \u2717 Entry-screen drift: ${driftMsg}`);
+        await recordFirstFailingSource();
         stepResults.push({ stepOrder: entryStep.order, status: "failed", duration: 0, error: driftMsg });
         const driftShot = await takeScreenshot(sessionId).catch(() => null);
         screenshots.push(driftShot ?? "");
@@ -331276,6 +331301,9 @@ async function executeMobileTest(options) {
       }
       const screenshot = await takeScreenshot(sessionId).catch(() => null);
       screenshots.push(screenshot ?? "");
+      if (status === "failed") {
+        await recordFirstFailingSource();
+      }
       stepResults.push({
         stepOrder: step.order,
         status,
@@ -331313,7 +331341,8 @@ async function executeMobileTest(options) {
       duration: Date.now() - startTime,
       deviceId: selectedDevice?.id,
       deviceName: selectedDevice?.name,
-      environmental: environmental ?? void 0
+      environmental: environmental ?? void 0,
+      failingSource
     };
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
@@ -331334,7 +331363,8 @@ async function executeMobileTest(options) {
       // A throw before/around the step loop is a setup/environment problem
       // (no device booted, app not installed, session could not be created,
       // Appium unreachable) — never a genuine test assertion failure.
-      environmental: errorMsg
+      environmental: errorMsg,
+      failingSource
     };
   } finally {
     await stopCapture();
@@ -333303,6 +333333,9 @@ function budgetResultPayload(result, maxBytes = RESULT_BODY_BUDGET_BYTES, videoS
   if ((bytes > maxBytes || oversizedVideo) && payload.video != null) {
     drop(["video", "videoMimeType"], "video");
   }
+  if (bytes > maxBytes && payload.failingSource != null) {
+    drop(["failingSource"], "failingSource");
+  }
   if (bytes > maxBytes && Array.isArray(payload.screenshots) && payload.screenshots.length > 0) {
     const shots = [...payload.screenshots];
     const bySizeDesc = shots.map((shot, i) => ({ i, len: typeof shot === "string" ? shot.length : 0 })).sort((a, b) => b.len - a.len);
@@ -333354,6 +333387,7 @@ ${tail}` };
 // src/runner.ts
 init_dist();
 var import_runner_core12 = __toESM(require_dist2());
+var import_runner_core13 = __toESM(require_dist2());
 function fingerprintTest(test) {
   const code = test.framework === "APPIUM" ? [test.appiumCode ?? "", JSON.stringify(test.steps ?? [])].join("\n--steps--\n") : test.playwrightCode ?? "";
   return createHash("sha256").update(test.name).update("\n--suite--\n").update(test.suiteName ?? "").update("\n--type--\n").update(test.testType ?? "").update("\n--framework--\n").update(test.framework ?? "").update("\n--code--\n").update(code).digest("hex").slice(0, 24);
@@ -333591,6 +333625,33 @@ async function postHealResult(serverUrl, headers, runId, healedCode, testCaseId,
   }
   throw new Error(`Failed to post heal result after ${MAX_ATTEMPTS} attempts: ${lastError?.message}`);
 }
+async function postMobileHealResult(serverUrl, headers, runId, body) {
+  const MAX_ATTEMPTS = 3;
+  let lastError;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    try {
+      const res = await fetch(`${serverUrl}/api/runner/runs/${runId}/mobile-heal-result`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(6e4)
+      });
+      if (res.ok) return;
+      lastError = new Error(`HTTP ${res.status}`);
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+    }
+    if (attempt < MAX_ATTEMPTS) {
+      const delay = Math.pow(2, attempt) * 1e3;
+      console.warn(`[runner] postMobileHealResult attempt ${attempt} failed (${lastError.message}), retrying in ${delay}ms...`);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+  throw new Error(`Failed to post mobile heal result after ${MAX_ATTEMPTS} attempts: ${lastError?.message}`);
+}
+function narrowMobileLaunchMode(mode) {
+  return mode === "LAUNCH_APP" || mode === "DEEP_LINK" || mode === "RESUME" ? mode : void 0;
+}
 async function postBatchHealResult(serverUrl, headers, runId, body) {
   const res = await fetch(`${serverUrl}/api/runner/runs/${runId}/batch-heal-result`, {
     method: "POST",
@@ -335499,6 +335560,218 @@ ${finalVerifyResult.logs ?? ""}`;
         log.fail("ERROR - No mobile steps");
         return;
       }
+      if (runMode === "heal" && run2.mobileAiHeal === true) {
+        if (getBridgeState().hasActiveSession) {
+          await postResult(opts.serverUrl, headers, run2.runId, {
+            status: "ERROR",
+            error: "CONFIG_ISSUE: the shared mobile device is busy with an active recording session; the AI heal will retry once it ends.",
+            duration: Date.now() - startTime
+          });
+          log.warn("Skipped mobile AI heal (device busy with a recording)");
+          return;
+        }
+        const healTarget = {
+          appId: target.appId,
+          platform: target.platform,
+          platformVersion: target.platformVersion,
+          recordedDeviceId: target.recordedDeviceId,
+          assignedDeviceId,
+          launchMode: target.launchMode,
+          deeplink: target.deeplink,
+          authoringPlatform: mobilePlatformFromMedium(run2.authoringMedium) ?? void 0
+        };
+        const nativeVerify = { last: null };
+        const runNativeTest = async ({ steps, target: t, testVariables }) => {
+          const res = await executeMobileTest({
+            steps,
+            target: {
+              appId: t.appId,
+              platform: t.platform,
+              platformVersion: t.platformVersion,
+              recordedDeviceId: t.recordedDeviceId,
+              assignedDeviceId: t.assignedDeviceId,
+              launchMode: narrowMobileLaunchMode(t.launchMode),
+              deeplink: t.deeplink,
+              authoringPlatform: t.authoringPlatform
+            },
+            testVariables
+          });
+          nativeVerify.last = res;
+          return {
+            passed: res.passed,
+            error: res.error,
+            stepResults: res.stepResults.map((s) => ({ stepOrder: s.stepOrder, status: s.status, error: s.error })),
+            failingSource: res.failingSource,
+            logs: res.logs
+          };
+        };
+        setExecutorBusy(true);
+        try {
+          log.info("\u{1FA7A} Mobile AI heal \u2014 reproducing the failure on device...");
+          const reproduce = await runNativeTest({ steps: mobileSteps, target: healTarget, testVariables: run2.testVariables });
+          if (reproduce.passed) {
+            const recovered = nativeVerify.last;
+            await postResult(opts.serverUrl, headers, run2.runId, {
+              status: "PASSED",
+              stepResults: recovered?.stepResults,
+              screenshots: recovered?.screenshots,
+              video: recovered?.video,
+              videoMimeType: recovered?.videoMimeType,
+              apiCalls: recovered?.apiCalls,
+              logs: recovered?.logs,
+              duration: Date.now() - startTime
+            });
+            try {
+              await postMobileHealResult(opts.serverUrl, headers, run2.runId, {
+                healedSteps: mobileSteps,
+                healedAppiumCode: "",
+                healReason: "recovered on reproduce",
+                verdict: "fix",
+                recovered: true,
+                priorStepsHash: run2.priorStepsHash
+              });
+              log.ok("\u{1FA7A} Reproduce PASSED \u2014 test recovered (flaky); promotion posted");
+            } catch (patchErr) {
+              log.warn(`Failed to post recovered heal result: ${patchErr instanceof Error ? patchErr.message : String(patchErr)}`);
+            }
+            return;
+          }
+          const reproduceError = reproduce.error;
+          const modelOverride = run2.healerModel ?? void 0;
+          const healerOptions = {
+            aiClient: modelOverride ? (0, import_runner_core13.getMobileClientForModel)(modelOverride) : (0, import_runner_core13.getMobileAIClient)(),
+            ...modelOverride ? { model: modelOverride } : {},
+            runNativeTest,
+            selectorRegistryContext: run2.selectorRegistryContext ?? null,
+            runLiveHeal: async (a) => {
+              let liveSession = null;
+              try {
+                liveSession = await createMobileDiscoverySession({
+                  appId: target.appId,
+                  platform: target.platform,
+                  platformVersion: target.platformVersion,
+                  recordedDeviceId: target.recordedDeviceId,
+                  assignedDeviceId,
+                  launchMode: target.launchMode,
+                  deeplink: target.deeplink
+                });
+                attachMirrorSession(liveSession.sessionId, target.platform, liveSession.deviceId);
+                const bridgeDriver = new MobileBridgeDriver({
+                  sessionId: liveSession.sessionId,
+                  platform: target.platform,
+                  appId: liveSession.appId,
+                  allowAppReset: shouldResetMobileAppData(target.platform, liveSession.deviceId)
+                });
+                const liveDriver = {
+                  snapshot: async () => {
+                    const snap = await bridgeDriver.snapshot();
+                    return { xml: snap.xml, screenshot: snap.screenshot, windowSize: snap.windowSize };
+                  },
+                  tap: async (bounds) => {
+                    await bridgeDriver.tap(bounds);
+                  },
+                  type: async (value, bounds) => {
+                    await bridgeDriver.type(value, bounds);
+                  },
+                  clear: async (bounds) => {
+                    await bridgeDriver.clear(bounds);
+                  },
+                  swipe: async (direction, distance) => {
+                    await bridgeDriver.swipe(direction, distance);
+                  },
+                  back: async () => {
+                    await bridgeDriver.back();
+                  },
+                  home: async () => {
+                    await bridgeDriver.home();
+                  },
+                  relaunch: async () => {
+                    await bridgeDriver.relaunch();
+                  },
+                  resetAppState: async () => bridgeDriver.resetAppState()
+                };
+                return await (0, import_runner_core13.executeMobileLiveHeal)({
+                  steps: a.steps,
+                  target: a.target,
+                  testVariables: a.testVariables,
+                  priorError: reproduceError,
+                  options: { ...a.options ?? healerOptions, liveDriver }
+                });
+              } finally {
+                if (liveSession) {
+                  detachMirrorSession(liveSession.deviceId);
+                  try {
+                    await liveSession.stop();
+                  } catch {
+                  }
+                }
+              }
+            }
+          };
+          log.info("\u{1FA7A} Mobile AI heal \u2014 Phase 1 (script) \u2192 Phase 2 (live device, lazy)...");
+          const heal = await (0, import_runner_core13.executeMobileTestWithHealing)(
+            mobileSteps,
+            healTarget,
+            { error: reproduceError, logs: reproduce.logs, failingSource: reproduce.failingSource, testVariables: run2.testVariables },
+            healerOptions
+          );
+          const finalRes = nativeVerify.last;
+          const outcome = (0, import_runner_core13.computeMobileHealOutcome)({
+            heal,
+            finalError: finalRes?.error ?? null,
+            reproduceError,
+            testVariables: run2.testVariables
+          });
+          await postResult(opts.serverUrl, headers, run2.runId, {
+            status: outcome.status,
+            stepResults: finalRes?.stepResults,
+            screenshots: finalRes?.screenshots,
+            video: finalRes?.video,
+            videoMimeType: finalRes?.videoMimeType,
+            apiCalls: finalRes?.apiCalls,
+            logs: finalRes?.logs,
+            error: outcome.error,
+            healReason: heal.healReason,
+            // NB: the loop's numeric `confidence` (0-1) is intentionally NOT posted
+            // here — RunnerResultPayload.confidence is the web healer's categorical
+            // 'high'|'medium'|'low'. The numeric value rides /mobile-heal-result via
+            // the healReason instead. Mapping the two would be lossy and misleading.
+            // extraTags carries @needs-review for the non-fix verdicts (applied by
+            // the server's mobileAiHeal /result tag hook); PASSED heals apply tags
+            // via /mobile-heal-result instead.
+            extraTags: outcome.extraTags,
+            removeTags: outcome.removeTags,
+            duration: Date.now() - startTime,
+            failingSource: finalRes?.failingSource
+          });
+          if (outcome.shouldPatch && heal.healedSteps && heal.healedSteps.length > 0) {
+            const healedAppiumCode = heal.healedAppiumCode ?? buildAppiumCode(run2.testName ?? run2.testCaseId ?? "Healed mobile test", run2.target ?? null, heal.healedSteps);
+            try {
+              await postMobileHealResult(opts.serverUrl, headers, run2.runId, {
+                healedSteps: heal.healedSteps,
+                healedAppiumCode,
+                healReason: heal.healReason ?? "",
+                verdict: heal.verdict,
+                extraTags: heal.extraTags,
+                removeTags: heal.removeTags,
+                priorStepsHash: run2.priorStepsHash
+              });
+              log.ok(`\u{1FA7A} Mobile heal patch posted for test ${run2.testCaseId ?? "(unknown)"} (verdict: ${heal.verdict})`);
+            } catch (patchErr) {
+              log.warn(`Failed to post mobile heal patch: ${patchErr instanceof Error ? patchErr.message : String(patchErr)}`);
+            }
+          } else if (outcome.secretLeak) {
+            log.warn(`\u{1FA7A} Mobile heal patch DROPPED \u2014 healed steps contained a secret (${outcome.secretLeak}); tagged @needs-review`);
+          }
+          const duration3 = Date.now() - startTime;
+          log[outcome.status === "PASSED" ? "ok" : "fail"](
+            `\u{1FA7A} Mobile AI heal ${outcome.status} (verdict: ${heal.verdict}, ${duration3}ms)${outcome.error ? ` - ${outcome.error}` : ""}`
+          );
+        } finally {
+          setExecutorBusy(false);
+        }
+        return;
+      }
       const maxRetries = typeof run2.retryCount === "number" && Number.isFinite(run2.retryCount) ? Math.max(0, Math.min(2, Math.floor(run2.retryCount))) : 0;
       setExecutorBusy(true);
       let result2 = null;
@@ -335568,7 +335841,10 @@ ${result2.logs}`);
         apiCalls: result2.apiCalls,
         logs: result2.logs,
         error: reportedError,
-        duration: duration2
+        duration: duration2,
+        // Point-of-failure page-source XML (mobile) for the AI healer. Budget-
+        // droppable (see result-payload-budget.ts); the verdict is never dropped.
+        failingSource: result2.failingSource
       });
       log[result2.passed ? "ok" : "fail"](
         `\u{1F4F1} ${status}  (${duration2}ms)${reportedError ? ` - ${reportedError}` : ""}`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@validate.qa/runner",
-  "version": "1.0.22",
+  "version": "1.0.24",
   "description": "validate local test runner - execute Playwright tests on your machine, connected to validate.qa cloud.",
   "bin": {
     "validate-runner": "dist/cli.js"