@validate.qa/runner 1.0.66 → 1.0.68

package/dist/cli.mjs

@@ -983,7 +983,7 @@ var require_mobile_source_parser = __commonJS({
       const value = nonEmpty3(attrs.value);
       const label = name ?? labelAttr ?? value;
       const accessibilityId = name;
-      const text = value && value !== label ? value : labelAttr && labelAttr !== label ? labelAttr : void 0;
+      const text = labelAttr ?? (isStateValueRole(role) ? void 0 : value);
       const bounds = parseIOSBounds(attrs);
       const enabled = attrBoolDefaultTrue(attrs.enabled);
       const visible = attrBoolDefaultTrue(attrs.visible);
@@ -1130,6 +1130,42 @@ var require_mobile_source_parser = __commonJS({
         }
       }
     }
+    function annotateIdentityUniqueness(elements) {
+      const a11yCounts = /* @__PURE__ */ new Map();
+      const ridCounts = /* @__PURE__ */ new Map();
+      const textCounts = /* @__PURE__ */ new Map();
+      const bump = (map2, value) => {
+        const key = value?.trim();
+        if (!key)
+          return;
+        map2.set(key, (map2.get(key) ?? 0) + 1);
+      };
+      for (const element of elements) {
+        bump(a11yCounts, element.accessibilityId);
+        bump(ridCounts, element.resourceId);
+        const identityValues = new Set([element.text, element.accessibilityId].map((value) => value?.trim()).filter((value) => Boolean(value)));
+        for (const value of identityValues)
+          bump(textCounts, value);
+      }
+      const isUnique = (map2, value) => {
+        const key = value?.trim();
+        if (!key)
+          return void 0;
+        return (map2.get(key) ?? 0) <= 1;
+      };
+      for (const element of elements) {
+        const accessibilityId = isUnique(a11yCounts, element.accessibilityId);
+        const resourceId = isUnique(ridCounts, element.resourceId);
+        const text = isUnique(textCounts, element.text);
+        if (accessibilityId === void 0 && resourceId === void 0 && text === void 0)
+          continue;
+        element.identityUnique = {
+          ...accessibilityId !== void 0 ? { accessibilityId } : {},
+          ...resourceId !== void 0 ? { resourceId } : {},
+          ...text !== void 0 ? { text } : {}
+        };
+      }
+    }
     function flatten(root, platform3) {
       const out = [];
       const stack = [];
@@ -1175,6 +1211,7 @@ var require_mobile_source_parser = __commonJS({
         }
       }
       markRepeatedBottomBarNavigation(out);
+      annotateIdentityUniqueness(out);
       return out;
     }
     function fnv1a(input) {
@@ -1256,6 +1293,13 @@ var require_mobile_source_parser = __commonJS({
     function isEditableElement(el) {
       return EDITABLE_CLASS_RE.test(el.role.trim());
     }
+    var STATE_VALUE_CLASS_RE = /(XCUIElementTypeSwitch|XCUIElementTypeToggle|XCUIElementTypeSlider|XCUIElementTypeStepper|XCUIElementTypePageIndicator|XCUIElementTypeProgressIndicator|XCUIElementTypeSegmentedControl|XCUIElementTypePicker|XCUIElementTypePickerWheel|ToggleButton|SeekBar|ProgressBar|RatingBar|NumberPicker)$/;
+    function isStateValueRole(role) {
+      return STATE_VALUE_CLASS_RE.test(role.trim());
+    }
+    function isStateValueElement(el) {
+      return isStateValueRole(el.role);
+    }
     function xpathAttrLiteral(value) {
       if (!value.includes("'"))
         return `'${value}'`;
@@ -1266,17 +1310,18 @@ var require_mobile_source_parser = __commonJS({
     function semanticXPath(el, platform3) {
       const cls = nonBlank(el.role) ?? "*";
       const a11y = nonBlank(el.accessibilityId);
-      if (a11y) {
-        return platform3 === "ANDROID" ? `//${cls}[@content-desc=${xpathAttrLiteral(a11y)}]` : `//${cls}[@name=${xpathAttrLiteral(a11y)}]`;
-      }
-      const rid = nonBlank(el.resourceId);
-      if (platform3 === "ANDROID" && rid)
-        return `//${cls}[@resource-id=${xpathAttrLiteral(rid)}]`;
-      const text = nonBlank(el.text);
-      if (text && !isEditableElement(el)) {
-        return platform3 === "ANDROID" ? `//${cls}[@text=${xpathAttrLiteral(text)}]` : `//${cls}[@label=${xpathAttrLiteral(text)}]`;
-      }
-      return void 0;
+      const rid = platform3 === "ANDROID" ? nonBlank(el.resourceId) : void 0;
+      const text = isEditableElement(el) || isStateValueElement(el) ? void 0 : nonBlank(el.text);
+      const a11yXpath = a11y ? platform3 === "ANDROID" ? `//${cls}[@content-desc=${xpathAttrLiteral(a11y)}]` : `//${cls}[@name=${xpathAttrLiteral(a11y)}]` : void 0;
+      const ridXpath = rid ? `//${cls}[@resource-id=${xpathAttrLiteral(rid)}]` : void 0;
+      const textXpath = text ? platform3 === "ANDROID" ? `//${cls}[@text=${xpathAttrLiteral(text)}]` : `//${cls}[@label=${xpathAttrLiteral(text)}]` : void 0;
+      const candidates = [
+        { xpath: a11yXpath, unique: el.identityUnique?.accessibilityId },
+        { xpath: ridXpath, unique: el.identityUnique?.resourceId },
+        { xpath: textXpath, unique: el.identityUnique?.text }
+      ];
+      const uniqueFirst = candidates.find((c) => c.xpath && c.unique !== false);
+      return (uniqueFirst ?? candidates.find((c) => c.xpath))?.xpath;
     }
     function nonBlank(value) {
       if (typeof value !== "string")
@@ -1285,30 +1330,40 @@ var require_mobile_source_parser = __commonJS({
       return trimmed.length > 0 ? trimmed : void 0;
     }
     function buildLocatorBundle(el, platform3) {
+      const durableText = el.text && !isEditableElement(el) && !isStateValueElement(el) ? el.text : void 0;
       const bundle = {
         // Attribute-anchored xpath when the element has identity; the absolute
         // indexed path only for identity-less elements (nothing else can find them).
         xpath: semanticXPath(el, platform3) ?? el.xpath,
         className: el.role
       };
-      if (el.accessibilityId)
+      const a11yUnique = el.identityUnique?.accessibilityId !== false;
+      const ridUnique = el.identityUnique?.resourceId !== false;
+      const textUnique = el.identityUnique?.text !== false;
+      const hasUniqueAlternativeToA11y = Boolean(el.resourceId && platform3 === "ANDROID" && ridUnique || durableText && textUnique);
+      const hasUniqueAlternativeToRid = Boolean(el.accessibilityId && a11yUnique || durableText && textUnique);
+      const includeA11y = Boolean(el.accessibilityId && (a11yUnique || !hasUniqueAlternativeToA11y));
+      const includeRid = Boolean(platform3 === "ANDROID" && el.resourceId && (ridUnique || !hasUniqueAlternativeToRid));
+      if (includeA11y && el.accessibilityId)
         bundle.accessibilityId = el.accessibilityId;
-      if (platform3 === "ANDROID" && el.resourceId)
+      if (includeRid && el.resourceId)
         bundle.resourceId = el.resourceId;
-      if (el.text && !isEditableElement(el))
-        bundle.text = el.text;
-      if (platform3 === "ANDROID" && el.accessibilityId)
+      if (durableText)
+        bundle.text = durableText;
+      if (includeA11y && platform3 === "ANDROID" && el.accessibilityId)
         bundle.contentDesc = el.accessibilityId;
       return bundle;
     }
     function preferredLocator(el) {
-      if (el.accessibilityId)
-        return el.accessibilityId;
-      if (el.resourceId)
-        return el.resourceId;
-      if (el.text && !isEditableElement(el))
-        return el.text;
-      return el.xpath;
+      const durableText = el.text && !isEditableElement(el) && !isStateValueElement(el) ? el.text : void 0;
+      const candidates = [
+        { value: el.accessibilityId, unique: el.identityUnique?.accessibilityId },
+        { value: el.resourceId, unique: el.identityUnique?.resourceId },
+        { value: durableText, 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;
     }
     function buildScreenSignal(elements, root, platform3) {
       const signal = {
@@ -1971,6 +2026,11 @@ function isEditableMobileClassName(className) {
     return false;
   return /(EditText|AutoCompleteTextView|XCUIElementTypeTextField|XCUIElementTypeSecureTextField|XCUIElementTypeSearchField|XCUIElementTypeTextView)$/.test(className.trim());
 }
+function isStateValueMobileClassName(className) {
+  if (!className)
+    return false;
+  return /(XCUIElementTypeSwitch|XCUIElementTypeToggle|XCUIElementTypeSlider|XCUIElementTypeStepper|XCUIElementTypePageIndicator|XCUIElementTypeProgressIndicator|XCUIElementTypeSegmentedControl|XCUIElementTypePicker|XCUIElementTypePickerWheel|ToggleButton|SeekBar|ProgressBar|RatingBar|NumberPicker)$/.test(className.trim());
+}
 function mobileCredentialPlaceholder(key) {
   return `{{${key}}}`;
 }
@@ -2100,9 +2160,10 @@ function buildStepTarget(metadata, selector) {
     locatorBundle.resourceId,
     // For editable fields the text attribute IS the currently-typed value — a
     // self-invalidating locator that only matches while the recorded text is
-    // still in the field (and it can leak typed input into locators). Static
-    // elements keep their text fallback.
-    isEditableMobileClassName(locatorBundle.className) ? void 0 : locatorBundle.text,
+    // still in the field (and it can leak typed input into locators). State
+    // controls' text is their current state ("1"/"ON") and collides with every
+    // same-state sibling. Static elements keep their text fallback.
+    isEditableMobileClassName(locatorBundle.className) || isStateValueMobileClassName(locatorBundle.className) ? void 0 : locatorBundle.text,
     locatorBundle.contentDesc,
     locatorBundle.xpath,
     selector
@@ -2241,12 +2302,26 @@ function selectorForValue(value) {
 function isIdentityMobileXpath(value) {
   return /@[A-Za-z_:][-A-Za-z0-9_:.]*\s*=/.test(value) && !/(?:contains|starts-with)\s*\(/i.test(value);
 }
+function xpathLiteral(value) {
+  if (!value.includes("'"))
+    return `'${value}'`;
+  if (!value.includes('"'))
+    return `"${value}"`;
+  const parts = value.split("'").map((p) => `'${p}'`);
+  return `concat(${parts.join(`, "'", `)})`;
+}
+function identityTextXpath(value) {
+  const lit = xpathLiteral(value);
+  return `//*[@text=${lit} or @content-desc=${lit} or @label=${lit} or @name=${lit} or @value=${lit}]`;
+}
 function mobileLocatorBundleHasIdentity(bundle) {
   if (!bundle)
     return false;
   if (nonEmpty(bundle.accessibilityId) || nonEmpty(bundle.resourceId))
     return true;
-  if (nonEmpty(bundle.text) || nonEmpty(bundle.contentDesc))
+  if (nonEmpty(bundle.text) && !isStateValueMobileClassName(bundle.className))
+    return true;
+  if (nonEmpty(bundle.contentDesc))
     return true;
   const xpath = nonEmpty(bundle.xpath);
   return !!xpath && isIdentityMobileXpath(xpath);
@@ -2269,14 +2344,25 @@ function selectorCandidatesForStep(step) {
       candidates.push(`id=${bundle.resourceId}`);
     if (nonEmpty(bundle.xpath))
       candidates.push(bundle.xpath);
+    const isGateStep = step.action === "waitForElement" || step.action === "assertVisible" || step.action === "assertText";
+    const textIdentity = (isGateStep || !isEditableMobileClassName(bundle.className)) && !isStateValueMobileClassName(bundle.className) ? bundle.text : void 0;
+    for (const value of [textIdentity, bundle.contentDesc]) {
+      const trimmed = nonEmpty(value);
+      if (trimmed)
+        candidates.push(identityTextXpath(trimmed));
+    }
   }
   const hasExplicitResourceId = !!nonEmpty(bundle?.resourceId);
+  const bundleContributedIdentity = candidates.some((value) => !(value.startsWith("/") || value.startsWith("(//")) || isIdentityMobileXpath(value));
   const pushValueCandidates = (value) => {
     candidates.push(selectorForValue(value));
     const looksLikeIdToken = /^[A-Za-z_][\w.:-]*$/.test(value);
     if (!hasExplicitResourceId && looksLikeIdToken && !/^(~|id=|css=|\/|\()/.test(value) && !value.includes(":id/")) {
       candidates.push(`id=${value}`);
     }
+    if (!bundleContributedIdentity && !/^(~|id=|css=|\/|\()/.test(value)) {
+      candidates.push(identityTextXpath(value));
+    }
   };
   if (nonEmpty(target.primary))
     pushValueCandidates(target.primary);
@@ -2715,7 +2801,7 @@ function uniq(values) {
   }
   return result;
 }
-function xpathLiteral(value) {
+function xpathLiteral2(value) {
   if (!value.includes("'"))
     return `'${value}'`;
   if (!value.includes('"'))
@@ -2723,7 +2809,7 @@ function xpathLiteral(value) {
   return `concat(${value.split("'").map((part) => `'${part}'`).join(`, "'", `)})`;
 }
 function mobileTextXPath(value, platform3) {
-  const literal = xpathLiteral(value);
+  const literal = xpathLiteral2(value);
   if (platform3 === "IOS") {
     return `//*[@name=${literal} or @label=${literal} or @value=${literal}]`;
   }
@@ -2971,7 +3057,8 @@ function isWebViewStep(step) {
 function hasCrossPlatformIdentity(bundle) {
   if (!bundle)
     return false;
-  return Boolean(bundle.text?.trim() || bundle.contentDesc?.trim() || bundle.accessibilityId?.trim());
+  const durableText = isStateValueMobileClassName(bundle.className) ? void 0 : bundle.text;
+  return Boolean(durableText?.trim() || bundle.contentDesc?.trim() || bundle.accessibilityId?.trim());
 }
 function stepIsDivergentForPlatform(step, platform3) {
   return Array.isArray(step.crossPlatformDivergent) && step.crossPlatformDivergent.includes(platform3);
@@ -3053,7 +3140,8 @@ function summarizeMobileReadiness(steps, authoringPlatform) {
 function hasStableNativeIdentity(bundle) {
   if (!bundle)
     return false;
-  return Boolean(bundle.accessibilityId?.trim() || bundle.resourceId?.trim() || bundle.text?.trim() || bundle.contentDesc?.trim() || bundle.xpath?.trim() && XPATH_ATTRIBUTE_EQUALITY_RE.test(bundle.xpath) && !/(?:contains|starts-with)\s*\(/i.test(bundle.xpath));
+  const durableText = isStateValueMobileClassName(bundle.className) ? void 0 : bundle.text;
+  return Boolean(bundle.accessibilityId?.trim() || bundle.resourceId?.trim() || durableText?.trim() || bundle.contentDesc?.trim() || bundle.xpath?.trim() && XPATH_ATTRIBUTE_EQUALITY_RE.test(bundle.xpath) && !/(?:contains|starts-with)\s*\(/i.test(bundle.xpath));
 }
 function isPositionalXpath(xpath) {
   const value = xpath?.trim();
@@ -3133,6 +3221,7 @@ var MOBILE_PLATFORMS, LOCATOR_REQUIRING_ACTIONS, XPATH_ATTRIBUTE_EQUALITY_RE;
 var init_mobile_cross_platform = __esm({
   "../shared/dist/mobile-cross-platform.js"() {
     "use strict";
+    init_mobile_test_generation();
     MOBILE_PLATFORMS = ["IOS", "ANDROID"];
     LOCATOR_REQUIRING_ACTIONS = /* @__PURE__ */ new Set([
       "tap",
@@ -3871,6 +3960,43 @@ function accumulateStatements(lines) {
   }
   return out;
 }
+function classifyMobileAssertValue(value, context = {}) {
+  const text = value.trim();
+  if (!text)
+    return null;
+  if (/^\{\{[A-Z0-9_]+\}\}$/.test(text))
+    return null;
+  const t1 = matchFirst(TIER1_PATTERNS, text);
+  if (t1)
+    return { tier: 1, reason: t1[1] };
+  const authIdentityValues = [];
+  if (context.authenticatedUserEmail)
+    authIdentityValues.push(context.authenticatedUserEmail);
+  if (context.authenticatedUserName && context.authenticatedUserName.length >= 3) {
+    authIdentityValues.push(context.authenticatedUserName);
+  }
+  for (const auth of authIdentityValues) {
+    if (auth.length >= 3 && text.toLowerCase().includes(auth.toLowerCase())) {
+      return { tier: 2, reason: "asserts the authenticated user identity \u2014 fails under any other test account" };
+    }
+  }
+  const knownValues = [
+    ...context.knownUserInputs ?? [],
+    ...context.scenarioCreatedValues ?? []
+  ].filter((v) => {
+    for (const auth of authIdentityValues) {
+      if (auth.length >= 3 && v.toLowerCase().includes(auth.toLowerCase()))
+        return false;
+    }
+    return true;
+  });
+  if (containsKnownValue(text, knownValues))
+    return null;
+  const t2 = matchFirst(TIER2_PATTERNS, text);
+  if (t2)
+    return { tier: 2, reason: t2[1] };
+  return null;
+}
 function parenDepthDelta(text) {
   let depth = 0;
   let quote = null;
@@ -6044,6 +6170,7 @@ __export(dist_exports, {
   classifyAssertionBlock: () => classifyAssertionBlock,
   classifyAssertionLine: () => classifyAssertionLine,
   classifyErrorMessage: () => classifyErrorMessage,
+  classifyMobileAssertValue: () => classifyMobileAssertValue,
   classifyTestHealth: () => classifyTestHealth,
   coldSessionConfigMessage: () => coldSessionConfigMessage,
   computeMobileSwipePointers: () => computeMobileSwipePointers,
@@ -6097,6 +6224,7 @@ __export(dist_exports, {
   isEditableMobileClassName: () => isEditableMobileClassName,
   isEmailFromIdentity: () => isEmailFromIdentity,
   isEnvironmentalError: () => isEnvironmentalError,
+  isIdentityMobileXpath: () => isIdentityMobileXpath,
   isMobilePlatform: () => isMobilePlatform,
   isPricingPlan: () => isPricingPlan,
   isRunnableStep: () => isRunnableStep,
@@ -6104,6 +6232,7 @@ __export(dist_exports, {
   isSameRegistrableDomainHost: () => isSameRegistrableDomainHost,
   isSensitiveQueryKey: () => isSensitiveQueryKey,
   isSharedAuthInjectEnabled: () => isSharedAuthInjectEnabled,
+  isStateValueMobileClassName: () => isStateValueMobileClassName,
   isSttModelForProvider: () => isSttModelForProvider,
   isTestReadyForPlatform: () => isTestReadyForPlatform,
   isTrialExpired: () => isTrialExpired,
@@ -7011,6 +7140,7 @@ var require_mobile_observation = __commonJS({
     exports.buildCollectedElementsForScreen = buildCollectedElementsForScreen;
     exports.extractNativeMobileLandmarks = extractNativeMobileLandmarks;
     exports.safeMobileElementLabel = safeMobileElementLabel;
+    var mobile_source_parser_js_1 = require_mobile_source_parser();
     var DEFAULT_MAX_ELEMENTS = 60;
     var MAX_LABEL_LENGTH = 80;
     var EVIDENCE_LABEL_LIMIT = 40;
@@ -7101,7 +7231,8 @@ var require_mobile_observation = __commonJS({
       const locators = [];
       if (stableId)
         locators.push({ strategy: "getByTestId", value: stableId, confidence: 0.95 });
-      const xpath = element.xpath?.trim();
+      const platform3 = element.role.startsWith("XCUIElementType") ? "IOS" : "ANDROID";
+      const xpath = (0, mobile_source_parser_js_1.buildLocatorBundle)(element, platform3).xpath?.trim();
       if (xpath)
         locators.push({ strategy: "css", value: xpath, confidence: 0.4 });
       const collected = {
@@ -78350,6 +78481,10 @@ var require_discover_ai_planner = __commonJS({
       if (context.appBrief) {
         sections.push(`## Application Brief
 ${context.appBrief.slice(0, 500)}`);
+      }
+      if (context.knowledgeContext && context.knowledgeContext.trim().length > 0) {
+        sections.push(`## Known Facts
+${context.knowledgeContext.slice(0, 4e3)}`);
       }
       sections.push(`## Base URL
 ${compressed.baseUrl}`);
@@ -80888,6 +81023,45 @@ ${constraints.join("\n")}`);
   }
 });
 
+// ../runner-core/dist/services/discovery-lint-flags.js
+var require_discovery_lint_flags = __commonJS({
+  "../runner-core/dist/services/discovery-lint-flags.js"(exports) {
+    "use strict";
+    Object.defineProperty(exports, "__esModule", { value: true });
+    exports.structuralLocatorLintMode = structuralLocatorLintMode;
+    exports.isPwMethodPreflightEnabled = isPwMethodPreflightEnabled;
+    exports.isVqaLoginDedupeEnabled = isVqaLoginDedupeEnabled;
+    exports.mobileSelectorQualityLintMode = mobileSelectorQualityLintMode;
+    exports.isTestgenEmailVerifyEnabled = isTestgenEmailVerifyEnabled;
+    function strictOn(value) {
+      return value === "true" || value === "1";
+    }
+    function structuralLocatorLintMode() {
+      const v = (process.env.DISCOVERY_STRUCTURAL_LOCATOR_LINT || "").trim().toLowerCase();
+      if (v === "warn")
+        return "warn";
+      if (v === "true" || v === "1" || v === "enforce")
+        return "enforce";
+      return "off";
+    }
+    function isPwMethodPreflightEnabled() {
+      return strictOn(process.env.DISCOVERY_PW_METHOD_PREFLIGHT);
+    }
+    function isVqaLoginDedupeEnabled() {
+      return strictOn(process.env.DISCOVERY_VQALOGIN_DEDUPE);
+    }
+    function mobileSelectorQualityLintMode() {
+      const v = (process.env.MOBILE_SELECTOR_QUALITY_LINT || "").trim().toLowerCase();
+      if (v === "true" || v === "1" || v === "enforce")
+        return "enforce";
+      return "off";
+    }
+    function isTestgenEmailVerifyEnabled() {
+      return strictOn(process.env.DISCOVERY_TESTGEN_EMAIL_VERIFY);
+    }
+  }
+});
+
 // ../runner-core/dist/services/mobile/mobile-generator.js
 var require_mobile_generator = __commonJS({
   "../runner-core/dist/services/mobile/mobile-generator.js"(exports) {
@@ -80907,6 +81081,7 @@ var require_mobile_generator = __commonJS({
     var ai_queue_js_1 = require_ai_queue();
     var ai_retry_js_1 = require_ai_retry();
     var mobile_session_keepalive_js_1 = require_mobile_session_keepalive();
+    var discovery_lint_flags_js_1 = require_discovery_lint_flags();
     var mobile_source_parser_js_1 = require_mobile_source_parser();
     var mobile_source_parser_js_2 = require_mobile_source_parser();
     var mobile_observation_js_1 = require_mobile_observation();
@@ -81076,7 +81251,15 @@ var require_mobile_generator = __commonJS({
           properties: {
             name: { type: "string", description: 'Descriptive test name (e.g. "Login - Happy Path").' },
             description: { type: "string", description: "One-line description of what the test proves." },
-            verified: { type: "boolean", description: "True only if you asserted the outcome LIVE with an assert tool." }
+            verified: { type: "boolean", description: "True only if you asserted the outcome LIVE with an assert tool." },
+            suspectedBug: {
+              type: "boolean",
+              description: "True when the app itself misbehaved (crash, error screen, broken flow) and the scenario could not behave as specified. Requires bugDescription and at least one honored assert proving what you observed."
+            },
+            bugDescription: {
+              type: "string",
+              description: "What is broken in the APP (not the test) \u2014 concrete screen + observed vs expected."
+            }
           },
           required: ["name", "description", "verified"]
         }
@@ -81322,6 +81505,8 @@ var require_mobile_generator = __commonJS({
 - Assert the OUTCOME of the flow (the new screen / new content), not the control you just tapped.
 - Assert only DURABLE elements \u2014 screen chrome that exists on every visit (tab labels, headers, nav bars, the entity you just created). NEVER assert one-time / data-dependent UI: empty-state CTAs, first-run or onboarding prompts, or counters \u2014 they vanish as soon as the account has data, and the test then fails forever on a healthy app.
 - Do NOT trigger irreversible or destructive side effects \u2014 real payments; sending messages to others; and ESPECIALLY account/data deletion, deactivation, or any "type DELETE to confirm" gate (the runner hard-blocks destructive taps and confirmation keystrokes). Note them and assert what you safely can.
+- STATE OWNERSHIP for mutation scenarios (edit / rename / archive / remove): CREATE the record first in this same recording, then act on the row YOU created \u2014 never mutate pre-existing data (it may not exist on a clean install, so the replay fails forever, and another test may depend on it). If the app offers no way to create one, do NOT act on someone else's data: assert what you can safely prove and finish with verified:false, explaining why in the description.
+- If the APP itself misbehaves (crash, error screen, a flow that cannot proceed as specified), do not force a green path: assert the failure you observed (e.g. the error text), then call finish_generate with suspectedBug:true and a concrete bugDescription of what is broken in the app.
 - Stay inside this app.${targetLine} Do not open or use app stores, browsers, email apps, settings, or any other app. If an action leaves the target app, the runner will relaunch the target app and reject that action.
 - NEVER tap the phone's home screen / launcher (app icons, "Predicted app" chips, search bars, widgets). Those are NOT part of the app under test \u2014 tapping them is junk that poisons the test. If the app ever backgrounds or you find yourself on the launcher, use mobile_relaunch to cold-start the app; do NOT tap a launcher icon or app-prediction to get back in.
 - Do NOT re-do a sequence you already completed. If you filled a form then navigated away, do NOT come back and fill it again \u2014 the scenario needs ONE clean pass. Filling the login form, going back, and re-filling it is exactly the kind of wandering that produces a bloated, broken test.
@@ -81427,6 +81612,7 @@ Start by calling mobile_snapshot, then execute the steps above \u2014 the minimu
       let assertCount = 0;
       let finish = null;
       let finishIntentRejections = 0;
+      let finishStrengthRejections = 0;
       let emptyTurnsAfterFinishReject = 0;
       let latest = null;
       const getLatest = () => latest;
@@ -81919,31 +82105,49 @@ ${statePacket}`, redactionCredentials) },
             const claimedVerified = Boolean(toolArgs.verified);
             const intentReason = scenarioIntentMismatchReason(scenario, actions);
             const verifiedWithoutAssert = claimedVerified && assertCount === 0;
-            const canReject = finishIntentRejections < MAX_FINISH_INTENT_REJECTIONS && iteration < maxIterations && (intentReason !== null || verifiedWithoutAssert);
-            if (canReject) {
-              finishIntentRejections += 1;
+            const intentStyleReject = finishIntentRejections < MAX_FINISH_INTENT_REJECTIONS && iteration < maxIterations && (intentReason !== null || verifiedWithoutAssert);
+            let strengthRejectReason = null;
+            if (!intentStyleReject && claimedVerified && assertCount > 0 && intentReason === null && finishStrengthRejections < 1 && iteration < maxIterations) {
+              const verdict = evaluateMobileAssertionStrength(actions);
+              if (verdict.severity === "block") {
+                strengthRejectReason = verdict.reason;
+              }
+            }
+            if (intentStyleReject || strengthRejectReason !== null) {
+              if (intentStyleReject)
+                finishIntentRejections += 1;
+              if (strengthRejectReason !== null)
+                finishStrengthRejections += 1;
               const reasons = [];
               if (intentReason)
                 reasons.push(intentReason);
               if (verifiedWithoutAssert) {
                 reasons.push("claimed verified:true but never called mobile_assert_visible / mobile_assert_text");
               }
+              if (strengthRejectReason !== null) {
+                reasons.push(`assertion strength: ${strengthRejectReason} \u2014 your only live proof re-checks a control you already used. Assert the scenario OUTCOME instead: an element on the resulting screen, the created/updated row, or the success/error message.`);
+              }
               const reasonText = reasons.join("; ");
-              log2(`  finish_generate REJECTED (${finishIntentRejections}/${MAX_FINISH_INTENT_REJECTIONS}): ${reasonText}`);
+              log2(`  finish_generate REJECTED (intent ${finishIntentRejections}/${MAX_FINISH_INTENT_REJECTIONS}, strength ${finishStrengthRejections}/1): ${reasonText}`);
               pushResult({
                 ok: false,
                 error: `Cannot finish yet \u2014 the recorded steps do not complete this scenario: ${reasonText}. Continue driving the app (fill fields, commit forms, navigate, assert the REAL outcome), then call finish_generate again. Do NOT re-open menus or thrash Back.`,
                 intentMismatch: intentReason,
                 verifiedWithoutAssert,
-                rejection: finishIntentRejections,
-                maxRejections: MAX_FINISH_INTENT_REJECTIONS
+                ...strengthRejectReason !== null ? { strengthBlock: strengthRejectReason } : {},
+                rejection: finishIntentRejections + finishStrengthRejections,
+                maxRejections: MAX_FINISH_INTENT_REJECTIONS + 1
               });
               continue;
             }
             finish = {
               name: redactCredentialValues(nonEmpty3(String(toolArgs.name ?? "")) ?? scenario.name, redactionCredentials),
               description: redactCredentialValues(nonEmpty3(String(toolArgs.description ?? "")) ?? scenario.goal, redactionCredentials),
-              verified: claimedVerified
+              verified: claimedVerified,
+              ...toolArgs.suspectedBug === true ? {
+                suspectedBug: true,
+                bugDescription: redactCredentialValues(nonEmpty3(String(toolArgs.bugDescription ?? "")) ?? "", redactionCredentials)
+              } : {}
             };
             log2(`  finish_generate: "${finish.name}" (claimed verified: ${finish.verified}, asserts: ${assertCount})`);
             pushResult({ acknowledged: true });
@@ -82007,6 +82211,7 @@ ${statePacket}`, redactionCredentials) },
         ok: false,
         error: `Unknown element ref "${String(ref)}". Call mobile_snapshot first; refs are only valid for the latest snapshot.`
       });
+      const recordedTypeValues = () => recordedActions.filter((action) => action.type === "TYPE" && typeof action.value === "string" && action.value.length > 0).map((action) => action.value);
       const actionPayload = (result, absorbed) => {
         const blocked = Boolean(absorbed.externalBlocked || absorbed.transientExternal);
         return {
@@ -82407,7 +82612,8 @@ ${statePacket}`, redactionCredentials) },
             latest,
             screenName,
             platform: platform3,
-            recordAction
+            recordAction,
+            typedValues: recordedTypeValues
           });
           if (!recorded.ok)
             return recorded;
@@ -82476,6 +82682,15 @@ ${statePacket}`, redactionCredentials) },
               error: `Live text assertion failed: expected ${JSON.stringify(expected)} was not present on ref ${element.ref}. Re-snapshot after the outcome appears and assert the text that is actually visible.`
             };
           }
+          const volatileExpected = (0, shared_1.classifyMobileAssertValue)(expected, {
+            knownUserInputs: recordedTypeValues()
+          });
+          if (volatileExpected) {
+            return {
+              ok: false,
+              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 expectedNeedle = expected.trim().toLowerCase();
           const identityValues = [element.accessibilityId, element.resourceId].map((value) => value?.trim().toLowerCase()).filter((value) => Boolean(value));
@@ -82531,6 +82746,17 @@ ${statePacket}`, redactionCredentials) },
       if (!accessibilityId && !text) {
         return { ok: false, error: "mobile_assert_visible needs a ref (preferred), accessibilityId, or text." };
       }
+      if (!accessibilityId && text) {
+        const volatileIdentity = (0, shared_1.classifyMobileAssertValue)(text, {
+          knownUserInputs: ctx.typedValues?.() ?? []
+        });
+        if (volatileIdentity) {
+          return {
+            ok: false,
+            error: `${JSON.stringify(text)} is ${volatileIdentity.tier === 1 ? "transient one-shot UI" : "session-dynamic content"} (${volatileIdentity.reason}) \u2014 a text identity must be durable to resolve at replay. Assert a stable element of the destination screen instead (prefer a ref from mobile_snapshot).`
+          };
+        }
+      }
       const directTarget = accessibilityId ?? text;
       if (directTarget && isStructuralAssertionIdentity(directTarget)) {
         return {
@@ -83166,7 +83392,21 @@ ${statePacket}`, redactionCredentials) },
       if (claimedVerified && !verified) {
         log2("  downgraded verified -> false: model claimed verified but called zero assert tools.");
       }
-      const strengthVerdict = evaluateMobileAssertionStrength(actions);
+      const baseStrengthVerdict = evaluateMobileAssertionStrength(actions);
+      const bugDescription = recording.finish?.bugDescription?.trim() ?? "";
+      const bugWitnessHonored = process.env.DISCOVERY_BUG_WITNESS_ENABLED === "true" && recording.finish?.suspectedBug === true && bugDescription.length >= 12 && recording.assertCount > 0;
+      if (recording.finish?.suspectedBug === true && !bugWitnessHonored) {
+        log2("  suspectedBug declared but NOT honored: " + (process.env.DISCOVERY_BUG_WITNESS_ENABLED !== "true" ? "bug-witness channel disabled (DISCOVERY_BUG_WITNESS_ENABLED)." : bugDescription.length < 12 ? "bugDescription too short." : "no honored assert backs the observation."));
+      }
+      const strengthVerdict = bugWitnessHonored ? {
+        ...baseStrengthVerdict,
+        ok: false,
+        severity: "route-bug",
+        reason: `Model declared an app bug during generation: ${bugDescription}`
+      } : baseStrengthVerdict;
+      if (bugWitnessHonored) {
+        log2(`  bug-witness honored \u2014 routing as app bug: ${bugDescription}`);
+      }
       if (strengthVerdict.severity === "block" || strengthVerdict.severity === "route-bug") {
         if (verified) {
           log2(`  downgraded verified -> false: assertion strength ${strengthVerdict.severity} \u2014 ${strengthVerdict.reason}`);
@@ -83182,7 +83422,11 @@ ${statePacket}`, redactionCredentials) },
         verified = false;
       }
       const platformTag2 = platform3 === "IOS" ? "@ios" : "@android";
-      const reviewTag = verified ? "@verified" : "@needs-review";
+      const selectorLintEnforced = (0, discovery_lint_flags_js_1.mobileSelectorQualityLintMode)() === "enforce" && selectorQuality.summary.high > 0;
+      if (selectorLintEnforced && verified) {
+        log2(`  selector-quality lint (enforce): ${selectorQuality.summary.high} high-severity locator issue(s) \u2014 tagging @needs-review.`);
+      }
+      const reviewTag = verified && !selectorLintEnforced ? "@verified" : "@needs-review";
       const tags = ["@discovered", "@mobile", platformTag2, reviewTag];
       if (strengthVerdict.severity === "downgrade")
         tags.push("@smoke");
@@ -86262,38 +86506,6 @@ var require_run_callback_proxy = __commonJS({
   }
 });
 
-// ../runner-core/dist/services/discovery-lint-flags.js
-var require_discovery_lint_flags = __commonJS({
-  "../runner-core/dist/services/discovery-lint-flags.js"(exports) {
-    "use strict";
-    Object.defineProperty(exports, "__esModule", { value: true });
-    exports.structuralLocatorLintMode = structuralLocatorLintMode;
-    exports.isPwMethodPreflightEnabled = isPwMethodPreflightEnabled;
-    exports.isVqaLoginDedupeEnabled = isVqaLoginDedupeEnabled;
-    exports.isTestgenEmailVerifyEnabled = isTestgenEmailVerifyEnabled;
-    function strictOn(value) {
-      return value === "true" || value === "1";
-    }
-    function structuralLocatorLintMode() {
-      const v = (process.env.DISCOVERY_STRUCTURAL_LOCATOR_LINT || "").trim().toLowerCase();
-      if (v === "warn")
-        return "warn";
-      if (v === "true" || v === "1" || v === "enforce")
-        return "enforce";
-      return "off";
-    }
-    function isPwMethodPreflightEnabled() {
-      return strictOn(process.env.DISCOVERY_PW_METHOD_PREFLIGHT);
-    }
-    function isVqaLoginDedupeEnabled() {
-      return strictOn(process.env.DISCOVERY_VQALOGIN_DEDUPE);
-    }
-    function isTestgenEmailVerifyEnabled() {
-      return strictOn(process.env.DISCOVERY_TESTGEN_EMAIL_VERIFY);
-    }
-  }
-});
-
 // ../runner-core/dist/services/auth-recipe.js
 var require_auth_recipe = __commonJS({
   "../runner-core/dist/services/auth-recipe.js"(exports) {
@@ -92154,6 +92366,15 @@ var require_agentic_discovery_prompts = __commonJS({
         lines.push(input.appBrief.trim());
         lines.push("");
       }
+      if (input.knownFactsBlock && input.knownFactsBlock.trim()) {
+        lines.push("## Known facts about this feature (from project documentation)");
+        lines.push("");
+        lines.push("Advisory hints about routes/data/constraints \u2014 verify against the live");
+        lines.push("app; the browser is the source of truth for locators.");
+        lines.push("");
+        lines.push(input.knownFactsBlock.trim());
+        lines.push("");
+      }
       if (input.credentials && input.credentials.length > 0) {
         lines.push("## Test credentials (throwaway accounts)");
         lines.push("");
@@ -328821,6 +329042,15 @@ var require_agentic_survey_prompts = __commonJS({
         lines.push(input.appBrief.trim());
         lines.push("");
       }
+      if (input.knownFactsBlock && input.knownFactsBlock.trim().length > 0) {
+        lines.push("## Known facts about this app (from project documentation)");
+        lines.push("");
+        lines.push("Use these as hints for what features/routes/constraints exist. They are");
+        lines.push("advisory \u2014 verify against the live app; the browser is the source of truth.");
+        lines.push("");
+        lines.push(input.knownFactsBlock.trim());
+        lines.push("");
+      }
       if (input.credentials && input.credentials.length > 0) {
         lines.push("## Test credentials (throwaway accounts)");
         lines.push("");
@@ -329448,6 +329678,7 @@ var require_grok_survey_runner = __commonJS({
       const briefInput = {
         baseUrl: ctx.baseUrl,
         appBrief: ctx.appBrief,
+        knownFactsBlock: ctx.knowledgeContext,
         credentials: credentials.length > 0 ? credentials : void 0,
         existingFeatureNames: ctx.existingFeatureNames ?? [],
         focusAreas: ctx.focusAreas,
@@ -331143,6 +331374,7 @@ var require_grok_discovery_runner = __commonJS({
           featureObservations: ctx.featureContext?.flowIntel,
           notesForTestAuthor: ctx.featureContext?.priorInsight,
           appBrief: ctx.appBrief,
+          knownFactsBlock: ctx.knowledgeContext,
           credentials: credentials.length > 0 ? credentials : void 0,
           testVariableKeys: testVariableKeys.length > 0 ? testVariableKeys : void 0,
           existingTestNames: ctx.existingTestNames ?? [],
@@ -332080,6 +332312,7 @@ ${(0, inbox_tools_js_1.buildInboxAgentsGuidance)(inboxReg.email, inboxReg.passwo
           featureObservations: ctx.featureContext?.flowIntel,
           notesForTestAuthor: ctx.featureContext?.priorInsight,
           appBrief: ctx.appBrief,
+          knownFactsBlock: ctx.knowledgeContext,
           credentials: credentials.length > 0 ? credentials : void 0,
           testVariableKeys: testVariableKeys.length > 0 ? testVariableKeys : void 0,
           existingTestNames: ctx.existingTestNames ?? [],
@@ -333171,6 +333404,7 @@ ${preview}`);
       const briefInput = {
         baseUrl: ctx.baseUrl,
         appBrief: ctx.appBrief,
+        knownFactsBlock: ctx.knowledgeContext,
         credentials: credentials.length > 0 ? credentials : void 0,
         existingFeatureNames: ctx.existingFeatureNames ?? [],
         focusAreas: ctx.focusAreas,
@@ -334030,6 +334264,7 @@ var require_claude_discovery_runner = __commonJS({
           featureObservations: ctx.featureContext?.flowIntel,
           notesForTestAuthor: ctx.featureContext?.priorInsight,
           appBrief: ctx.appBrief,
+          knownFactsBlock: ctx.knowledgeContext,
           credentials: credentials.length > 0 ? credentials : void 0,
           testVariableKeys: testVariableKeys.length > 0 ? testVariableKeys : void 0,
           existingTestNames: ctx.existingTestNames ?? [],
@@ -335884,7 +336119,8 @@ Explore complete: ${exploreResult.pagesDiscovered} pages, ${exploreResult.elemen
           // scenarioTouchesSignupAuthSurface) still isolate non-auth scenarios. The
           // auth-feature scope IS applied at the DEEP call site where ctx.featureName is known.
           emailVerifyArmed: mode !== "survey" && plannerEmailVerifyArmed(ctx),
-          testBudget
+          testBudget,
+          knowledgeContext: ctx.knowledgeContext
         }, {
           modelOverride: ctx.planModel ?? ctx.generateModel,
           gateModelOverride: ctx.planGateModel,
@@ -335996,6 +336232,7 @@ Health: ${surveyHealth.totalIssues} issue(s) - ${surveyHealth.consoleErrors.leng
           interactionLog: exploreResult.interactionLog,
           modelOverride: ctx.generateModel,
           appBrief: ctx.appBrief,
+          knowledgeContext: ctx.knowledgeContext,
           onAICall,
           onProgress,
           mcpClient: mcpClient ?? void 0,
@@ -336475,7 +336712,8 @@ Plan (reused): ${resumeSavedScenarios.length} scenarios from the paused run.`);
             // configured inbox), so the planner never promises what generation can't do.
             // Scoped to AUTH features: a non-auth feature has no signup surface to test.
             emailVerifyArmed: plannerEmailVerifyArmed(ctx) && featureLooksLikeAuth(ctx.featureName, augmentedFeatureFocusAreas),
-            testBudget: featureTestBudget
+            testBudget: featureTestBudget,
+            knowledgeContext: ctx.knowledgeContext
           }, {
             modelOverride: ctx.planModel ?? ctx.generateModel,
             gateModelOverride: ctx.planGateModel,
@@ -336521,6 +336759,7 @@ Plan: ${planResult.scenarios.length} scenarios (budget: ${featureTestBudget})`);
           interactionLog: exploreResult.interactionLog,
           modelOverride: ctx.generateModel,
           appBrief: ctx.appBrief,
+          knowledgeContext: ctx.knowledgeContext,
           onAICall,
           mcpClient: mcpClient ?? void 0,
           // Pooled browser for parallel scenario generation (Fargate opt-in via
@@ -347734,6 +347973,12 @@ Write valid JSON only (no markdown fences inside files). Be exhaustive.`;
         "Use {{TEST_USER_EMAIL}}/{{TEST_USER_PASSWORD}} for credentials. Include",
         "assertVisible or assertText unless tagging @needs-review. When an incremental",
         "allow-list is present, extract ONLY from those files.",
+        "",
+        "Every tap/type/clear/waitForElement/assertVisible/assertText target MUST",
+        "carry an IDENTITY locator: ~accessibility-id, id=resource-id, visible text,",
+        "or an attribute-EQUALITY xpath (//android.widget.Button[@text='Submit']).",
+        "Positional/index-only xpaths (/hierarchy/\u2026/View[3]) are rejected \u2014 imported",
+        "steps have no recorded coordinates, so such a step can never replay.",
         "Write strictly valid JSON."
       ].join("\n");
     }
@@ -347751,6 +347996,32 @@ Write valid JSON only (no markdown fences inside files). Be exhaustive.`;
     function isPlainObject2(value) {
       return !!value && typeof value === "object" && !Array.isArray(value);
     }
+    var LOCATOR_REQUIRING_IMPORT_ACTIONS = /* @__PURE__ */ new Set([
+      "tap",
+      "type",
+      "clear",
+      "waitForElement",
+      "assertVisible",
+      "assertText"
+    ]);
+    function selectorValueHasIdentity(value) {
+      const trimmed = value.trim();
+      if (!trimmed)
+        return false;
+      if (trimmed.startsWith("/") || trimmed.startsWith("(//"))
+        return (0, shared_1.isIdentityMobileXpath)(trimmed);
+      return true;
+    }
+    function stepLocatorLacksIdentity(step) {
+      if (!LOCATOR_REQUIRING_IMPORT_ACTIONS.has(step.action))
+        return false;
+      const target = step.target;
+      if (!target)
+        return true;
+      if ((0, shared_1.mobileLocatorBundleHasIdentity)(target.locatorBundle))
+        return false;
+      return ![target.primary, ...target.fallbacks ?? []].some((value) => typeof value === "string" && selectorValueHasIdentity(value));
+    }
     function isValidStep(value) {
       if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -347792,12 +348063,7 @@ Write valid JSON only (no markdown fences inside files). Be exhaustive.`;
       const o = value;
       if (!isNonEmptyString(o.name))
         return { ok: false, reason: "name: missing" };
-      if (!isNonEmptyString(o.appiumCode))
-        return { ok: false, reason: "appiumCode: missing" };
-      const code = o.appiumCode;
-      if (!/webdriverio|remote\s*\(|driver\s*\./i.test(code)) {
-        return { ok: false, reason: "appiumCode: not a WebdriverIO/Appium script" };
-      }
+      const code = isNonEmptyString(o.appiumCode) ? o.appiumCode : "";
       if (!Array.isArray(o.steps) || o.steps.length === 0) {
         return { ok: false, reason: "steps: missing or empty" };
       }
@@ -347807,6 +348073,13 @@ Write valid JSON only (no markdown fences inside files). Be exhaustive.`;
       if (!o.steps.every(isValidStep)) {
         return { ok: false, reason: "steps: invalid step shape" };
       }
+      const identityless = o.steps.find(stepLocatorLacksIdentity);
+      if (identityless) {
+        return {
+          ok: false,
+          reason: `steps: step ${identityless.order} (${identityless.action}) has no identity locator \u2014 a positional/index xpath cannot replay (imported steps have no recorded coordinates). Use ~accessibility-id, id=resource-id, visible text, or an attribute-equality xpath like //android.widget.Button[@text='Submit'].`
+        };
+      }
       const steps = o.steps.map((step, order) => ({
         ...step,
         order,
@@ -351100,7 +351373,7 @@ var require_package4 = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@validate.qa/runner",
-      version: "1.0.66",
+      version: "1.0.68",
       description: "validate local test runner - execute Playwright tests on your machine, connected to validate.qa cloud.",
       bin: {
         "validate-runner": "dist/cli.js"
@@ -351496,6 +351769,9 @@ function sanitizeAppiumLogLine(line) {
 }
 function setAppiumWorkloadActive(active) {
   activeWorkloadCount = active ? activeWorkloadCount + 1 : Math.max(0, activeWorkloadCount - 1);
+  if (activeWorkloadCount === 0) {
+    consecutiveHealthFailures = 0;
+  }
 }
 function shouldRestartAfterHealthFailure(workloadCount, failureCount) {
   return workloadCount <= 0 && failureCount >= HEALTH_FAILURES_BEFORE_RESTART;
@@ -351991,17 +352267,31 @@ function rectMatchesIntendedBounds(rect, bounds) {
   return rectCenterInBounds || boundsCenterInRect;
 }
 async function resolveTypeTargetElementId(sessionPath, bounds) {
-  const box = bounds !== void 0 ? normaliseBounds(bounds) : null;
+  const rawBox = bounds !== void 0 ? normaliseBounds(bounds) : null;
+  const box = rawBox && rawBox.width > 0 && rawBox.height > 0 ? rawBox : null;
   let elementId = await getActiveElementId(sessionPath);
-  if (elementId && box && box.width > 0 && box.height > 0) {
+  let rejectedElementId = null;
+  let rejectedForMismatch = false;
+  if (elementId && box) {
     const rect = await getElementRect(sessionPath, elementId);
     if (!rect || !rectMatchesIntendedBounds(rect, box)) {
+      rejectedElementId = elementId;
+      rejectedForMismatch = !!rect;
       elementId = null;
     }
   }
   if (!elementId && bounds !== void 0 && await tapBoundsCenter(sessionPath, bounds)) {
     await new Promise((resolve2) => setTimeout(resolve2, MOBILE_FOCUS_SETTLE_MS));
     elementId = await getActiveElementId(sessionPath);
+    if (elementId && box) {
+      const rect = await getElementRect(sessionPath, elementId);
+      const provablyWrong = rect ? !rectMatchesIntendedBounds(rect, box) : rejectedForMismatch && elementId === rejectedElementId;
+      if (provablyWrong) {
+        throw new Error(
+          "Could not focus the intended field: a different element kept keyboard focus after tapping the target bounds. Tap the field directly, then retry."
+        );
+      }
+    }
   }
   return elementId;
 }
@@ -354554,7 +354844,7 @@ function boundsForRun(step, platform3, isCrossPlatform) {
   if (platform3 && hasPlatformLocator(step.target, platform3)) return null;
   return boundsFromStep(step);
 }
-function locatorStrategyForValue(value) {
+function locatorStrategyForValue(value, platform3) {
   const trimmed = value?.trim();
   if (!trimmed) {
     return [];
@@ -354570,7 +354860,8 @@ function locatorStrategyForValue(value) {
   }
   return [
     { using: "accessibility id", value: trimmed },
-    { using: "id", value: trimmed }
+    { using: "id", value: trimmed },
+    ...textIdentityStrategies(trimmed, platform3)
   ];
 }
 function buildLocatorStrategies(target, platform3) {
@@ -354580,12 +354871,19 @@ function buildLocatorStrategies(target, platform3) {
   if (bundle) {
     if (bundle.accessibilityId) strategies.push({ using: "accessibility id", value: bundle.accessibilityId });
     if (bundle.resourceId) strategies.push({ using: "id", value: bundle.resourceId });
-    if (bundle.xpath) strategies.push({ using: "xpath", value: bundle.xpath });
+    if (bundle.xpath && isIdentityXpath(bundle.xpath)) strategies.push({ using: "xpath", value: bundle.xpath });
+    for (const value of [
+      isEditableMobileClassName(bundle.className) || isStateValueMobileClassName(bundle.className) ? void 0 : bundle.text,
+      bundle.contentDesc
+    ]) {
+      const trimmed = value?.trim();
+      if (trimmed) strategies.push(...textIdentityStrategies(trimmed, platform3));
+    }
   }
   if (!(platform3 && hasPlatformLocator(target, platform3))) {
-    strategies.push(...locatorStrategyForValue(target.primary));
+    strategies.push(...locatorStrategyForValue(target.primary, platform3));
     for (const fallback of target.fallbacks ?? []) {
-      strategies.push(...locatorStrategyForValue(fallback));
+      strategies.push(...locatorStrategyForValue(fallback, platform3));
     }
   }
   return strategies.filter((strategy) => strategy.using !== "xpath" || isIdentityXpath(strategy.value)).filter(
@@ -354597,22 +354895,41 @@ function dedupeStrategies(strategies) {
     (strategy, index, list) => list.findIndex((candidate) => candidate.using === strategy.using && candidate.value === strategy.value) === index
   );
 }
-function xpathLiteral2(value) {
+function xpathLiteral3(value) {
   if (!value.includes("'")) return `'${value}'`;
   if (!value.includes('"')) return `"${value}"`;
   const parts = value.split("'").map((p) => `'${p}'`);
   return `concat(${parts.join(`, "'", `)})`;
 }
-function identityTextXpath(value) {
-  const lit = xpathLiteral2(value);
+function identityTextXpath2(value) {
+  const lit = xpathLiteral3(value);
   return `//*[@text=${lit} or @content-desc=${lit} or @label=${lit} or @name=${lit} or @value=${lit}]`;
 }
+function iosPredicateLiteral(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function iosTextIdentityPredicate(value) {
+  const lit = iosPredicateLiteral(value);
+  return `label == ${lit} OR name == ${lit} OR value == ${lit}`;
+}
+function textIdentityStrategies(value, platform3) {
+  const strategies = [];
+  if (platform3 === "IOS") {
+    strategies.push({ using: "-ios predicate string", value: iosTextIdentityPredicate(value) });
+  }
+  strategies.push({ using: "xpath", value: identityTextXpath2(value) });
+  return strategies;
+}
+function isIdentityIosPredicate(value) {
+  return /(?:^|[\s(])(?:name|label|value)\s*==\s*"/.test(value) && !/\b(?:CONTAINS|BEGINSWITH|ENDSWITH|LIKE|MATCHES|IN)\b/i.test(value);
+}
 function isIdentityXpath(value) {
   return /@[A-Za-z_:][-A-Za-z0-9_:.]*\s*=/.test(value) && !/(?: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 isIdentityXpath(strategy.value);
+  if (strategy.using === "-ios predicate string") return isIdentityIosPredicate(strategy.value);
   return false;
 }
 function buildIdentityLocatorStrategies(target, platform3) {
@@ -354622,15 +354939,18 @@ function buildIdentityLocatorStrategies(target, platform3) {
   if (bundle) {
     if (bundle.accessibilityId) strategies.push({ using: "accessibility id", value: bundle.accessibilityId });
     if (bundle.resourceId) strategies.push({ using: "id", value: bundle.resourceId });
-    for (const value of [bundle.text, bundle.contentDesc]) {
+    if (bundle.xpath && isIdentityXpath(bundle.xpath)) strategies.push({ using: "xpath", value: bundle.xpath });
+    for (const value of [
+      isStateValueMobileClassName(bundle.className) ? void 0 : bundle.text,
+      bundle.contentDesc
+    ]) {
       const trimmed = value?.trim();
-      if (trimmed) strategies.push({ using: "xpath", value: identityTextXpath(trimmed) });
+      if (trimmed) strategies.push(...textIdentityStrategies(trimmed, platform3));
     }
-    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 ?? []]) {
-      for (const strategy of locatorStrategyForValue(value)) {
+      for (const strategy of locatorStrategyForValue(value, platform3)) {
         if (isIdentityStrategy(strategy)) strategies.push(strategy);
       }
     }
@@ -355104,6 +355424,19 @@ async function readElementTextCandidates(sessionId, elementId, actualText) {
   }
   return values;
 }
+var controlPortSlotsByDevice = /* @__PURE__ */ new Map();
+function acquireControlPortSlot(deviceId) {
+  const existing = controlPortSlotsByDevice.get(deviceId);
+  if (existing !== void 0) return existing;
+  const taken = new Set(controlPortSlotsByDevice.values());
+  let slot = 0;
+  while (taken.has(slot)) slot += 1;
+  controlPortSlotsByDevice.set(deviceId, slot);
+  return slot;
+}
+function releaseControlPortSlot(deviceId) {
+  controlPortSlotsByDevice.delete(deviceId);
+}
 async function executeMobileTest(options) {
   const logLines = [];
   const log2 = (msg) => logLines.push(`[${(/* @__PURE__ */ new Date()).toISOString()}] ${msg}`);
@@ -355123,6 +355456,7 @@ async function executeMobileTest(options) {
   let captureStopped = false;
   let recordingStarted = false;
   let recordingStopped = false;
+  let acquiredSlotDeviceId = null;
   let video;
   let failingSource;
   const stopCapture = async () => {
@@ -355225,7 +355559,8 @@ async function executeMobileTest(options) {
       log2(`Warning: Could not retrieve installed apps list. Proceeding with test execution.`);
     }
     log2(`Starting Appium session for ${options.target.appId} on ${selectedDevice.name}...`);
-    const leasedPortOffset = Math.max(0, matchingDevices.findIndex((d) => d.id === selectedDevice?.id));
+    const leasedPortOffset = acquireControlPortSlot(selectedDevice.id);
+    acquiredSlotDeviceId = selectedDevice.id;
     try {
       sessionId = await createSessionWithRetry({
         appId: options.target.appId,
@@ -355502,6 +355837,7 @@ async function executeMobileTest(options) {
       await deleteSession(sessionId);
       log2("Session destroyed");
     }
+    if (acquiredSlotDeviceId) releaseControlPortSlot(acquiredSlotDeviceId);
   }
 }
 async function createMobileDiscoverySession(target, options) {
@@ -355547,21 +355883,28 @@ async function createMobileDiscoverySession(target, options) {
     isPhysical: selectedDevice.isPhysical === true,
     platformVersion: selectedDevice.platformVersion
   });
-  const sessionId = await createSessionWithRetry({
-    appId: target.appId,
-    platform: target.platform,
-    deviceId: selectedDevice.id,
-    platformVersion: target.platformVersion ?? selectedDevice.platformVersion,
-    isPhysical: selectedDevice.isPhysical,
-    // Distinct control resources per concurrent device, including simulators.
-    portOffset: Math.max(0, matchingDevices.findIndex((d) => d.id === selectedDevice?.id))
-  });
+  const discoveryPortSlotDeviceId = selectedDevice.id;
+  let sessionId;
+  try {
+    sessionId = await createSessionWithRetry({
+      appId: target.appId,
+      platform: target.platform,
+      deviceId: selectedDevice.id,
+      platformVersion: target.platformVersion ?? selectedDevice.platformVersion,
+      isPhysical: selectedDevice.isPhysical,
+      portOffset: acquireControlPortSlot(discoveryPortSlotDeviceId)
+    });
+  } catch (err) {
+    releaseControlPortSlot(discoveryPortSlotDeviceId);
+    throw err;
+  }
   if (target.launchMode === "DEEP_LINK" && target.deeplink) {
     try {
       await openDeepLink(sessionId, target.platform, target.deeplink, target.appId);
     } catch (err) {
       await deleteSession(sessionId).catch(() => {
       });
+      releaseControlPortSlot(discoveryPortSlotDeviceId);
       throw new Error(
         `Deep-link launch failed for mobile discovery: ${err instanceof Error ? err.message : String(err)}`
       );
@@ -355583,6 +355926,7 @@ async function createMobileDiscoverySession(target, options) {
       } catch {
       }
       await deleteSession(sessionId);
+      releaseControlPortSlot(discoveryPortSlotDeviceId);
     }
   };
 }
@@ -355600,26 +355944,26 @@ async function readElementAttribute(sessionId, elementId, name) {
 }
 function harvestFallbackXpath(platform3, attrs) {
   if (platform3 === "IOS") {
-    if (attrs.name) return `//*[@name=${xpathLiteral2(attrs.name)}]`;
-    const text = attrs.label ?? attrs.value;
-    if (text) return identityTextXpath(text);
+    if (attrs.name) return `//*[@name=${xpathLiteral3(attrs.name)}]`;
+    if (attrs.text) return identityTextXpath2(attrs.text);
     return "//*";
   }
-  if (attrs.resourceId) return `//*[@resource-id=${xpathLiteral2(attrs.resourceId)}]`;
-  if (attrs.text) return identityTextXpath(attrs.text);
-  if (attrs.contentDesc) return `//*[@content-desc=${xpathLiteral2(attrs.contentDesc)}]`;
+  if (attrs.resourceId) return `//*[@resource-id=${xpathLiteral3(attrs.resourceId)}]`;
+  if (attrs.text) return identityTextXpath2(attrs.text);
+  if (attrs.contentDesc) return `//*[@content-desc=${xpathLiteral3(attrs.contentDesc)}]`;
   return "//*";
 }
 async function readNativeElementBundle(sessionId, elementId, platform3) {
   const className = await readElementAttribute(sessionId, elementId, platform3 === "IOS" ? "type" : "class") ?? "";
+  const volatileText = isEditableMobileClassName(className) || isStateValueMobileClassName(className);
   if (platform3 === "IOS") {
     const name = await readElementAttribute(sessionId, elementId, "name");
     const label = await readElementAttribute(sessionId, elementId, "label");
     const value = await readElementAttribute(sessionId, elementId, "value");
-    const text2 = label ?? value;
+    const text2 = label ?? (volatileText ? void 0 : value);
     if (!name && !text2) return null;
     const bundle2 = {
-      xpath: harvestFallbackXpath("IOS", { name, label, value }),
+      xpath: harvestFallbackXpath("IOS", { name, text: text2 }),
       className
     };
     if (name) bundle2.accessibilityId = name;
@@ -355628,7 +355972,8 @@ async function readNativeElementBundle(sessionId, elementId, platform3) {
   }
   const resourceId = await readElementAttribute(sessionId, elementId, "resource-id");
   const contentDesc = await readElementAttribute(sessionId, elementId, "content-desc") ?? await readElementAttribute(sessionId, elementId, "contentDescription");
-  const text = await readElementAttribute(sessionId, elementId, "text");
+  const rawText = await readElementAttribute(sessionId, elementId, "text");
+  const text = volatileText ? void 0 : rawText;
   if (!resourceId && !contentDesc && !text) return null;
   const bundle = {
     xpath: harvestFallbackXpath("ANDROID", { text, contentDesc, resourceId }),
@@ -355960,6 +356305,7 @@ var sessionStartInFlight = null;
 var sessionReaperTimer = null;
 var mirrorClientsEmptyAt = null;
 var mirrorSessionOwner = null;
+var actionInFlight = false;
 var recordingWorkloadActive = false;
 function setRecordingWorkloadActive(active) {
   if (recordingWorkloadActive === active) return;
@@ -356189,7 +356535,11 @@ async function handleHealth(_req, res) {
     // 409 — it must never be inferred from server-side global run counts, which
     // include unrelated projects and runners.
     executorBusy: executorBusyCount > 0,
-    recordingActive: !!state.appiumSessionId && mirrorSessionOwner === "recording"
+    // TRUE also during the multi-second session-START window: the claim loop
+    // reads this to keep test runs off the recording device, and the Appium
+    // session id only lands AFTER `POST /session` returns — without the
+    // in-flight latch a run admitted in that window fights the recording.
+    recordingActive: !!state.appiumSessionId && mirrorSessionOwner === "recording" || sessionStartInFlight !== null
   });
 }
 function realDeviceCapabilities2(platform3) {
@@ -356267,7 +356617,11 @@ async function handleDevices(_req, res) {
   sendJSON(res, 200, {
     devices,
     executorBusy: executorBusyCount > 0,
-    recordingActive: !!state.appiumSessionId && mirrorSessionOwner === "recording"
+    // TRUE also during the multi-second session-START window: the claim loop
+    // reads this to keep test runs off the recording device, and the Appium
+    // session id only lands AFTER `POST /session` returns — without the
+    // in-flight latch a run admitted in that window fights the recording.
+    recordingActive: !!state.appiumSessionId && mirrorSessionOwner === "recording" || sessionStartInFlight !== null
   });
 }
 async function handleSessionStart(req, res) {
@@ -356356,6 +356710,8 @@ async function startSession(validated, res) {
     state.platform = targetPlatform === "IOS" ? "IOS" : "ANDROID";
     mirrorSessionOwner = "recording";
     setRecordingWorkloadActive(true);
+    mirrorClientsEmptyAt = Date.now();
+    ensureSessionReaper();
     if (launchMode === "DEEP_LINK" && deeplink) {
       try {
         const args = targetPlatform === "IOS" ? [{ url: deeplink, bundleId: appId }] : [{ url: deeplink, package: appId }];
@@ -356709,6 +357065,14 @@ async function handleAction(req, res) {
     sendJSON(res, 400, { error: "No active Appium session" });
     return;
   }
+  if (mirrorSessionOwner !== "recording") {
+    sendJSON(res, 409, { error: "No recording session owns the device (a runner-driven session is active)." });
+    return;
+  }
+  if (actionInFlight) {
+    sendJSON(res, 409, { error: "Another action is still executing. Wait for it to finish." });
+    return;
+  }
   validateSessionId(state.appiumSessionId);
   const body = await parseBody(req);
   const type = typeof body.type === "string" ? body.type : null;
@@ -356720,6 +357084,7 @@ async function handleAction(req, res) {
     sendJSON(res, 400, { error: "Unknown or unsupported action type" });
     return;
   }
+  actionInFlight = true;
   try {
     const sessionPath = `/session/${state.appiumSessionId}`;
     switch (type) {
@@ -356792,15 +357157,23 @@ async function handleAction(req, res) {
         sendJSON(res, 400, { error: `Unknown action type: ${type}` });
         return;
     }
-    const [screenshot, source] = await Promise.all([getScreenshot2(), getPageSource2()]);
+    await waitForUiSettle(sessionPath);
+    const screenshot = await getScreenshot2();
+    let source = await getPageSource2();
+    if (source === null) {
+      source = await getPageSource2();
+    }
     sendJSON(res, 200, {
       ok: true,
       screenshot: screenshot ?? null,
       source: source ?? null,
+      ...source === null || source === void 0 ? { sourceUnavailable: true } : {},
       timestamp: Date.now()
     });
   } catch (err) {
     sendJSON(res, 500, { error: `Action failed: ${err instanceof Error ? err.message : String(err)}` });
+  } finally {
+    actionInFlight = false;
   }
 }
 async function handleScreenshot(_req, res) {
@@ -357038,7 +357411,11 @@ function getBridgeState() {
     tunnelUrl: state.tunnelUrl,
     tunnelToken: state.tunnelToken,
     hasActiveSession: !!state.appiumSessionId,
-    recordingActive: !!state.appiumSessionId && mirrorSessionOwner === "recording",
+    // TRUE also during the multi-second session-START window: the claim loop
+    // reads this to keep test runs off the recording device, and the Appium
+    // session id only lands AFTER `POST /session` returns — without the
+    // in-flight latch a run admitted in that window fights the recording.
+    recordingActive: !!state.appiumSessionId && mirrorSessionOwner === "recording" || sessionStartInFlight !== null,
     platform: state.platform
   };
 }