@validate.qa/runner 1.0.66 → 1.0.67

package/dist/cli.mjs

@@ -2241,6 +2241,18 @@ 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;
@@ -2267,6 +2279,13 @@ function selectorCandidatesForStep(step) {
       candidates.push(`~${bundle.accessibilityId}`);
     if (nonEmpty(bundle.resourceId))
       candidates.push(`id=${bundle.resourceId}`);
+    const isGateStep = step.action === "waitForElement" || step.action === "assertVisible" || step.action === "assertText";
+    const textIdentity = isGateStep || !isEditableMobileClassName(bundle.className) ? bundle.text : void 0;
+    for (const value of [textIdentity, bundle.contentDesc]) {
+      const trimmed = nonEmpty(value);
+      if (trimmed)
+        candidates.push(identityTextXpath(trimmed));
+    }
     if (nonEmpty(bundle.xpath))
       candidates.push(bundle.xpath);
   }
@@ -2715,7 +2734,7 @@ function uniq(values) {
   }
   return result;
 }
-function xpathLiteral(value) {
+function xpathLiteral2(value) {
   if (!value.includes("'"))
     return `'${value}'`;
   if (!value.includes('"'))
@@ -2723,7 +2742,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}]`;
   }
@@ -3871,6 +3890,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 +6100,7 @@ __export(dist_exports, {
   classifyAssertionBlock: () => classifyAssertionBlock,
   classifyAssertionLine: () => classifyAssertionLine,
   classifyErrorMessage: () => classifyErrorMessage,
+  classifyMobileAssertValue: () => classifyMobileAssertValue,
   classifyTestHealth: () => classifyTestHealth,
   coldSessionConfigMessage: () => coldSessionConfigMessage,
   computeMobileSwipePointers: () => computeMobileSwipePointers,
@@ -80888,6 +80945,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 +81003,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 +81173,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 +81427,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 +81534,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 +82027,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 +82133,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 +82534,8 @@ ${statePacket}`, redactionCredentials) },
             latest,
             screenName,
             platform: platform3,
-            recordAction
+            recordAction,
+            typedValues: recordedTypeValues
           });
           if (!recorded.ok)
             return recorded;
@@ -82476,6 +82604,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 +82668,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 +83314,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 +83344,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 +86428,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) {
@@ -347792,12 +347926,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" };
       }
@@ -351100,7 +351229,7 @@ var require_package4 = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@validate.qa/runner",
-      version: "1.0.66",
+      version: "1.0.67",
       description: "validate local test runner - execute Playwright tests on your machine, connected to validate.qa cloud.",
       bin: {
         "validate-runner": "dist/cli.js"
@@ -351496,6 +351625,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 +352123,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;
 }
@@ -354580,6 +354726,13 @@ 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 });
+    for (const value of [
+      isEditableMobileClassName(bundle.className) ? void 0 : bundle.text,
+      bundle.contentDesc
+    ]) {
+      const trimmed = value?.trim();
+      if (trimmed) strategies.push({ using: "xpath", value: identityTextXpath2(trimmed) });
+    }
     if (bundle.xpath) strategies.push({ using: "xpath", value: bundle.xpath });
   }
   if (!(platform3 && hasPlatformLocator(target, platform3))) {
@@ -354597,14 +354750,14 @@ 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 isIdentityXpath(value) {
@@ -354624,7 +354777,7 @@ function buildIdentityLocatorStrategies(target, platform3) {
     if (bundle.resourceId) strategies.push({ using: "id", value: bundle.resourceId });
     for (const value of [bundle.text, bundle.contentDesc]) {
       const trimmed = value?.trim();
-      if (trimmed) strategies.push({ using: "xpath", value: identityTextXpath(trimmed) });
+      if (trimmed) strategies.push({ using: "xpath", value: identityTextXpath2(trimmed) });
     }
     if (bundle.xpath && isIdentityXpath(bundle.xpath)) strategies.push({ using: "xpath", value: bundle.xpath });
   }
@@ -355104,6 +355257,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 +355289,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 +355392,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 +355670,7 @@ async function executeMobileTest(options) {
       await deleteSession(sessionId);
       log2("Session destroyed");
     }
+    if (acquiredSlotDeviceId) releaseControlPortSlot(acquiredSlotDeviceId);
   }
 }
 async function createMobileDiscoverySession(target, options) {
@@ -355547,21 +355716,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 +355759,7 @@ async function createMobileDiscoverySession(target, options) {
       } catch {
       }
       await deleteSession(sessionId);
+      releaseControlPortSlot(discoveryPortSlotDeviceId);
     }
   };
 }
@@ -355600,14 +355777,14 @@ async function readElementAttribute(sessionId, elementId, name) {
 }
 function harvestFallbackXpath(platform3, attrs) {
   if (platform3 === "IOS") {
-    if (attrs.name) return `//*[@name=${xpathLiteral2(attrs.name)}]`;
+    if (attrs.name) return `//*[@name=${xpathLiteral3(attrs.name)}]`;
     const text = attrs.label ?? attrs.value;
-    if (text) return identityTextXpath(text);
+    if (text) return identityTextXpath2(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) {
@@ -355960,6 +356137,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 +356367,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 +356449,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 +356542,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 +356897,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 +356916,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 +356989,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 +357243,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
   };
 }