@validate.qa/runner 1.0.4 → 1.0.6

package/dist/cli.mjs

@@ -620,12 +620,19 @@ var require_ai_provider = __commonJS({
     function getMobileAIClient() {
       if ((process.env.SERVER_URL ?? "").trim().length > 0)
         return getServerProxiedAIClient();
-      return getAIClient();
+      if (isMobileAiUnitTestMode())
+        return getAIClient();
+      throw new Error("Mobile AI requires the platform server URL (SERVER_URL). Customer runners do not provision provider API keys \u2014 the platform proxies every mobile AI completion through /api/runner/ai/execute, which lives on the shared server with the keys. If you reached this from `validate-runner start`, the credentials file is missing `serverUrl` or the install is broken; re-run `npx @validate.qa/runner login`. If you are calling the runner-core library directly, pass `options.aiClient` in tests or set VALIDATEQA_TEST_MODE=1 to opt into the local-provider fallback.");
     }
     function getMobileClientForModel(modelId) {
       if ((process.env.SERVER_URL ?? "").trim().length > 0)
         return getServerProxiedClientForModel(modelId);
-      return getClientForModel(modelId);
+      if (isMobileAiUnitTestMode())
+        return getClientForModel(modelId);
+      throw new Error(`Mobile AI for model "${modelId}" requires the platform server URL (SERVER_URL). Customer runners do not provision provider API keys \u2014 the platform proxies every mobile AI completion through /api/runner/ai/execute. See getMobileAIClient() for remediation steps.`);
+    }
+    function isMobileAiUnitTestMode() {
+      return (process.env.VALIDATEQA_TEST_MODE ?? "").trim() === "1" || (process.env.NODE_ENV ?? "").trim() === "test";
     }
   }
 });
@@ -1035,6 +1042,65 @@ var require_mobile_source_parser = __commonJS({
   }
 });
 
+// ../runner-core/dist/services/mobile/mobile-boundary.js
+var require_mobile_boundary = __commonJS({
+  "../runner-core/dist/services/mobile/mobile-boundary.js"(exports) {
+    "use strict";
+    Object.defineProperty(exports, "__esModule", { value: true });
+    exports.mobileOwnerFromScreenSignal = mobileOwnerFromScreenSignal;
+    exports.isTransientMobileSystemOwner = isTransientMobileSystemOwner;
+    exports.classifyMobileScreenBoundary = classifyMobileScreenBoundary2;
+    exports.isTargetLikeMobileBoundary = isTargetLikeMobileBoundary2;
+    exports.mobileBoundaryNote = mobileBoundaryNote;
+    var ANDROID_TRANSIENT_SYSTEM_APP_IDS = /* @__PURE__ */ new Set([
+      "com.android.permissioncontroller",
+      "com.google.android.permissioncontroller",
+      "com.android.packageinstaller",
+      "com.google.android.packageinstaller"
+    ]);
+    var IOS_TRANSIENT_SYSTEM_APP_IDS = /* @__PURE__ */ new Set([
+      "com.apple.springboard"
+    ]);
+    function mobileOwnerFromScreenSignal(signal, targetAppId) {
+      const bundleId = signal.bundleId?.trim();
+      if (bundleId)
+        return bundleId;
+      const activity = signal.activity?.trim();
+      if (activity && targetAppId && (activity === targetAppId || activity.startsWith(`${targetAppId}.`))) {
+        return targetAppId;
+      }
+      return null;
+    }
+    function isTransientMobileSystemOwner(owner, platform3) {
+      return platform3 === "ANDROID" ? ANDROID_TRANSIENT_SYSTEM_APP_IDS.has(owner) : IOS_TRANSIENT_SYSTEM_APP_IDS.has(owner);
+    }
+    function classifyMobileScreenBoundary2(signal, targetAppId, platform3) {
+      if (!targetAppId)
+        return { kind: "target" };
+      const owner = mobileOwnerFromScreenSignal(signal, targetAppId);
+      if (!owner)
+        return { kind: "unknown" };
+      if (owner === targetAppId)
+        return { kind: "target" };
+      if (isTransientMobileSystemOwner(owner, platform3)) {
+        return { kind: "transient_external", owner, targetAppId };
+      }
+      return { kind: "external", owner, targetAppId };
+    }
+    function isTargetLikeMobileBoundary2(boundary) {
+      return boundary.kind === "target" || boundary.kind === "unknown";
+    }
+    function mobileBoundaryNote(boundary) {
+      return [
+        "",
+        "## App Boundary",
+        `Foreground app is ${boundary.owner}, outside target app ${boundary.targetAppId}.`,
+        boundary.kind === "transient_external" ? "This looks like a system overlay. Handle or dismiss it if needed, but do not capture it as an app screen." : "The runner excluded this external app screen from the target app evidence and relaunched the target app."
+      ].join("\n");
+    }
+  }
+});
+
 // ../shared/dist/types.js
 function isUIVariant(value) {
   return typeof value === "string" && UI_VARIANTS.includes(value);
@@ -1470,6 +1536,18 @@ function buildAppiumCode(testName, target, steps) {
     `  }`,
     `  throw new Error('No locator resolved. Tried: ' + JSON.stringify(selectors) + (__lastError ? ' (last error: ' + String(__lastError) + ')' : ''));`,
     `}`,
+    ``,
+    `async function __tapAt(driver: WebdriverIO.Browser, x: number, y: number) {`,
+    `  await driver.performActions([{ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' }, actions: [{ type: 'pointerMove', duration: 0, x, y }, { type: 'pointerDown', button: 0 }, { type: 'pause', duration: 100 }, { type: 'pointerUp', button: 0 }] }]);`,
+    `}`,
+    ``,
+    `async function __typeIntoFocused(driver: WebdriverIO.Browser, text: string) {`,
+    `  try {`,
+    `    await (await driver.getActiveElement() as unknown as WebdriverIO.Element).addValue(text);`,
+    `  } catch {`,
+    `    await driver.keys(text);`,
+    `  }`,
+    `}`,
     ...hasSwipe ? [
       ``,
       `// Read the device window with a few retries (matches the runtime executor).`,
@@ -1528,13 +1606,25 @@ function buildAppiumCode(testName, target, steps) {
       const y = Math.round(bounds.y + bounds.height / 2);
       lines.push(`    await driver.performActions([{ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' }, actions: [{ type: 'pointerMove', duration: 0, x: ${x}, y: ${y} }, { type: 'pointerDown', button: 0 }, { type: 'pause', duration: 100 }, { type: 'pointerUp', button: 0 }] }]);`);
     } else if (step.action === "type" && hasSelector) {
-      lines.push(`    await (await findFirst(driver, ${candidatesLiteral})).addValue(${toJsStringLiteral(step.value ?? "")});`);
+      if (bounds) {
+        const x = Math.round(bounds.x + bounds.width / 2);
+        const y = Math.round(bounds.y + bounds.height / 2);
+        lines.push(`    try {`);
+        lines.push(`      await (await findFirst(driver, ${candidatesLiteral})).addValue(${toJsStringLiteral(step.value ?? "")});`);
+        lines.push(`    } catch {`);
+        lines.push(`      await __tapAt(driver, ${x}, ${y});`);
+        lines.push(`      await driver.pause(${MOBILE_FOCUS_SETTLE_MS});`);
+        lines.push(`      await __typeIntoFocused(driver, ${toJsStringLiteral(step.value ?? "")});`);
+        lines.push(`    }`);
+      } else {
+        lines.push(`    await (await findFirst(driver, ${candidatesLiteral})).addValue(${toJsStringLiteral(step.value ?? "")});`);
+      }
     } else if (step.action === "type" && bounds) {
       const x = Math.round(bounds.x + bounds.width / 2);
       const y = Math.round(bounds.y + bounds.height / 2);
-      lines.push(`    await driver.performActions([{ type: 'pointer', id: 'finger1', parameters: { pointerType: 'touch' }, actions: [{ type: 'pointerMove', duration: 0, x: ${x}, y: ${y} }, { type: 'pointerDown', button: 0 }, { type: 'pause', duration: 100 }, { type: 'pointerUp', button: 0 }] }]);`);
+      lines.push(`    await __tapAt(driver, ${x}, ${y});`);
       lines.push(`    await driver.pause(${MOBILE_FOCUS_SETTLE_MS});`);
-      lines.push(`    await (await driver.getActiveElement() as unknown as WebdriverIO.Element).addValue(${toJsStringLiteral(step.value ?? "")});`);
+      lines.push(`    await __typeIntoFocused(driver, ${toJsStringLiteral(step.value ?? "")});`);
     } else if (step.action === "clear" && hasSelector) {
       lines.push(`    await (await findFirst(driver, ${candidatesLiteral})).clearValue();`);
     } else if (step.action === "assertVisible" && hasSelector) {
@@ -4431,6 +4521,7 @@ var require_mobile_explorer = __commonJS({
     var ai_retry_js_1 = require_ai_retry();
     var mobile_source_parser_js_1 = require_mobile_source_parser();
     var mobile_observation_js_1 = require_mobile_observation();
+    var mobile_boundary_js_1 = require_mobile_boundary();
     var MAX_MOBILE_ITERATIONS_SURVEY = 40;
     var MAX_MOBILE_ITERATIONS_DEEP = 60;
     var MAX_SCREENSHOTS = 15;
@@ -4739,8 +4830,9 @@ var require_mobile_explorer = __commonJS({
       }
       return sections.join("\n");
     }
-    function buildSystemPrompt(mode, platform3, enableRecordJourney, maxIterations, appBrief) {
+    function buildSystemPrompt(mode, platform3, enableRecordJourney, maxIterations, appBrief, targetAppId) {
       const platformLabel = platform3 === "IOS" ? "iOS" : "Android";
+      const targetLine = targetAppId ? ` Target app package/bundle: ${targetAppId}.` : "";
       const surveyBody = `You are a mobile QA exploration agent driving a real ${platformLabel} app on a connected device. Your goal: MAP every reachable screen so downstream agents know what to test. You are NOT testing \u2014 you are building a complete screen map.
 
 ## How the loop works
@@ -4758,7 +4850,7 @@ var require_mobile_explorer = __commonJS({
 
 ## Boundaries (survey = map, do not mutate)
 - Do NOT submit forms, save, delete, purchase, or send anything. You MAY open modals/menus to catalog them, then dismiss.
-- Stay inside this app. Do not leave to the system home screen or other apps (mobile_home backgrounds \u2014 avoid it).
+- Stay inside this app.${targetLine} Do not leave to the system home screen or other apps (mobile_home backgrounds \u2014 avoid it). If a tap opens an app store, settings, browser, or another app, do not explore it; return with mobile_back or mobile_relaunch.
 - If you hit a login wall and have no credentials, capture the auth screen and explore what is reachable.
 
 Max iterations: ${maxIterations}. You will be warned near the end.`;
@@ -4776,6 +4868,7 @@ Max iterations: ${maxIterations}. You will be warned near the end.`;
 4. Use mobile_relaunch for a clean, hermetic restart before testing a distinct flow that needs fresh state.
 5. mobile_swipe to scroll; mobile_back to return.
 6. Do NOT trigger irreversible side effects (real payments, sending messages/invites to others). Note them instead.
+7. Stay inside this app.${targetLine} If a tap opens an app store, settings, browser, or another app, do not explore it; return with mobile_back or mobile_relaunch.
 
 Max iterations: ${maxIterations}. You will be warned near the end.`;
       const briefBlock = appBrief ? `
@@ -4801,6 +4894,7 @@ Use this to prioritize which screens and flows to cover.` : "";
       const mode = ctx.mode === "deep" ? "deep" : "survey";
       const platform3 = platformForMedium(ctx.medium);
       const enableRecordJourney = config?.enableRecordJourney ?? mode !== "survey";
+      const targetAppId = ctx.target?.appId?.trim() || void 0;
       const defaultBudget = mode === "deep" ? MAX_MOBILE_ITERATIONS_DEEP : MAX_MOBILE_ITERATIONS_SURVEY;
       const maxIterations = config?.maxIterations && config.maxIterations > 0 ? Math.floor(config.maxIterations) : defaultBudget;
       const modelOverride = ctx.exploreModel ?? null;
@@ -4851,6 +4945,81 @@ Use this to prioritize which screens and flows to cover.` : "";
           return null;
         return resolveSnapshot(xml, windowSize, driverSignal, platform3);
       };
+      const currentBoundary = () => {
+        const current = getLatest();
+        return current ? (0, mobile_boundary_js_1.classifyMobileScreenBoundary)(current.signal, targetAppId, platform3) : { kind: "unknown" };
+      };
+      const absorbResolvedObservation = async (resolved, screenshot, iterationForObservation, source) => {
+        const boundary = (0, mobile_boundary_js_1.classifyMobileScreenBoundary)(resolved.signal, targetAppId, platform3);
+        if (boundary.kind === "target" || boundary.kind === "unknown") {
+          const screenId = ingestSnapshot(resolved, iterationForObservation);
+          captureScreenshot(screenshot, screenId);
+          return { observation: resolved.observation, screenId };
+        }
+        latest = resolved;
+        lastSnapshotIteration = iterationForObservation;
+        if (boundary.kind === "transient_external") {
+          log2(`   System overlay detected from ${source}: ${boundary.owner}; not adding it to target-app survey evidence.`);
+          return {
+            observation: `${resolved.observation}${(0, mobile_boundary_js_1.mobileBoundaryNote)(boundary)}`,
+            screenId: null,
+            transientExternal: true,
+            externalOwner: boundary.owner
+          };
+        }
+        log2(`   External app detected from ${source}: ${boundary.owner}; excluding it from survey evidence and relaunching ${boundary.targetAppId}.`);
+        try {
+          await driver.relaunch();
+          const snap = await driver.snapshot();
+          const recovered = buildResolved(snap.xml, snap.windowSize, snap.screenSignal);
+          if (!recovered) {
+            return {
+              observation: `(left target app ${boundary.targetAppId} for ${boundary.owner}; relaunched target app, but no UI tree was returned)`,
+              screenId: null,
+              externalBlocked: true,
+              externalOwner: boundary.owner
+            };
+          }
+          const recoveredBoundary = (0, mobile_boundary_js_1.classifyMobileScreenBoundary)(recovered.signal, targetAppId, platform3);
+          latest = recovered;
+          lastSnapshotIteration = iterationForObservation;
+          if (recoveredBoundary.kind === "target" || recoveredBoundary.kind === "unknown") {
+            const screenId = ingestSnapshot(recovered, iterationForObservation);
+            captureScreenshot(snap.screenshot, screenId);
+            return {
+              observation: recovered.observation,
+              screenId,
+              externalBlocked: true,
+              externalOwner: boundary.owner
+            };
+          }
+          if (recoveredBoundary.kind === "transient_external") {
+            log2(`   Relaunch surfaced system overlay ${recoveredBoundary.owner}; not adding it to target-app survey evidence.`);
+            return {
+              observation: `${recovered.observation}${(0, mobile_boundary_js_1.mobileBoundaryNote)(recoveredBoundary)}`,
+              screenId: null,
+              externalBlocked: true,
+              transientExternal: true,
+              externalOwner: boundary.owner
+            };
+          }
+          log2(`   Relaunch still outside target app (${recoveredBoundary.owner}); no screen recorded.`);
+          return {
+            observation: `(left target app ${boundary.targetAppId} for ${boundary.owner}; relaunch still showed ${recoveredBoundary.owner}, so no screen was recorded)`,
+            screenId: null,
+            externalBlocked: true,
+            externalOwner: boundary.owner
+          };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          return {
+            observation: `(left target app ${boundary.targetAppId} for ${boundary.owner}; failed to relaunch target app: ${message})`,
+            screenId: null,
+            externalBlocked: true,
+            externalOwner: boundary.owner
+          };
+        }
+      };
       const resolveRef = (ref) => {
         if (typeof ref !== "string" || !latest)
           return null;
@@ -4859,7 +5028,7 @@ Use this to prioritize which screens and flows to cover.` : "";
           return null;
         return { element, bounds: element.bounds };
       };
-      const systemPrompt = buildSystemPrompt(mode, platform3, enableRecordJourney, maxIterations, ctx.appBrief);
+      const systemPrompt = buildSystemPrompt(mode, platform3, enableRecordJourney, maxIterations, ctx.appBrief, targetAppId);
       const kickoff = buildKickoffMessage(mode);
       const recentExchanges = [];
       const transientDirectives = [];
@@ -4889,9 +5058,13 @@ Use this to prioritize which screens and flows to cover.` : "";
           const seed = await driver.snapshot();
           const resolved = buildResolved(seed.xml, seed.windowSize, seed.screenSignal);
           if (resolved) {
-            const screenId = ingestSnapshot(resolved, 0);
-            captureScreenshot(seed.screenshot, screenId);
-            log2(`Seed snapshot: screen ${screenId} (${resolved.screen.elements.length} elements)`);
+            const absorbed = await absorbResolvedObservation(resolved, seed.screenshot, 0, "seed snapshot");
+            if (absorbed.screenId) {
+              const elementCount = state2.getScreen(absorbed.screenId)?.elements.length ?? resolved.screen.elements.length;
+              log2(`Seed snapshot: screen ${absorbed.screenId} (${elementCount} elements)`);
+            } else {
+              log2("Seed snapshot was outside the target app and was not recorded.");
+            }
           } else {
             log2("Seed snapshot returned no XML \u2014 the agent must call mobile_snapshot.");
           }
@@ -5032,9 +5205,9 @@ Exploration complete: ${summary}`);
                 mode,
                 latest: getLatest,
                 buildResolved,
-                ingestSnapshot,
+                absorbResolvedObservation,
                 resolveRef,
-                captureScreenshot,
+                currentBoundary,
                 collectedTransitions,
                 counters,
                 journeys,
@@ -5069,9 +5242,21 @@ Exploration complete: ${summary}`);
         counters.pagesDiscovered = collectedPages.length;
       }
       log2(`Mobile explore phase done \u2014 ${collectedPages.length} screens, ${collectedTransitions.length} transitions, ${journeys.length} journeys, ${counters.elementsFound} elements observed.`);
+      const recordedJourneys = journeys.map((journey) => {
+        const routes = journey.screenIds && journey.screenIds.length > 0 ? journey.screenIds : [journey.screenId];
+        return {
+          name: journey.name,
+          route: journey.screenId,
+          routes,
+          steps: journey.steps,
+          expectedOutcome: journey.expectedOutcome,
+          iteration: journey.iteration
+        };
+      });
       const result = {
         collectedPages,
         collectedTransitions,
+        recordedJourneys,
         screenshots,
         exploreStats: {
           pagesDiscovered: counters.pagesDiscovered,
@@ -5092,15 +5277,13 @@ Exploration complete: ${summary}`);
       return result;
     }
     async function dispatchMobileTool(args) {
-      const { toolName, toolArgs, iteration, driver, state: state2, enableRecordJourney, latest, buildResolved, ingestSnapshot, resolveRef, captureScreenshot, collectedTransitions, counters, journeys, log: log2 } = args;
-      const absorbActionResult = (xml, screenshot) => {
-        const resolved = buildResolved(xml, latest()?.screen.windowSize ?? null, void 0);
+      const { toolName, toolArgs, iteration, driver, state: state2, enableRecordJourney, latest, buildResolved, absorbResolvedObservation, resolveRef, currentBoundary, collectedTransitions, counters, journeys, log: log2 } = args;
+      const absorbActionResult = (actionResult, source) => {
+        const resolved = buildResolved(actionResult.source, latest()?.screen.windowSize ?? null, actionResult.screenSignal);
         if (!resolved) {
-          return { observation: "(no UI tree returned)", screenId: null };
+          return Promise.resolve({ observation: "(no UI tree returned)", screenId: null });
         }
-        const screenId = ingestSnapshot(resolved, iteration);
-        captureScreenshot(screenshot, screenId);
-        return { observation: resolved.observation, screenId };
+        return absorbResolvedObservation(resolved, actionResult.screenshot, iteration, source);
       };
       switch (toolName) {
         // ----- Observation -----
@@ -5110,12 +5293,16 @@ Exploration complete: ${summary}`);
           if (!resolved) {
             return { ok: false, error: "snapshot returned no UI tree" };
           }
-          const screenId = ingestSnapshot(resolved, iteration);
-          captureScreenshot(snap.screenshot, screenId);
-          log2(`   Snapshot: screen ${screenId} (${resolved.screen.elements.length} elements)`);
+          const absorbed = await absorbResolvedObservation(resolved, snap.screenshot, iteration, "mobile_snapshot");
+          if (absorbed.screenId) {
+            const elementCount = state2.getScreen(absorbed.screenId)?.elements.length ?? resolved.screen.elements.length;
+            log2(`   Snapshot: screen ${absorbed.screenId} (${elementCount} elements)`);
+          }
           return {
-            screenId,
-            observation: resolved.observation,
+            screenId: absorbed.screenId,
+            observation: absorbed.observation,
+            ...absorbed.externalBlocked ? { blockedExternalApp: true, externalApp: absorbed.externalOwner } : {},
+            ...absorbed.transientExternal ? { transientExternalApp: true, externalApp: absorbed.externalOwner } : {},
             progress: `${state2.getScreenCount()} screens, ${collectedTransitions.length} transitions, ${journeys.length} journeys`
           };
         }
@@ -5126,14 +5313,21 @@ Exploration complete: ${summary}`);
             return { ok: false, error: `Unknown element ref "${String(toolArgs.ref)}". Call mobile_snapshot first; refs are only valid for the latest snapshot.` };
           }
           const fromScreenId = state2.getCurrentScreenId();
+          const boundaryBeforeAction = currentBoundary();
+          const startedOutsideTarget = boundaryBeforeAction.kind !== "target" && boundaryBeforeAction.kind !== "unknown";
           const actionResult = await driver.tap(resolved.bounds);
-          const { observation, screenId } = absorbActionResult(actionResult.source, actionResult.screenshot);
-          autoRecordTransition(state2, collectedTransitions, counters, fromScreenId, screenId, String(toolArgs.ref), "tap");
+          const absorbed = await absorbActionResult(actionResult, "mobile_tap");
+          const { observation, screenId } = absorbed;
+          if (!startedOutsideTarget && !absorbed.externalBlocked && !absorbed.transientExternal) {
+            autoRecordTransition(state2, collectedTransitions, counters, fromScreenId, screenId, String(toolArgs.ref), "tap");
+          }
           return {
             ok: actionResult.ok,
             ...actionResult.error ? { error: actionResult.error } : {},
             screenId,
-            observation
+            observation,
+            ...absorbed.externalBlocked ? { blockedExternalApp: true, externalApp: absorbed.externalOwner } : {},
+            ...absorbed.transientExternal ? { transientExternalApp: true, externalApp: absorbed.externalOwner } : {}
           };
         }
         // ----- Type -----
@@ -5144,12 +5338,15 @@ Exploration complete: ${summary}`);
           }
           const value = typeof toolArgs.value === "string" ? toolArgs.value : String(toolArgs.value ?? "");
           const actionResult = await driver.type(value, resolved.bounds);
-          const { observation, screenId } = absorbActionResult(actionResult.source, actionResult.screenshot);
+          const absorbed = await absorbActionResult(actionResult, "mobile_type");
+          const { observation, screenId } = absorbed;
           return {
             ok: actionResult.ok,
             ...actionResult.error ? { error: actionResult.error } : {},
             screenId,
-            observation
+            observation,
+            ...absorbed.externalBlocked ? { blockedExternalApp: true, externalApp: absorbed.externalOwner } : {},
+            ...absorbed.transientExternal ? { transientExternalApp: true, externalApp: absorbed.externalOwner } : {}
           };
         }
         // ----- Clear -----
@@ -5159,12 +5356,15 @@ Exploration complete: ${summary}`);
             return { ok: false, error: `Unknown element ref "${String(toolArgs.ref)}". Call mobile_snapshot first.` };
           }
           const actionResult = await driver.clear(resolved.bounds);
-          const { observation, screenId } = absorbActionResult(actionResult.source, actionResult.screenshot);
+          const absorbed = await absorbActionResult(actionResult, "mobile_clear");
+          const { observation, screenId } = absorbed;
           return {
             ok: actionResult.ok,
             ...actionResult.error ? { error: actionResult.error } : {},
             screenId,
-            observation
+            observation,
+            ...absorbed.externalBlocked ? { blockedExternalApp: true, externalApp: absorbed.externalOwner } : {},
+            ...absorbed.transientExternal ? { transientExternalApp: true, externalApp: absorbed.externalOwner } : {}
           };
         }
         // ----- Swipe -----
@@ -5175,36 +5375,49 @@ Exploration complete: ${summary}`);
           }
           const distance = typeof toolArgs.distance === "number" ? toolArgs.distance : void 0;
           const actionResult = await driver.swipe(direction, distance);
-          const { observation, screenId } = absorbActionResult(actionResult.source, actionResult.screenshot);
+          const absorbed = await absorbActionResult(actionResult, "mobile_swipe");
+          const { observation, screenId } = absorbed;
           return {
             ok: actionResult.ok,
             ...actionResult.error ? { error: actionResult.error } : {},
             screenId,
-            observation
+            observation,
+            ...absorbed.externalBlocked ? { blockedExternalApp: true, externalApp: absorbed.externalOwner } : {},
+            ...absorbed.transientExternal ? { transientExternalApp: true, externalApp: absorbed.externalOwner } : {}
           };
         }
         // ----- Back -----
         case "mobile_back": {
           const fromScreenId = state2.getCurrentScreenId();
+          const boundaryBeforeAction = currentBoundary();
+          const startedOutsideTarget = boundaryBeforeAction.kind !== "target" && boundaryBeforeAction.kind !== "unknown";
           const actionResult = await driver.back();
-          const { observation, screenId } = absorbActionResult(actionResult.source, actionResult.screenshot);
-          autoRecordTransition(state2, collectedTransitions, counters, fromScreenId, screenId, void 0, "back");
+          const absorbed = await absorbActionResult(actionResult, "mobile_back");
+          const { observation, screenId } = absorbed;
+          if (!startedOutsideTarget && !absorbed.externalBlocked && !absorbed.transientExternal) {
+            autoRecordTransition(state2, collectedTransitions, counters, fromScreenId, screenId, void 0, "back");
+          }
           return {
             ok: actionResult.ok,
             ...actionResult.error ? { error: actionResult.error } : {},
             screenId,
-            observation
+            observation,
+            ...absorbed.externalBlocked ? { blockedExternalApp: true, externalApp: absorbed.externalOwner } : {},
+            ...absorbed.transientExternal ? { transientExternalApp: true, externalApp: absorbed.externalOwner } : {}
           };
         }
         // ----- Home (backgrounds only) -----
         case "mobile_home": {
           const actionResult = await driver.home();
-          const { observation, screenId } = absorbActionResult(actionResult.source, actionResult.screenshot);
+          const absorbed = await absorbActionResult(actionResult, "mobile_home");
+          const { observation, screenId } = absorbed;
           return {
             ok: actionResult.ok,
             ...actionResult.error ? { error: actionResult.error } : {},
             screenId,
             observation,
+            ...absorbed.externalBlocked ? { blockedExternalApp: true, externalApp: absorbed.externalOwner } : {},
+            ...absorbed.transientExternal ? { transientExternalApp: true, externalApp: absorbed.externalOwner } : {},
             note: "Home only backgrounds the app. Use mobile_relaunch for a clean restart."
           };
         }
@@ -5217,9 +5430,15 @@ Exploration complete: ${summary}`);
           if (!resolved) {
             return { ok: true, note: "relaunched; no UI tree returned \u2014 call mobile_snapshot." };
           }
-          const screenId = ingestSnapshot(resolved, iteration);
-          captureScreenshot(snap.screenshot, screenId);
-          return { ok: true, screenId, observation: resolved.observation, note: "App relaunched (clean state)." };
+          const absorbed = await absorbResolvedObservation(resolved, snap.screenshot, iteration, "mobile_relaunch");
+          return {
+            ok: true,
+            screenId: absorbed.screenId,
+            observation: absorbed.observation,
+            ...absorbed.externalBlocked ? { blockedExternalApp: true, externalApp: absorbed.externalOwner } : {},
+            ...absorbed.transientExternal ? { transientExternalApp: true, externalApp: absorbed.externalOwner } : {},
+            note: "App relaunched (clean state)."
+          };
         }
         // ----- Deep-link (guarded) -----
         case "mobile_open_deeplink": {
@@ -5228,18 +5447,32 @@ Exploration complete: ${summary}`);
             return { ok: false, error: `Refused to open deep link "${deeplink}" (empty or dangerous scheme).` };
           }
           const fromScreenId = state2.getCurrentScreenId();
+          const boundaryBeforeAction = currentBoundary();
+          const startedOutsideTarget = boundaryBeforeAction.kind !== "target" && boundaryBeforeAction.kind !== "unknown";
           const actionResult = await driver.openDeepLink(deeplink);
-          const { observation, screenId } = absorbActionResult(actionResult.source, actionResult.screenshot);
-          autoRecordTransition(state2, collectedTransitions, counters, fromScreenId, screenId, void 0, "deeplink");
+          const absorbed = await absorbActionResult(actionResult, "mobile_open_deeplink");
+          const { observation, screenId } = absorbed;
+          if (!startedOutsideTarget && !absorbed.externalBlocked && !absorbed.transientExternal) {
+            autoRecordTransition(state2, collectedTransitions, counters, fromScreenId, screenId, void 0, "deeplink");
+          }
           return {
             ok: actionResult.ok,
             ...actionResult.error ? { error: actionResult.error } : {},
             screenId,
-            observation
+            observation,
+            ...absorbed.externalBlocked ? { blockedExternalApp: true, externalApp: absorbed.externalOwner } : {},
+            ...absorbed.transientExternal ? { transientExternalApp: true, externalApp: absorbed.externalOwner } : {}
           };
         }
         // ----- capture_screen (mark + annotate current screen) -----
         case "capture_screen": {
+          const boundary = currentBoundary();
+          if (boundary.kind === "external" || boundary.kind === "transient_external") {
+            return {
+              ok: false,
+              error: `Current foreground app is ${boundary.owner}, outside target app ${boundary.targetAppId}. It was not captured. Return to the target app with mobile_back or mobile_relaunch.`
+            };
+          }
           const screenId = state2.getCurrentScreenId();
           if (!screenId) {
             return { ok: false, error: "No current screen \u2014 call mobile_snapshot first." };
@@ -5290,6 +5523,13 @@ Exploration complete: ${summary}`);
           if (!enableRecordJourney) {
             return { ok: false, error: "record_journey is not available in survey mode." };
           }
+          const boundary = currentBoundary();
+          if (boundary.kind === "external" || boundary.kind === "transient_external") {
+            return {
+              ok: false,
+              error: `Current foreground app is ${boundary.owner}, outside target app ${boundary.targetAppId}. External app screens cannot be recorded as a target-app journey.`
+            };
+          }
           const name = typeof toolArgs.name === "string" ? toolArgs.name : "";
           const screenId = typeof toolArgs.screenId === "string" && toolArgs.screenId ? toolArgs.screenId : state2.getCurrentScreenId() ?? "";
           const steps = Array.isArray(toolArgs.steps) ? toolArgs.steps.filter((s) => typeof s === "string") : [];
@@ -7080,7 +7320,7 @@ Each entry is exactly one of:
       const existingNamesLower = new Set(existingTestNames.map((n) => n.toLowerCase()));
       const usedNames = /* @__PURE__ */ new Set();
       const validTypes = /* @__PURE__ */ new Set(["HAPPY_PATH", "EDGE_CASE", "USER_JOURNEY", "REGRESSION", "BUG_REPORT"]);
-      const validOutcomeTypes = /* @__PURE__ */ new Set(["url", "element-visible", "text-visible", "value-match", "element-hidden"]);
+      const validOutcomeTypes = /* @__PURE__ */ new Set(["url", "screen-visible", "element-visible", "text-visible", "value-match", "element-hidden"]);
       const validVariants = /* @__PURE__ */ new Set(["happy", "validation", "bug"]);
       const validCriticalities = /* @__PURE__ */ new Set(["critical", "high", "medium", "low"]);
       const inferOutcomeTypeFromDescription = (description) => /\b(?:heading|button|link|menu\s*item|menuitem|tab|card|modal|dialog|sidebar(?:\s+item)?|nav\s+item|navigation\s+link|form\s+label|field\s+label|avatar|banner)\b/i.test(description) ? "element-visible" : "text-visible";
@@ -7554,8 +7794,8 @@ Each entry is exactly one of:
       const agentModel = options.modelOverride ? (0, ai_provider_js_1.resolveModelForTask)(options.modelOverride, "agent") : (0, ai_provider_js_1.getModel)("agent");
       const plannerMaxTokens = getAIPlannerMaxTokens(agentModel);
       logs2.push(`AI planner [${context.mode}]: ${siteMap.pages.length} pages, ${evidence.recordedJourneys.length} journeys, budget ${context.testBudget}`);
-      const systemPrompt = context.mode === "survey" ? SURVEY_SYSTEM_PROMPT : exports.SCENARIO_SYSTEM_PROMPT;
-      const userPrompt = formatEvidenceForPlanner(compressed, evidence, context);
+      const systemPrompt = options.systemPromptOverride ?? (context.mode === "survey" ? SURVEY_SYSTEM_PROMPT : exports.SCENARIO_SYSTEM_PROMPT);
+      const userPrompt = options.userPromptOverride ?? formatEvidenceForPlanner(compressed, evidence, context);
       logs2.push(`AI planner: ~${Math.ceil(userPrompt.length / 3.5)} input tokens`);
       const aiClient = options.aiClient ?? (options.modelOverride ? (0, ai_provider_js_1.getClientForModel)(options.modelOverride) : (0, ai_provider_js_1.getAIClient)());
       const messages = [
@@ -7771,6 +8011,14 @@ var require_mobile_discovery_prompts = __commonJS({
     exports.runMobileAIPlanner = runMobileAIPlanner;
     var ai_provider_js_1 = require_ai_provider();
     var discover_ai_planner_js_1 = require_discover_ai_planner();
+    function isTargetAppScreenId(screenId, appId) {
+      if (!appId)
+        return true;
+      return screenId === appId || screenId.startsWith(`${appId}#`) || screenId.startsWith(`${appId}.`);
+    }
+    function targetAppScreens(graph, appId) {
+      return [...graph.screens.values()].filter((state2) => isTargetAppScreenId(state2.screenId, appId));
+    }
     exports.MOBILE_SURVEY_SYSTEM_PROMPT = `You are a feature analyst for a native mobile application (iOS or Android). You receive evidence from an AI explorer that mapped the app's screens by tapping, typing, and swiping through the live UI. Your job is to organize screens into meaningful feature groups.
 
 ## Output Discipline
@@ -8000,7 +8248,8 @@ ${targetBits.length > 0 ? targetBits.join(" ") : "native mobile app"}`);
       if (context.featureName) {
         sections.push(`## Feature: ${context.featureName}`);
       }
-      const orderedScreens = [...graph.screens.values()].sort((a, b) => a.firstSeenIteration - b.firstSeenIteration);
+      const orderedScreens = targetAppScreens(graph, context.appId).sort((a, b) => a.firstSeenIteration - b.firstSeenIteration);
+      const includedScreenIds = new Set(orderedScreens.map((state2) => state2.screenId));
       sections.push(`## Screens Discovered (${orderedScreens.length})`);
       for (const state2 of orderedScreens) {
         const name = screenDisplayName(state2);
@@ -8022,7 +8271,7 @@ ${targetBits.length > 0 ? targetBits.join(" ") : "native mobile app"}`);
         for (const state2 of orderedScreens)
           nameById.set(state2.screenId, screenDisplayName(state2));
         const lines = ["## Observed Screen Transitions"];
-        for (const t of graph.transitions.slice(0, MAX_TRANSITIONS)) {
+        for (const t of graph.transitions.filter((transition) => includedScreenIds.has(transition.fromScreenId) && includedScreenIds.has(transition.toScreenId)).slice(0, MAX_TRANSITIONS)) {
           const from = nameById.get(t.fromScreenId) ?? t.fromScreenId;
           const to = nameById.get(t.toScreenId) ?? t.toScreenId;
           const via = t.viaRef ? ` via ${t.viaRef}` : "";
@@ -8108,7 +8357,7 @@ ${constraints.join("\n")}`);
       const now = /* @__PURE__ */ new Date();
       const idByScreen = /* @__PURE__ */ new Map();
       let pageSeq = 0;
-      const orderedScreens = [...graph.screens.values()].sort((a, b) => a.firstSeenIteration - b.firstSeenIteration);
+      const orderedScreens = targetAppScreens(graph, meta.appId).sort((a, b) => a.firstSeenIteration - b.firstSeenIteration);
       for (const state2 of orderedScreens) {
         idByScreen.set(state2.screenId, `mpage-${pageSeq++}`);
       }
@@ -8167,6 +8416,135 @@ ${constraints.join("\n")}`);
         seedFixtures: []
       };
     }
+    function buildMobileFeatureGroupsFromGraph(graph, appId) {
+      const groups = /* @__PURE__ */ new Map();
+      const orderedScreens = targetAppScreens(graph, appId).filter((state2) => state2.screenType?.toLowerCase() !== "error").sort((a, b) => a.firstSeenIteration - b.firstSeenIteration);
+      const includedScreenIds = new Set(orderedScreens.map((state2) => state2.screenId));
+      for (const state2 of orderedScreens) {
+        const groupName = state2.screenType === "auth" ? "Authentication" : screenDisplayName(state2);
+        const group = groups.get(groupName) ?? {
+          name: groupName,
+          description: `Native mobile screens related to ${groupName}.`,
+          routes: [],
+          criticality: state2.screenType === "auth" ? "critical" : "medium",
+          pages: [],
+          flows: []
+        };
+        group.routes.push(state2.screenId);
+        group.pages?.push({
+          route: state2.screenId,
+          type: state2.screenType ?? "UNKNOWN",
+          summary: `${state2.elements.filter((el) => el.actionable).length} actionable element(s)`
+        });
+        groups.set(groupName, group);
+      }
+      const nameById = /* @__PURE__ */ new Map();
+      for (const state2 of graph.screens.values()) {
+        nameById.set(state2.screenId, screenDisplayName(state2));
+      }
+      for (const transition of graph.transitions) {
+        if (!includedScreenIds.has(transition.fromScreenId) || !includedScreenIds.has(transition.toScreenId))
+          continue;
+        const from = graph.screens.get(transition.fromScreenId);
+        const to = graph.screens.get(transition.toScreenId);
+        if (!from || !to)
+          continue;
+        const groupName = from.screenType === "auth" ? "Authentication" : screenDisplayName(from);
+        const group = groups.get(groupName);
+        if (!group)
+          continue;
+        const via = transition.viaRef ? ` via ${transition.viaRef}` : "";
+        group.flows?.push(`${nameById.get(transition.fromScreenId) ?? transition.fromScreenId} \u2192 ${nameById.get(transition.toScreenId) ?? transition.toScreenId} (${transition.action}${via})`);
+      }
+      return [...groups.values()];
+    }
+    function buildMobileFallbackScenarios(input) {
+      if (input.mode === "survey")
+        return [];
+      const orderedScreens = targetAppScreens(input.graph, input.appId).filter((state2) => state2.screenType?.toLowerCase() !== "error").filter((state2) => state2.visited || state2.firstSeenIteration === 0).sort((a, b) => a.firstSeenIteration - b.firstSeenIteration);
+      if (orderedScreens.length === 0)
+        return [];
+      const entryScreenId = orderedScreens[0].screenId;
+      const usedNames = new Set((input.existingTestNames ?? []).map((name) => name.toLowerCase()));
+      const scenarios = [];
+      const budget = Math.max(1, input.testBudget || orderedScreens.length);
+      for (const state2 of orderedScreens) {
+        if (scenarios.length >= budget)
+          break;
+        const screenName = screenDisplayName(state2);
+        const baseName = `${screenName} - Screen Reachability`;
+        const name = usedNames.has(baseName.toLowerCase()) ? `${baseName} ${state2.firstSeenIteration + 1}` : baseName;
+        if (usedNames.has(name.toLowerCase()))
+          continue;
+        usedNames.add(name.toLowerCase());
+        const actionableLabels = state2.elements.filter((el) => el.actionable).map((el) => el.label?.trim() || el.text?.trim() || el.accessibilityId || shortResourceId(el.resourceId ?? "") || compactRole(el.role)).filter((label) => Boolean(label)).slice(0, 3);
+        const steps = [
+          { action: "Relaunch the app from a clean state", target: entryScreenId },
+          {
+            action: state2.screenId === entryScreenId ? `Verify the launch screen is ${screenName}` : `Navigate through the app until the ${screenName} screen is visible`,
+            target: state2.screenId
+          }
+        ];
+        if (actionableLabels.length > 0) {
+          steps.push({
+            action: `Verify expected native controls are available: ${actionableLabels.join(", ")}`,
+            target: state2.screenId
+          });
+        }
+        scenarios.push({
+          name,
+          type: "HAPPY_PATH",
+          priority: state2.screenType === "auth" ? 1 : 3,
+          variant: "happy",
+          featureGroup: state2.screenType === "auth" ? "Authentication" : screenName,
+          goal: `User can reach and inspect the ${screenName} screen`,
+          steps,
+          expectedOutcomes: [{
+            type: "screen-visible",
+            description: `${screenName} screen is visible`,
+            reliability: "medium"
+          }],
+          entryRoute: entryScreenId,
+          startFromLanding: true,
+          targetPages: [state2.screenId],
+          evidence: { observedLocators: [], observedTransitions: [] },
+          prerequisites: []
+        });
+      }
+      return scenarios;
+    }
+    function filterRecordedJourneysToSiteMap(journeys, siteMap) {
+      if (!journeys?.length)
+        return [];
+      const validRoutes = new Set(siteMap.pages.map((page) => page.route));
+      const filtered = [];
+      for (const journey of journeys) {
+        const routes = (journey.routes?.length ? journey.routes : [journey.route]).filter((route2) => validRoutes.has(route2));
+        if (routes.length === 0)
+          continue;
+        filtered.push({
+          ...journey,
+          route: validRoutes.has(journey.route) ? journey.route : routes[0],
+          routes
+        });
+      }
+      return filtered;
+    }
+    function filterFeatureGroupsToSiteMap(groups, siteMap) {
+      if (groups.length === 0)
+        return [];
+      const validRoutes = new Set(siteMap.pages.map((page) => page.route));
+      return groups.flatMap((group) => {
+        const routes = group.routes.filter((route2) => validRoutes.has(route2));
+        if (routes.length === 0)
+          return [];
+        return [{
+          ...group,
+          routes,
+          pages: group.pages?.filter((page) => validRoutes.has(page.route))
+        }];
+      });
+    }
     async function runMobileAIPlanner(input, options = {}) {
       const planner = options.planner ?? discover_ai_planner_js_1.runAIPlanner;
       const shouldBuildMobileAIClient = (process.env.SERVER_URL ?? "").trim().length > 0 || !options.planner;
@@ -8175,11 +8553,12 @@ ${constraints.join("\n")}`);
         projectId: input.projectId,
         appId: input.appId
       });
+      const recordedJourneys = filterRecordedJourneysToSiteMap(input.recordedJourneys, siteMap);
       const collectedPages = input.collectedPages ?? [];
       const collectedTransitions = input.collectedTransitions ?? [];
-      const visitedRoutes = [...input.graph.screens.values()].filter((s) => s.visited).map((s) => s.screenId);
-      return planner(siteMap, {
-        recordedJourneys: input.recordedJourneys ?? [],
+      const visitedRoutes = targetAppScreens(input.graph, input.appId).filter((s) => s.visited).map((s) => s.screenId);
+      const result = await planner(siteMap, {
+        recordedJourneys,
         collectedPages,
         collectedTransitions,
         visitedRoutes
@@ -8197,8 +8576,52 @@ ${constraints.join("\n")}`);
       }, {
         modelOverride: options.modelOverride,
         onAICall: options.onAICall,
-        ...aiClient ? { aiClient } : {}
+        ...aiClient ? { aiClient } : {},
+        systemPromptOverride: input.mode === "survey" ? exports.MOBILE_SURVEY_SYSTEM_PROMPT : exports.MOBILE_SCENARIO_SYSTEM_PROMPT,
+        userPromptOverride: formatMobileEvidenceForPlanner(input.graph, {
+          appBrief: input.appBrief,
+          appId: input.appId,
+          platform: input.platform,
+          featureName: input.featureName,
+          existingTestNames: input.existingTestNames,
+          existingFeatureNames: input.existingFeatureNames,
+          recordedJourneys,
+          credentials: input.credentials,
+          testBudget: input.testBudget,
+          incremental: input.incremental
+        })
       });
+      const plannerFeatureGroups = filterFeatureGroupsToSiteMap(result.featureGroups, siteMap);
+      const mobileFeatureGroups = plannerFeatureGroups.length > 0 ? plannerFeatureGroups : buildMobileFeatureGroupsFromGraph(input.graph, input.appId);
+      if (input.mode !== "survey" && result.scenarios.length === 0 && input.graph.screens.size > 0) {
+        const fallbackScenarios = buildMobileFallbackScenarios(input);
+        if (fallbackScenarios.length > 0) {
+          return {
+            ...result,
+            scenarios: fallbackScenarios,
+            featureGroups: mobileFeatureGroups,
+            logs: [
+              ...result.logs,
+              `Mobile fallback: synthesized ${fallbackScenarios.length} screen-reachability scenario(s) from the native screen graph`
+            ],
+            fallbackUsed: true,
+            fallbackReason: result.fallbackReason ?? "Mobile planner produced no scenarios"
+          };
+        }
+      }
+      if (input.mode === "survey" && result.featureGroups.length === 0 && mobileFeatureGroups.length > 0) {
+        return {
+          ...result,
+          featureGroups: mobileFeatureGroups,
+          logs: [
+            ...result.logs,
+            `Mobile fallback: synthesized ${mobileFeatureGroups.length} feature group(s) from the native screen graph`
+          ],
+          fallbackUsed: true,
+          fallbackReason: result.fallbackReason ?? "Mobile planner produced no feature groups"
+        };
+      }
+      return { ...result, featureGroups: mobileFeatureGroups };
     }
   }
 });
@@ -8217,6 +8640,7 @@ var require_mobile_generator = __commonJS({
     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();
+    var mobile_boundary_js_1 = require_mobile_boundary();
     var MAX_SCENARIO_ITERATIONS = 30;
     var MAX_RECENT_EXCHANGES = 24;
     var OBSERVATION_MAX_ELEMENTS = 50;
@@ -8402,8 +8826,9 @@ var require_mobile_generator = __commonJS({
     function hasStableId(element) {
       return !!nonEmpty2(element.accessibilityId) || !!nonEmpty2(element.resourceId);
     }
-    function buildSystemPrompt(platform3) {
+    function buildSystemPrompt(platform3, targetAppId) {
       const platformLabel = platform3 === "IOS" ? "iOS" : "Android";
+      const targetLine = targetAppId ? ` Target app package/bundle: ${targetAppId}.` : "";
       return `You are an expert mobile QA agent generating ONE automated test by driving a real ${platformLabel} app on a connected device. The app has just been relaunched into a clean state.
 
 ## How the loop works
@@ -8423,7 +8848,8 @@ var require_mobile_generator = __commonJS({
 - Re-snapshot before every assertion so the ref is fresh.
 - Assert the OUTCOME of the flow (the new screen / new content), not the control you just tapped.
 - Do NOT trigger irreversible side effects (real payments, sending messages to others) \u2014 note them and assert what you safely can.
-- Stay inside this app. Finish promptly once the outcome is proven.
+- 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.
+- Finish promptly once the outcome is proven.
 
 Max iterations: ${MAX_SCENARIO_ITERATIONS}. You will be warned near the end.`;
     }
@@ -8496,7 +8922,7 @@ Start by calling mobile_snapshot, then execute the steps. Finish with at least o
       }
     }
     async function runScenarioLoop(args) {
-      const { scenario, driver, platform: platform3, maxIterations, agentModel, provider, aiClient, auditGroupId, onAICall, log: log2 } = args;
+      const { scenario, driver, platform: platform3, maxIterations, agentModel, provider, aiClient, auditGroupId, onAICall, onScreenshot, targetAppId, log: log2 } = args;
       const actions = [];
       let assertCount = 0;
       let finish = null;
@@ -8510,14 +8936,98 @@ Start by calling mobile_snapshot, then execute the steps. Finish with at least o
         const fromActivity = signal.activity ? signal.activity.split(".").pop() : void 0;
         return nonEmpty2(fromActivity) ?? nonEmpty2(signal.bundleId) ?? `screen-${signal.screenHash.slice(0, 8)}`;
       };
-      const ingest = (xml, driverSignal, windowSize) => {
-        if (!xml)
-          return null;
-        const resolved = resolveSnapshot(xml, windowSize ?? latest?.screen.windowSize ?? null, driverSignal, platform3);
+      const setLatest = (resolved) => {
         latest = resolved;
         lastScreenName = screenNameFor(resolved);
         return resolved;
       };
+      const buildResolved = (xml, driverSignal, windowSize) => {
+        if (!xml)
+          return null;
+        return resolveSnapshot(xml, windowSize ?? latest?.screen.windowSize ?? null, driverSignal, platform3);
+      };
+      const emitScreenshot = (base64) => {
+        if (!base64)
+          return;
+        try {
+          onScreenshot?.(base64);
+        } catch {
+        }
+      };
+      const absorbResolvedObservation = async (resolved, screenshot, source) => {
+        const boundary = (0, mobile_boundary_js_1.classifyMobileScreenBoundary)(resolved.signal, targetAppId, platform3);
+        if ((0, mobile_boundary_js_1.isTargetLikeMobileBoundary)(boundary)) {
+          setLatest(resolved);
+          emitScreenshot(screenshot);
+          return { resolved, observation: resolved.observation };
+        }
+        setLatest(resolved);
+        if (boundary.kind === "transient_external") {
+          log2(`  system overlay detected from ${source}: ${boundary.owner}; not recording it as a target-app step.`);
+          return {
+            resolved,
+            observation: `${resolved.observation}${(0, mobile_boundary_js_1.mobileBoundaryNote)(boundary)}`,
+            transientExternal: true,
+            externalOwner: boundary.owner
+          };
+        }
+        log2(`  external app detected from ${source}: ${boundary.owner}; rejecting the action and relaunching ${boundary.targetAppId}.`);
+        try {
+          await driver.relaunch();
+          const snap = await driver.snapshot();
+          const recovered = buildResolved(snap.xml, snap.screenSignal, snap.windowSize);
+          if (!recovered) {
+            return {
+              resolved: null,
+              observation: `(left target app ${boundary.targetAppId} for ${boundary.owner}; relaunched target app, but no UI tree was returned)`,
+              externalBlocked: true,
+              externalOwner: boundary.owner
+            };
+          }
+          const recoveredBoundary = (0, mobile_boundary_js_1.classifyMobileScreenBoundary)(recovered.signal, targetAppId, platform3);
+          setLatest(recovered);
+          if ((0, mobile_boundary_js_1.isTargetLikeMobileBoundary)(recoveredBoundary)) {
+            emitScreenshot(snap.screenshot);
+            return {
+              resolved: recovered,
+              observation: recovered.observation,
+              externalBlocked: true,
+              externalOwner: boundary.owner
+            };
+          }
+          if (recoveredBoundary.kind === "transient_external") {
+            log2(`  relaunch surfaced system overlay ${recoveredBoundary.owner}; not recording it as a target-app step.`);
+            return {
+              resolved: recovered,
+              observation: `${recovered.observation}${(0, mobile_boundary_js_1.mobileBoundaryNote)(recoveredBoundary)}`,
+              externalBlocked: true,
+              transientExternal: true,
+              externalOwner: boundary.owner
+            };
+          }
+          log2(`  relaunch still outside target app (${recoveredBoundary.owner}); no target-app step recorded.`);
+          return {
+            resolved: recovered,
+            observation: `(left target app ${boundary.targetAppId} for ${boundary.owner}; relaunch still showed ${recoveredBoundary.owner}, so no target-app step was recorded)`,
+            externalBlocked: true,
+            externalOwner: boundary.owner
+          };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          return {
+            resolved: null,
+            observation: `(left target app ${boundary.targetAppId} for ${boundary.owner}; failed to relaunch target app: ${message})`,
+            externalBlocked: true,
+            externalOwner: boundary.owner
+          };
+        }
+      };
+      const absorbObservation = async (xml, driverSignal, windowSize, screenshot, source) => {
+        const resolved = buildResolved(xml, driverSignal, windowSize);
+        if (!resolved)
+          return { resolved: null, observation: null };
+        return absorbResolvedObservation(resolved, screenshot, source);
+      };
       const resolveRef = (ref) => {
         if (typeof ref !== "string" || !latest)
           return null;
@@ -8525,11 +9035,11 @@ Start by calling mobile_snapshot, then execute the steps. Finish with at least o
       };
       try {
         const seed = await driver.snapshot();
-        ingest(seed.xml, seed.screenSignal, seed.windowSize);
+        await absorbObservation(seed.xml, seed.screenSignal, seed.windowSize, seed.screenshot, "seed snapshot");
       } catch (err) {
         log2(`  seed snapshot failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
       }
-      const systemPrompt = buildSystemPrompt(platform3);
+      const systemPrompt = buildSystemPrompt(platform3, targetAppId);
       const kickoff = buildScenarioKickoff(scenario);
       const recentExchanges = [];
       let iteration = 0;
@@ -8640,7 +9150,7 @@ ${statePacket}` },
               driver,
               platform: platform3,
               latest: getLatest,
-              ingest,
+              absorbObservation,
               resolveRef,
               screenName: () => lastScreenName || "UnknownScreen",
               recordAction: (action) => {
@@ -8663,60 +9173,85 @@ ${statePacket}` },
       return { actions, assertCount, finish, lastSnapshot: getLatest(), lastScreenName };
     }
     async function dispatchGenerateTool(args) {
-      const { toolName, toolArgs, driver, platform: platform3, latest, ingest, resolveRef, screenName, recordAction, log: log2 } = args;
+      const { toolName, toolArgs, driver, platform: platform3, latest, absorbObservation, resolveRef, screenName, recordAction, log: log2 } = args;
       const unknownRef = (ref) => ({
         ok: false,
         error: `Unknown element ref "${String(ref)}". Call mobile_snapshot first; refs are only valid for the latest snapshot.`
       });
+      const actionPayload = (result, absorbed) => {
+        const blocked = Boolean(absorbed.externalBlocked || absorbed.transientExternal);
+        return {
+          ok: result.ok && !blocked,
+          ...result.error ? { error: result.error } : {},
+          ...blocked ? { error: "Action left the target app and was not recorded. Continue from the relaunched target app." } : {},
+          observation: absorbed.observation ?? void 0,
+          ...absorbed.externalBlocked ? { blockedExternalApp: true, externalApp: absorbed.externalOwner } : {},
+          ...absorbed.transientExternal ? { transientExternalApp: true, externalApp: absorbed.externalOwner } : {}
+        };
+      };
+      const shouldRecordAction = (result, absorbed) => result.ok && !absorbed.externalBlocked && !absorbed.transientExternal;
       switch (toolName) {
         case "mobile_snapshot": {
           const snap = await driver.snapshot();
-          const resolved = ingest(snap.xml, snap.screenSignal, snap.windowSize);
-          if (!resolved)
+          const absorbed = await absorbObservation(snap.xml, snap.screenSignal, snap.windowSize, snap.screenshot, "mobile_snapshot");
+          if (!absorbed.resolved)
             return { ok: false, error: "snapshot returned no UI tree" };
-          log2(`  snapshot: ${resolved.screen.elements.length} elements`);
-          return { observation: resolved.observation };
+          log2(`  snapshot: ${absorbed.resolved.screen.elements.length} elements`);
+          return {
+            observation: absorbed.observation,
+            ...absorbed.externalBlocked ? { blockedExternalApp: true, externalApp: absorbed.externalOwner } : {},
+            ...absorbed.transientExternal ? { transientExternalApp: true, externalApp: absorbed.externalOwner } : {}
+          };
         }
         case "mobile_tap": {
           const element = resolveRef(toolArgs.ref);
           if (!element)
             return unknownRef(toolArgs.ref);
+          const beforeScreenName = screenName();
           const result = await driver.tap(element.bounds);
-          recordAction({
-            type: "TAP",
-            selector: (0, mobile_source_parser_js_2.preferredLocator)(element),
-            metadata: metadataForElement(element, screenName(), platform3)
-          });
-          const resolved = ingest(result.source, void 0, latest()?.screen.windowSize ?? null);
-          return { ok: result.ok, ...result.error ? { error: result.error } : {}, observation: resolved?.observation };
+          const absorbed = await absorbObservation(result.source, result.screenSignal, latest()?.screen.windowSize ?? null, result.screenshot, "mobile_tap");
+          if (shouldRecordAction(result, absorbed)) {
+            recordAction({
+              type: "TAP",
+              selector: (0, mobile_source_parser_js_2.preferredLocator)(element),
+              metadata: metadataForElement(element, beforeScreenName, platform3)
+            });
+          }
+          return actionPayload(result, absorbed);
         }
         case "mobile_type": {
           const element = resolveRef(toolArgs.ref);
           if (!element)
             return unknownRef(toolArgs.ref);
           const value = typeof toolArgs.value === "string" ? toolArgs.value : String(toolArgs.value ?? "");
+          const beforeScreenName = screenName();
           const result = await driver.type(value, element.bounds);
-          recordAction({
-            type: "TYPE",
-            value,
-            selector: (0, mobile_source_parser_js_2.preferredLocator)(element),
-            metadata: metadataForElement(element, screenName(), platform3)
-          });
-          const resolved = ingest(result.source, void 0, latest()?.screen.windowSize ?? null);
-          return { ok: result.ok, ...result.error ? { error: result.error } : {}, observation: resolved?.observation };
+          const absorbed = await absorbObservation(result.source, result.screenSignal, latest()?.screen.windowSize ?? null, result.screenshot, "mobile_type");
+          if (shouldRecordAction(result, absorbed)) {
+            recordAction({
+              type: "TYPE",
+              value,
+              selector: (0, mobile_source_parser_js_2.preferredLocator)(element),
+              metadata: metadataForElement(element, beforeScreenName, platform3)
+            });
+          }
+          return actionPayload(result, absorbed);
         }
         case "mobile_clear": {
           const element = resolveRef(toolArgs.ref);
           if (!element)
             return unknownRef(toolArgs.ref);
+          const beforeScreenName = screenName();
           const result = await driver.clear(element.bounds);
-          recordAction({
-            type: "CLEAR",
-            selector: (0, mobile_source_parser_js_2.preferredLocator)(element),
-            metadata: metadataForElement(element, screenName(), platform3)
-          });
-          const resolved = ingest(result.source, void 0, latest()?.screen.windowSize ?? null);
-          return { ok: result.ok, ...result.error ? { error: result.error } : {}, observation: resolved?.observation };
+          const absorbed = await absorbObservation(result.source, result.screenSignal, latest()?.screen.windowSize ?? null, result.screenshot, "mobile_clear");
+          if (shouldRecordAction(result, absorbed)) {
+            recordAction({
+              type: "CLEAR",
+              selector: (0, mobile_source_parser_js_2.preferredLocator)(element),
+              metadata: metadataForElement(element, beforeScreenName, platform3)
+            });
+          }
+          return actionPayload(result, absorbed);
         }
         case "mobile_swipe": {
           const direction = toolArgs.direction;
@@ -8724,30 +9259,42 @@ ${statePacket}` },
             return { ok: false, error: "direction must be one of up|down|left|right" };
           }
           const distance = typeof toolArgs.distance === "number" ? toolArgs.distance : void 0;
+          const beforeScreenName = screenName();
           const result = await driver.swipe(direction, distance);
-          recordAction({
-            type: "SWIPE",
-            metadata: {
-              screenName: screenName(),
-              direction,
-              ...distance !== void 0 ? { distance } : {}
-            }
-          });
-          const resolved = ingest(result.source, void 0, latest()?.screen.windowSize ?? null);
-          return { ok: result.ok, ...result.error ? { error: result.error } : {}, observation: resolved?.observation };
+          const absorbed = await absorbObservation(result.source, result.screenSignal, latest()?.screen.windowSize ?? null, result.screenshot, "mobile_swipe");
+          if (shouldRecordAction(result, absorbed)) {
+            recordAction({
+              type: "SWIPE",
+              metadata: {
+                screenName: beforeScreenName,
+                direction,
+                ...distance !== void 0 ? { distance } : {}
+              }
+            });
+          }
+          return actionPayload(result, absorbed);
         }
         case "mobile_back": {
+          const beforeScreenName = screenName();
           const result = await driver.back();
-          recordAction({ type: "BACK", metadata: { screenName: screenName() } });
-          const resolved = ingest(result.source, void 0, latest()?.screen.windowSize ?? null);
-          return { ok: result.ok, ...result.error ? { error: result.error } : {}, observation: resolved?.observation };
+          const absorbed = await absorbObservation(result.source, result.screenSignal, latest()?.screen.windowSize ?? null, result.screenshot, "mobile_back");
+          if (shouldRecordAction(result, absorbed)) {
+            recordAction({ type: "BACK", metadata: { screenName: beforeScreenName } });
+          }
+          return actionPayload(result, absorbed);
         }
         case "mobile_relaunch": {
           await driver.relaunch();
           const snap = await driver.snapshot();
-          const resolved = ingest(snap.xml, snap.screenSignal, snap.windowSize);
+          const absorbed = await absorbObservation(snap.xml, snap.screenSignal, snap.windowSize, snap.screenshot, "mobile_relaunch");
           log2("  relaunched app for hermetic reset.");
-          return { ok: true, observation: resolved?.observation, note: "App relaunched (clean state). Not recorded as a step." };
+          return {
+            ok: true,
+            observation: absorbed.observation,
+            ...absorbed.externalBlocked ? { blockedExternalApp: true, externalApp: absorbed.externalOwner } : {},
+            ...absorbed.transientExternal ? { transientExternalApp: true, externalApp: absorbed.externalOwner } : {},
+            note: "App relaunched (clean state). Not recorded as a step."
+          };
         }
         case "mobile_assert_visible": {
           const recorded = recordAssertVisible(toolArgs, { resolveRef, screenName, platform: platform3, recordAction });
@@ -8885,7 +9432,7 @@ ${statePacket}` },
       return test;
     }
     async function runMobileGeneratePhase(args) {
-      const { scenarios, driver, ctx, config, onLog, onAICall, onTestGenerated } = args;
+      const { scenarios, driver, ctx, config, onLog, onAICall, onTestGenerated, onScreenshot } = args;
       const log2 = (line) => {
         try {
           onLog?.(line);
@@ -8899,6 +9446,7 @@ ${statePacket}` },
       const provider = (0, ai_provider_js_1.getProviderForModel)(agentModel);
       const aiClient = modelOverride ? (0, ai_provider_js_1.getMobileClientForModel)(modelOverride) : (0, ai_provider_js_1.getMobileAIClient)();
       const auditGroupId = `mobile-generate-${(0, crypto_1.randomUUID)().slice(0, 8)}`;
+      const targetAppId = ctx.target?.appId?.trim() || void 0;
       log2(`Mobile generator starting \u2014 platform: ${platform3}, provider: ${provider}, model: ${agentModel}, scenarios: ${scenarios.length}`);
       const tests = [];
       for (let i = 0; i < scenarios.length; i++) {
@@ -8917,6 +9465,8 @@ ${statePacket}` },
             aiClient,
             auditGroupId,
             onAICall,
+            onScreenshot,
+            targetAppId,
             log: log2
           });
           const test = assembleTest({ scenario, recording, ctx, platform: platform3, log: log2 });
@@ -8924,13 +9474,17 @@ ${statePacket}` },
             log2(`  scenario "${scenario.name}" produced no compilable test \u2014 skipped.`);
             continue;
           }
-          tests.push(test);
           log2(`  \u2713 generated "${test.name}" (verified: ${test.verified}, steps: ${test.steps?.length ?? 0})`);
           try {
-            onTestGenerated?.(test);
+            await onTestGenerated?.(test);
           } catch (cbErr) {
+            if (cbErr?.isPlanLimitReached) {
+              log2("  Plan limit reached \u2014 stopping further generation");
+              break;
+            }
             log2(`  onTestGenerated callback error: ${cbErr instanceof Error ? cbErr.message : String(cbErr)}`);
           }
+          tests.push(test);
         } catch (err) {
           log2(`  scenario "${scenario.name}" failed: ${err instanceof Error ? err.message : String(err)} \u2014 skipping.`);
           continue;
@@ -12611,6 +13165,17 @@ var require_snapshot_observation = __commonJS({
           for (const container of group.containers) {
             lines.push(`      - ${yamlScalar(container ?? "(none)")}`);
           }
+          const hasRowContext = group.rowContexts.some((rc) => !!rc);
+          if (hasRowContext) {
+            lines.push('    distinguish_by_row:  # same name in different rows \u2014 scope by this text, e.g. getByRole(role, { name }).filter({ has: getByText("<row>") })');
+            for (let i = 0; i < group.rowContexts.length; i++) {
+              const rowContext = group.rowContexts[i];
+              if (!rowContext)
+                continue;
+              const ref = group.refs[i];
+              lines.push(`      - ${yamlScalar(`${ref ? `[${ref}] ` : ""}${rowContext}`)}`);
+            }
+          }
         }
       }
       lines.push("interactive_elements:");
@@ -12642,6 +13207,29 @@ var require_snapshot_observation = __commonJS({
           if (topLocator) {
             lines.push(`    locator: ${yamlScalar((0, snapshot_parser_js_1.formatLocator)(topLocator))}`);
           }
+          const enr = rankedElement.element.enrichment;
+          if (enr?.rowContext) {
+            lines.push(`    row_context: ${yamlScalar(enr.rowContext)}`);
+          }
+          if (enr && (enr.occluded || enr.position && enr.position !== "in-view")) {
+            const vis = [];
+            if (enr.position && enr.position !== "in-view")
+              vis.push(`off-screen-${enr.position}`);
+            if (enr.occluded)
+              vis.push("occluded");
+            lines.push(`    visibility: [${vis.map((token) => yamlScalar(token)).join(", ")}]`);
+          }
+        }
+      }
+      const recoveredClickables = options.recoveredClickables ?? [];
+      if (recoveredClickables.length > 0) {
+        lines.push("non_semantic_clickables:");
+        lines.push('  # Clickable elements with NO accessibility role (e.g. <div onclick> / cursor:pointer) that the a11y snapshot drops. Some may be decorative \u2014 verify before relying on them, and prefer a scoped locator (e.g. page.getByRole("main").getByText("...")) over a bare getByText to avoid strict-mode ambiguity.');
+        for (const clickable of recoveredClickables.slice(0, 8)) {
+          lines.push(`  - text: ${yamlScalar(clickable.text)}`);
+          if (clickable.rowContext) {
+            lines.push(`    row_context: ${yamlScalar(clickable.rowContext)}`);
+          }
         }
       }
       lines.push("observation_cues:");
@@ -12815,6 +13403,9 @@ var require_snapshot_observation = __commonJS({
           score += 12;
         }
       }
+      const enr = element.enrichment;
+      if (enr?.rowContext)
+        score += 4;
       return score;
     }
     function buildStateSummary(element) {
@@ -12990,10 +13581,12 @@ var require_snapshot_observation = __commonJS({
         const key = `${role}\0${name}`;
         let group = groups.get(key);
         if (!group) {
-          group = { role, name, containers: [] };
+          group = { role, name, containers: [], rowContexts: [], refs: [] };
           groups.set(key, group);
         }
         group.containers.push(element.containerPath ?? null);
+        group.rowContexts.push(element.enrichment?.rowContext ?? null);
+        group.refs.push(element.ref ?? null);
       }
       return [...groups.values()].filter((group) => group.containers.length > 1);
     }
@@ -234647,6 +235240,154 @@ var require_preflight_syntax = __commonJS({
   }
 });
 
+// ../runner-core/dist/services/selector-registry-context.js
+var require_selector_registry_context = __commonJS({
+  "../runner-core/dist/services/selector-registry-context.js"(exports) {
+    "use strict";
+    Object.defineProperty(exports, "__esModule", { value: true });
+    exports.formatSelectorRegistryContextForPrompt = formatSelectorRegistryContextForPrompt;
+    function isRecord(value) {
+      return value !== null && typeof value === "object" && !Array.isArray(value);
+    }
+    function asString(value, fallback = "") {
+      return typeof value === "string" ? value : fallback;
+    }
+    function asNumber(value, fallback = 0) {
+      return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+    }
+    function asStringArray(value) {
+      return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+    }
+    function truncateForSelectorPrompt(value, maxLength = 180) {
+      const normalized = (value ?? "").replace(/\s+/g, " ").trim();
+      if (normalized.length <= maxLength)
+        return normalized;
+      return `${normalized.slice(0, Math.max(0, maxLength - 3))}...`;
+    }
+    function inlineCode(value, maxLength = 180) {
+      return `\`${truncateForSelectorPrompt(value, maxLength).replace(/`/g, "'")}\``;
+    }
+    function normalizeRef(value) {
+      if (!isRecord(value))
+        return null;
+      const expression = asString(value.expression).trim();
+      if (!expression)
+        return null;
+      return {
+        route: asString(value.route, "*"),
+        usage: asString(value.usage, "locator"),
+        source: asString(value.source, "generated"),
+        expression,
+        occurrenceIndex: asNumber(value.occurrenceIndex, 0)
+      };
+    }
+    function normalizeSibling(value) {
+      if (!isRecord(value))
+        return null;
+      const testCaseId = asString(value.testCaseId).trim();
+      const expression = asString(value.expression).trim();
+      if (!testCaseId || !expression)
+        return null;
+      return {
+        testCaseId,
+        name: asString(value.name, testCaseId),
+        suite: typeof value.suite === "string" ? value.suite : null,
+        lastPassedAt: typeof value.lastPassedAt === "string" ? value.lastPassedAt : null,
+        expression,
+        usage: asString(value.usage, "locator"),
+        route: asString(value.route, "*"),
+        source: asString(value.source, "generated")
+      };
+    }
+    function normalizeEntry(value) {
+      if (!isRecord(value))
+        return null;
+      const id = asString(value.id).trim();
+      const expression = asString(value.expression).trim();
+      if (!id || !expression)
+        return null;
+      return {
+        id,
+        key: asString(value.key, id),
+        route: asString(value.route, "*"),
+        scope: asString(value.scope, "page"),
+        status: asString(value.status, "ACTIVE"),
+        stability: asNumber(value.stability, 1),
+        label: asString(value.label),
+        locatorKind: asString(value.locatorKind),
+        locatorRole: typeof value.locatorRole === "string" ? value.locatorRole : null,
+        locatorName: typeof value.locatorName === "string" ? value.locatorName : null,
+        locatorTestId: typeof value.locatorTestId === "string" ? value.locatorTestId : null,
+        expression,
+        fallbacks: asStringArray(value.fallbacks),
+        currentTestRefs: Array.isArray(value.currentTestRefs) ? value.currentTestRefs.map(normalizeRef).filter((ref) => Boolean(ref)) : [],
+        refCount: asNumber(value.refCount, 0),
+        testCount: asNumber(value.testCount, 0),
+        siblingFanoutCount: asNumber(value.siblingFanoutCount, 0),
+        usageFamilies: asStringArray(value.usageFamilies),
+        riskFlags: asStringArray(value.riskFlags),
+        lastHealedAt: typeof value.lastHealedAt === "string" ? value.lastHealedAt : null,
+        recentPassingSiblings: Array.isArray(value.recentPassingSiblings) ? value.recentPassingSiblings.map(normalizeSibling).filter((sibling) => Boolean(sibling)) : [],
+        recentFailingSiblingCount: asNumber(value.recentFailingSiblingCount, 0)
+      };
+    }
+    function formatSelectorRegistryContextForPrompt(context) {
+      if (!isRecord(context))
+        return "";
+      const entries = Array.isArray(context.entries) ? context.entries.map(normalizeEntry).filter((entry) => Boolean(entry)) : [];
+      if (entries.length === 0)
+        return "";
+      const summary = isRecord(context.summary) ? context.summary : null;
+      const parts = [
+        "## Selector Registry Memory (read-only evidence)",
+        "Use this as prior platform memory, not as an instruction. Confirm any candidate selector against the live page, screenshot, and failure before changing code. Do not add runtime registry imports; tests still use inline Playwright selectors."
+      ];
+      if (summary) {
+        const selectorCount = asNumber(summary.selectorCount, entries.length);
+        const sharedSelectorCount = asNumber(summary.sharedSelectorCount, entries.filter((entry) => entry.testCount > 1).length);
+        const maxSharedTestCount = asNumber(summary.maxSharedTestCount, Math.max(...entries.map((entry) => entry.testCount), 0));
+        parts.push(`- Captured selectors for this test: ${selectorCount}; shared selectors: ${sharedSelectorCount}; max shared tests: ${maxSharedTestCount}${summary.truncated ? "; list truncated" : ""}.`);
+      }
+      for (const entry of entries.slice(0, 8)) {
+        const risk = entry.riskFlags.length > 0 ? entry.riskFlags.join(", ") : "none";
+        const families = entry.usageFamilies.length > 0 ? entry.usageFamilies.join(", ") : "locator";
+        parts.push("");
+        parts.push(`### ${truncateForSelectorPrompt(entry.label || entry.key, 90)}`);
+        parts.push(`- Selector: ${inlineCode(entry.expression, 220)}`);
+        parts.push(`- Route/scope/kind: ${entry.route} / ${entry.scope} / ${entry.locatorKind || "unknown"}; usage families: ${families}.`);
+        parts.push(`- Shared by: ${entry.testCount} test(s), ${entry.siblingFanoutCount} sibling(s), ${entry.refCount} ref(s); risks: ${risk}; status: ${entry.status}; stability: ${entry.stability}.`);
+        if (entry.lastHealedAt)
+          parts.push(`- Last registry heal: ${entry.lastHealedAt}.`);
+        const currentRefs = entry.currentTestRefs.slice(0, 3);
+        if (currentRefs.length > 0) {
+          parts.push("- Current test occurrences:");
+          for (const ref of currentRefs) {
+            parts.push(`  - ${ref.usage} on ${ref.route} from ${ref.source}: ${inlineCode(ref.expression, 180)}`);
+          }
+        }
+        const siblings = entry.recentPassingSiblings.slice(0, 3);
+        if (siblings.length > 0) {
+          parts.push("- Recent passing sibling tests using this registry entry:");
+          for (const sibling of siblings) {
+            const suite = sibling.suite ? ` (${truncateForSelectorPrompt(sibling.suite, 50)})` : "";
+            const passed = sibling.lastPassedAt ? ` passed ${sibling.lastPassedAt}` : "";
+            parts.push(`  - ${truncateForSelectorPrompt(sibling.name, 80)}${suite}${passed}: ${inlineCode(sibling.expression, 180)}`);
+          }
+        }
+        if (entry.recentFailingSiblingCount && entry.recentFailingSiblingCount > 0) {
+          parts.push(`- Other recent failing siblings on this entry: ${entry.recentFailingSiblingCount}.`);
+        }
+        const fallbacks = (entry.fallbacks ?? []).slice(0, 3);
+        if (fallbacks.length > 0) {
+          parts.push(`- Registry fallbacks: ${fallbacks.map((fallback) => inlineCode(fallback, 120)).join(", ")}.`);
+        }
+      }
+      return `${parts.join("\n")}
+`;
+    }
+  }
+});
+
 // ../runner-core/dist/services/mcp-healer.js
 var require_mcp_healer = __commonJS({
   "../runner-core/dist/services/mcp-healer.js"(exports) {
@@ -234741,6 +235482,7 @@ var require_mcp_healer = __commonJS({
     var snapshot_context_compactor_js_1 = require_snapshot_context_compactor();
     var rate_limit_detector_js_1 = require_rate_limit_detector();
     var preflight_syntax_js_1 = require_preflight_syntax();
+    var selector_registry_context_js_1 = require_selector_registry_context();
     function stripCodeFences(code) {
       let cleaned = code.replace(/<think>[\s\S]*?<\/think>/gi, "").trim();
       cleaned = cleaned.replace(/^\s*```(?:typescript|ts|javascript|js)?\s*\n?/, "").replace(/\n?\s*```\s*$/, "");
@@ -235302,7 +236044,7 @@ ${lines.join("\n")}
       }).join("\n");
     }
     async function executeScriptDrivenHeal(playwrightCode, baseUrl, options) {
-      const { testName, testVariables, surfaceIntelligence, healingContext, lastFailureError, failureScreenshot, lastHealAttempt, consecutiveFails, modelOverride, onAICall, stepResults, tags } = options;
+      const { testName, testVariables, surfaceIntelligence, healingContext, selectorRegistryContext, lastFailureError, failureScreenshot, lastHealAttempt, consecutiveFails, modelOverride, onAICall, stepResults, tags } = options;
       const landingViolation = (tags ?? []).includes("@landing-violation");
       const agentModel = modelOverride ? (0, ai_provider_js_1.resolveModelForTask)(modelOverride, "strong") : (0, ai_provider_js_1.getModel)("strong");
       const provider = modelOverride ? (0, ai_provider_js_1.getProviderForModel)(modelOverride) : (0, ai_provider_js_1.getAIProvider)();
@@ -235365,6 +236107,11 @@ ${lastHealAttempt.healReason.slice(0, 800)}`);
           if (healingContext) {
             parts.push(`
 ${formatHealingContextForPrompt(healingContext)}`);
+          }
+          const selectorRegistryPrompt = (0, selector_registry_context_js_1.formatSelectorRegistryContextForPrompt)(selectorRegistryContext);
+          if (selectorRegistryPrompt) {
+            parts.push(`
+${selectorRegistryPrompt}`);
           }
           if (surfaceIntelligence) {
             parts.push(`
@@ -235972,6 +236719,7 @@ ${(verifyResult.logs ?? "").slice(0, 2e3)}`;
         testVariables: options?.testVariables,
         surfaceIntelligence: options?.surfaceIntelligence,
         healingContext: options?.healingContext,
+        selectorRegistryContext: options?.selectorRegistryContext,
         lastFailureError: options?.lastFailureError,
         failureScreenshot: options?.failureScreenshot,
         lastHealAttempt: options?.lastHealAttempt,
@@ -236512,6 +237260,7 @@ ${publicLines}` : ""}${credBlock}
 `;
             })()}
 ${options?.healingContext ? `${formatHealingContextForPrompt(options.healingContext)}` : ""}
+${(0, selector_registry_context_js_1.formatSelectorRegistryContextForPrompt)(options?.selectorRegistryContext)}
 ${surfaceIntelligence ? `## Original Recorded Actions (what the test was trying to do)
 ${surfaceIntelligence.slice(0, 1500)}
 ` : ""}${landingViolation ? `## STRUCTURAL REQUIREMENT
@@ -238558,6 +239307,7 @@ var require_grok_per_test_healer = __commonJS({
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
     exports.executeGrokPerTestHeal = executeGrokPerTestHeal2;
+    exports.buildHealBrief = buildHealBrief;
     var node_child_process_1 = __require("child_process");
     var promises_1 = __require("fs/promises");
     var node_os_1 = __require("os");
@@ -238574,6 +239324,7 @@ var require_grok_per_test_healer = __commonJS({
     var playwright_mcp_config_js_1 = require_playwright_mcp_config();
     var heal_session_tailer_js_1 = require_heal_session_tailer();
     var proven_actions_adapter_js_1 = require_proven_actions_adapter();
+    var selector_registry_context_js_1 = require_selector_registry_context();
     var HEAL_MCP_CAPABILITIES = ["core", "core-navigation", "core-input", "core-tabs", "testing"];
     var grok_cli_js_1 = require_grok_cli();
     var DEFAULT_MAX_ATTEMPTS = 3;
@@ -238679,6 +239430,7 @@ var require_grok_per_test_healer = __commonJS({
             lastDiagnosis,
             publicVars: publics,
             secretKeys: Object.keys(secrets),
+            selectorRegistryContext: options.selectorRegistryContext ?? null,
             attempt,
             maxAttempts
           }), "utf8");
@@ -238906,6 +239658,7 @@ ${input.lastDiagnosis ? `
 ## Your prior diagnosis (do not repeat the same fix)
 ${input.lastDiagnosis}
 ` : ""}
+${(0, selector_registry_context_js_1.formatSelectorRegistryContextForPrompt)(input.selectorRegistryContext)}
 
 ## Tools available
 - **bash** \u2014 \`curl\`, \`sed\`, \`grep\` for static inspection of the app under test.
@@ -299620,6 +300373,699 @@ var require_capture_page_normalizer = __commonJS({
   }
 });
 
+// ../runner-core/dist/services/perception-enricher.js
+var require_perception_enricher = __commonJS({
+  "../runner-core/dist/services/perception-enricher.js"(exports) {
+    "use strict";
+    Object.defineProperty(exports, "__esModule", { value: true });
+    exports.enrichCapturedPage = enrichCapturedPage;
+    exports.mergePerceptionOntoElements = mergePerceptionOntoElements;
+    exports.elementRoleClass = elementRoleClass;
+    exports.normalizeName = normalizeName;
+    exports.urlMatchesRoute = urlMatchesRoute;
+    var DEFAULT_CONFIG = {
+      maxCandidates: 220,
+      maxScan: 4e3,
+      recoverNonSemantic: false,
+      budgetMs: 1500
+    };
+    var BLACKOUT_THRESHOLD = 8;
+    var EVALUATE_TIMEOUT_MS = 1800;
+    var MAX_RECOVERED = 12;
+    async function enrichCapturedPage(page, input, opts = {}) {
+      const empty = { recovered: [], enriched: 0, perceived: 0 };
+      if (!page)
+        return { ...empty, skipReason: "no-page" };
+      try {
+        const url = page.url();
+        if (url && input.route && !urlMatchesRoute(url, input.route)) {
+          opts.onLog?.(`[perception] skip: page ${shortUrl(url)} != captured route ${input.route}`);
+          return { ...empty, skipReason: "route-mismatch" };
+        }
+      } catch {
+      }
+      const elements = input.elements ?? [];
+      const parsedInteractive = input.parsedInteractiveCount ?? elements.length;
+      const cfg = {
+        ...DEFAULT_CONFIG,
+        recoverNonSemantic: parsedInteractive < BLACKOUT_THRESHOLD
+      };
+      let perceived;
+      try {
+        const raw = await withTimeout(page.evaluate(collectPerception, cfg), opts.timeoutMs ?? EVALUATE_TIMEOUT_MS);
+        if (!Array.isArray(raw))
+          return { ...empty, skipReason: "bad-result" };
+        perceived = raw;
+      } catch (err) {
+        opts.onLog?.(`[perception] evaluate failed \u2014 ${err instanceof Error ? err.message : String(err)}`);
+        return { ...empty, skipReason: "evaluate-error" };
+      }
+      const { enriched } = mergePerceptionOntoElements(elements, perceived);
+      const recovered = collectRecovered(perceived);
+      opts.onLog?.(`[perception] enriched ${enriched}/${elements.length} elements, ${recovered.length} non-semantic clickables (${perceived.length} perceived)`);
+      return { recovered, enriched, perceived: perceived.length };
+    }
+    function mergePerceptionOntoElements(elements, perceived) {
+      const perceivedGroups = /* @__PURE__ */ new Map();
+      for (const p of perceived) {
+        if (p.nonSemantic || !p.roleClass || !p.name)
+          continue;
+        const key = `${p.roleClass}\0${p.name}`;
+        let arr = perceivedGroups.get(key);
+        if (!arr) {
+          arr = [];
+          perceivedGroups.set(key, arr);
+        }
+        arr.push(p);
+      }
+      for (const arr of perceivedGroups.values())
+        arr.sort((a, b) => a.domOrder - b.domOrder);
+      const elementGroups = /* @__PURE__ */ new Map();
+      for (const el of elements) {
+        const roleClass = elementRoleClass(el);
+        const name = normalizeName(el.label);
+        if (!roleClass || !name)
+          continue;
+        const key = `${roleClass}\0${name}`;
+        let arr = elementGroups.get(key);
+        if (!arr) {
+          arr = [];
+          elementGroups.set(key, arr);
+        }
+        arr.push(el);
+      }
+      let enriched = 0;
+      for (const [key, els] of elementGroups) {
+        const ps = perceivedGroups.get(key);
+        if (!ps)
+          continue;
+        if (ps.length !== els.length)
+          continue;
+        for (let i = 0; i < els.length; i++) {
+          const enrichment = toEnrichment(ps[i]);
+          if (enrichment) {
+            els[i].enrichment = enrichment;
+            enriched++;
+          }
+        }
+      }
+      return { enriched };
+    }
+    function toEnrichment(p) {
+      const e = {};
+      if (p.rowContext)
+        e.rowContext = p.rowContext;
+      if (p.position && p.position !== "in-view")
+        e.position = p.position;
+      if (p.occluded)
+        e.occluded = true;
+      if (p.cursorPointer)
+        e.cursorPointer = true;
+      return Object.keys(e).length > 0 ? e : null;
+    }
+    function collectRecovered(perceived) {
+      const out = [];
+      const seen = /* @__PURE__ */ new Set();
+      for (const p of perceived) {
+        if (!p.nonSemantic || !p.text)
+          continue;
+        const key = `${p.text}\0${p.rowContext ?? ""}`;
+        if (seen.has(key))
+          continue;
+        seen.add(key);
+        const rc = { text: p.text };
+        if (p.rowContext)
+          rc.rowContext = p.rowContext;
+        out.push(rc);
+        if (out.length >= MAX_RECOVERED)
+          break;
+      }
+      return out;
+    }
+    function elementRoleClass(el) {
+      const r = (el.role ?? "").toLowerCase().trim();
+      const mapped = roleBucket(r);
+      if (mapped)
+        return mapped;
+      const t = (el.elementType ?? "").toLowerCase();
+      if (t === "link")
+        return "link";
+      if (t === "button")
+        return "button";
+      if (t.startsWith("input")) {
+        const it = (el.inputType ?? "").toLowerCase();
+        if (it === "checkbox")
+          return "checkbox";
+        if (it === "radio")
+          return "radio";
+        if (it === "submit" || it === "button")
+          return "button";
+        return "textbox";
+      }
+      return t || "";
+    }
+    function roleBucket(r) {
+      if (!r)
+        return null;
+      if (r === "link")
+        return "link";
+      if (r === "button")
+        return "button";
+      if (r === "textbox" || r === "searchbox" || r === "spinbutton")
+        return "textbox";
+      if (r === "combobox" || r === "listbox")
+        return "combobox";
+      if (r === "checkbox" || r === "switch")
+        return "checkbox";
+      if (r === "radio")
+        return "radio";
+      if (r === "tab")
+        return "tab";
+      if (r === "menuitem" || r === "menuitemcheckbox" || r === "menuitemradio")
+        return "menuitem";
+      if (r === "option")
+        return "option";
+      if (r === "slider")
+        return "slider";
+      return r;
+    }
+    function normalizeName(name) {
+      return (name ?? "").replace(/\s+/g, " ").trim().toLowerCase().slice(0, 80);
+    }
+    function withTimeout(p, ms) {
+      return new Promise((resolve, reject) => {
+        const t = setTimeout(() => reject(new Error(`timeout after ${ms}ms`)), ms);
+        p.then((v) => {
+          clearTimeout(t);
+          resolve(v);
+        }, (e) => {
+          clearTimeout(t);
+          reject(e);
+        });
+      });
+    }
+    function parseLoc(input) {
+      try {
+        const u = new URL(input, "http://__rel__");
+        return {
+          origin: u.host === "__rel__" ? "" : u.host,
+          // '' when input was path-relative
+          path: (u.pathname || "/").replace(/\/+$/, "") || "/",
+          search: u.search,
+          hash: u.hash
+        };
+      } catch {
+        const hashI = input.indexOf("#");
+        const hash = hashI >= 0 ? input.slice(hashI) : "";
+        const beforeHash = hashI >= 0 ? input.slice(0, hashI) : input;
+        const qi = beforeHash.indexOf("?");
+        const search = qi >= 0 ? beforeHash.slice(qi) : "";
+        const path = ((qi >= 0 ? beforeHash.slice(0, qi) : beforeHash) || "/").replace(/\/+$/, "") || "/";
+        return { origin: "", path, search, hash };
+      }
+    }
+    function urlMatchesRoute(url, route2) {
+      const u = parseLoc(url);
+      const r = parseLoc(route2);
+      if (u.path !== r.path)
+        return false;
+      if (r.origin && u.origin && r.origin !== u.origin)
+        return false;
+      if (r.search && u.search !== r.search)
+        return false;
+      if (r.hash && u.hash !== r.hash)
+        return false;
+      return true;
+    }
+    function shortUrl(url) {
+      return url.length > 80 ? `${url.slice(0, 77)}...` : url;
+    }
+    function collectPerception(cfg) {
+      const NATIVE = {
+        A: true,
+        BUTTON: true,
+        INPUT: true,
+        SELECT: true,
+        TEXTAREA: true,
+        SUMMARY: true,
+        OPTION: true
+      };
+      const INTERACTIVE_ROLE = {
+        button: true,
+        link: true,
+        textbox: true,
+        searchbox: true,
+        spinbutton: true,
+        combobox: true,
+        listbox: true,
+        checkbox: true,
+        radio: true,
+        switch: true,
+        menuitem: true,
+        menuitemcheckbox: true,
+        menuitemradio: true,
+        tab: true,
+        option: true,
+        slider: true
+      };
+      const norm = (s) => (s || "").replace(/\s+/g, " ").trim();
+      const lower = (s) => s.toLowerCase().slice(0, 80);
+      const roleClassOf = (tag, roleAttr, inputType) => {
+        const r = roleAttr.toLowerCase();
+        if (r) {
+          if (r === "link")
+            return "link";
+          if (r === "button")
+            return "button";
+          if (r === "textbox" || r === "searchbox" || r === "spinbutton")
+            return "textbox";
+          if (r === "combobox" || r === "listbox")
+            return "combobox";
+          if (r === "switch" || r === "checkbox")
+            return "checkbox";
+          if (r === "radio")
+            return "radio";
+          if (r === "tab")
+            return "tab";
+          if (r === "menuitem" || r === "menuitemcheckbox" || r === "menuitemradio")
+            return "menuitem";
+          if (r === "option")
+            return "option";
+          if (r === "slider")
+            return "slider";
+          return r;
+        }
+        if (tag === "A")
+          return "link";
+        if (tag === "BUTTON" || tag === "SUMMARY")
+          return "button";
+        if (tag === "SELECT")
+          return "combobox";
+        if (tag === "TEXTAREA")
+          return "textbox";
+        if (tag === "OPTION")
+          return "option";
+        if (tag === "INPUT") {
+          const t = (inputType || "text").toLowerCase();
+          if (t === "checkbox")
+            return "checkbox";
+          if (t === "radio")
+            return "radio";
+          if (t === "submit" || t === "button" || t === "image" || t === "reset")
+            return "button";
+          if (t === "range")
+            return "slider";
+          return "textbox";
+        }
+        return "other";
+      };
+      const accName = (el) => {
+        const al = norm(el.getAttribute("aria-label"));
+        if (al)
+          return al;
+        const lb = el.getAttribute("aria-labelledby");
+        if (lb) {
+          const ids = lb.split(/\s+/);
+          let txt = "";
+          for (let i = 0; i < ids.length; i++) {
+            const t = el.ownerDocument.getElementById(ids[i]);
+            if (t)
+              txt += (txt ? " " : "") + norm(t.textContent);
+          }
+          if (txt)
+            return txt;
+        }
+        if (el.tagName === "INPUT" || el.tagName === "TEXTAREA" || el.tagName === "SELECT") {
+          const id = el.getAttribute("id");
+          if (id) {
+            try {
+              const lab = el.ownerDocument.querySelector('label[for="' + (window.CSS && CSS.escape ? CSS.escape(id) : id) + '"]');
+              const t = lab ? norm(lab.textContent) : "";
+              if (t)
+                return t;
+            } catch {
+            }
+          }
+          const val = norm(el.value);
+          if (val)
+            return val;
+          const ph = norm(el.getAttribute("placeholder"));
+          if (ph)
+            return ph;
+          return norm(el.getAttribute("name"));
+        }
+        const text = norm(el.textContent);
+        if (text)
+          return text;
+        return norm(el.getAttribute("title")) || norm(el.getAttribute("alt"));
+      };
+      const ROW_SEL = 'tr,li,[role="row"],[role="listitem"],[role="article"],article,[role="option"]';
+      const isCardish = (el) => {
+        const cls = (el.getAttribute("class") || "").toLowerCase();
+        return /(^|[\s_-])(card|row|item|listitem|cell|tile)([\s_-]|$)/.test(cls);
+      };
+      const rowContextOf = (el, ownNameLower) => {
+        let cur = el.parentElement;
+        let depth = 0;
+        while (cur && depth < 8) {
+          let isRow = false;
+          try {
+            isRow = cur.matches(ROW_SEL);
+          } catch {
+            isRow = false;
+          }
+          if (isRow || isCardish(cur)) {
+            const head = cur.querySelector('h1,h2,h3,h4,h5,h6,[role="heading"],strong,b,th,td');
+            let txt = head ? norm(head.textContent) : "";
+            if (!txt)
+              txt = norm(cur.textContent);
+            txt = txt.slice(0, 80);
+            const low = txt.toLowerCase();
+            if (txt && low !== ownNameLower && low.length > 1)
+              return txt;
+            return null;
+          }
+          cur = cur.parentElement;
+          depth++;
+        }
+        return null;
+      };
+      const vh = window.innerHeight || 0;
+      const vw = window.innerWidth || 0;
+      const visibleRect = (el) => {
+        let rect;
+        let style;
+        try {
+          rect = el.getBoundingClientRect();
+          style = window.getComputedStyle(el);
+        } catch {
+          return null;
+        }
+        if (style.display === "none" || style.visibility === "hidden")
+          return null;
+        if (parseFloat(style.opacity || "1") === 0)
+          return null;
+        if (rect.width <= 0 || rect.height <= 0)
+          return null;
+        try {
+          if (el.closest('[aria-hidden="true"],[inert]'))
+            return null;
+        } catch {
+        }
+        return { rect, style };
+      };
+      const occlusionOf = (el, rect) => {
+        const cx = rect.left + rect.width / 2;
+        const cy = rect.top + rect.height / 2;
+        if (cx < 0 || cy < 0 || cx > vw || cy > vh)
+          return false;
+        try {
+          const hit = document.elementFromPoint(cx, cy);
+          if (!hit || hit === el || el.contains(hit) || hit.contains(el))
+            return false;
+          let anc = hit;
+          let guard = 0;
+          while (anc && guard < 12) {
+            const pos = window.getComputedStyle(anc).position;
+            if (pos === "fixed" || pos === "sticky")
+              return false;
+            anc = anc.parentElement;
+            guard++;
+          }
+          return true;
+        } catch {
+          return false;
+        }
+      };
+      const positionOf = (rect) => rect.bottom < 0 ? "above" : rect.top > vh ? "below" : "in-view";
+      const t0 = typeof performance !== "undefined" && performance.now ? performance.now() : 0;
+      const overBudget = () => t0 > 0 && performance.now() - t0 > cfg.budgetMs;
+      const out = [];
+      let order = 0;
+      const SEL = 'a[href],button,input:not([type="hidden"]),textarea,select,summary,option,[role],[onclick],[tabindex]';
+      const all = document.querySelectorAll(SEL);
+      const limit = all.length < cfg.maxScan ? all.length : cfg.maxScan;
+      for (let i = 0; i < limit; i++) {
+        if (out.length >= cfg.maxCandidates)
+          break;
+        if ((i & 63) === 0 && overBudget())
+          break;
+        const el = all[i];
+        const vis = visibleRect(el);
+        if (!vis)
+          continue;
+        const tag = el.tagName;
+        const roleAttr = el.getAttribute("role") || "";
+        const inputType = tag === "INPUT" ? el.type || "" : "";
+        const cursorPointer = vis.style.cursor === "pointer";
+        const native = NATIVE[tag] === true;
+        const roleLower = roleAttr.toLowerCase();
+        const hasInteractiveRole = !!roleLower && INTERACTIVE_ROLE[roleLower] === true;
+        const hasOnclick = el.hasAttribute("onclick");
+        const tabAttr = el.getAttribute("tabindex");
+        const tabbable = tabAttr != null && tabAttr !== "-1";
+        const semantic = native || hasInteractiveRole;
+        const nonSemantic = !semantic && (cursorPointer || hasOnclick || tabbable);
+        if (!semantic && !nonSemantic)
+          continue;
+        const myOrder = order++;
+        const name = accName(el);
+        const lname = lower(name);
+        const rect = vis.rect;
+        out.push({
+          domOrder: myOrder,
+          roleClass: roleClassOf(tag, roleAttr, inputType),
+          name: lname,
+          rowContext: rowContextOf(el, lname),
+          position: positionOf(rect),
+          occluded: occlusionOf(el, rect),
+          cursorPointer,
+          nonSemantic,
+          text: nonSemantic ? name.slice(0, 80) || null : null
+        });
+      }
+      if (cfg.recoverNonSemantic) {
+        const extra = document.querySelectorAll("div,span,li,td,p");
+        const extraLimit = extra.length < cfg.maxScan ? extra.length : cfg.maxScan;
+        for (let i = 0; i < extraLimit; i++) {
+          if (out.length >= cfg.maxCandidates)
+            break;
+          if ((i & 63) === 0 && overBudget())
+            break;
+          const el = extra[i];
+          const vis = visibleRect(el);
+          if (!vis)
+            continue;
+          if (vis.style.cursor !== "pointer")
+            continue;
+          if (el.querySelector('a,button,input,select,textarea,[role="button"],[role="link"]'))
+            continue;
+          const rect = vis.rect;
+          if (rect.width < 6 || rect.height < 6)
+            continue;
+          if (rect.width > vw * 0.98)
+            continue;
+          if (positionOf(rect) !== "in-view")
+            continue;
+          if (occlusionOf(el, rect))
+            continue;
+          const name = accName(el);
+          if (!name)
+            continue;
+          const lname = lower(name);
+          out.push({
+            domOrder: order++,
+            roleClass: "button",
+            name: lname,
+            rowContext: rowContextOf(el, lname),
+            position: "in-view",
+            occluded: false,
+            cursorPointer: true,
+            nonSemantic: true,
+            text: name.slice(0, 80) || null
+          });
+        }
+      }
+      return out;
+    }
+  }
+});
+
+// ../runner-core/dist/services/stuck-detector.js
+var require_stuck_detector = __commonJS({
+  "../runner-core/dist/services/stuck-detector.js"(exports) {
+    "use strict";
+    Object.defineProperty(exports, "__esModule", { value: true });
+    exports.StuckDetector = void 0;
+    exports.isPageAffectingTool = isPageAffectingTool;
+    exports.normalizeStuckSignature = normalizeStuckSignature;
+    var PAGE_AFFECTING_TOOLS = /* @__PURE__ */ new Set([
+      "browser_click",
+      "browser_type",
+      "browser_fill_form",
+      "browser_select_option",
+      "browser_navigate",
+      "browser_press_key",
+      "browser_hover",
+      "browser_drag"
+    ]);
+    function isPageAffectingTool(toolName) {
+      return PAGE_AFFECTING_TOOLS.has(toolName);
+    }
+    function normalizeStuckSignature(toolName, toolArgs) {
+      const rawRef = typeof toolArgs.ref === "string" ? toolArgs.ref.trim() : "";
+      const rawElement = typeof toolArgs.element === "string" ? toolArgs.element.trim() : "";
+      const elementKey = rawRef ? rawRef : rawElement ? rawElement.toLowerCase().replace(/\S+@\S+/g, "[email]").slice(0, 60) : "";
+      switch (toolName) {
+        case "browser_click":
+        case "browser_hover":
+        case "browser_select_option":
+        case "browser_type":
+        case "browser_fill_form":
+        case "browser_drag":
+          return elementKey ? `${toolName}:${elementKey}` : null;
+        case "browser_navigate": {
+          const url = typeof toolArgs.url === "string" ? canonicalizeUrlPath(toolArgs.url) : "";
+          return `browser_navigate:${url}`;
+        }
+        case "browser_press_key": {
+          const key = typeof toolArgs.key === "string" ? toolArgs.key : "";
+          return `browser_press_key:${key}`;
+        }
+        default:
+          return null;
+      }
+    }
+    function canonicalizeUrlPath(url) {
+      try {
+        const u = new URL(url, "http://x");
+        return u.pathname.replace(/\/+$/, "") || "/";
+      } catch {
+        return url.trim().split(/[?#]/)[0] || url.trim();
+      }
+    }
+    var NO_VERDICT = Object.freeze({
+      tier: 0,
+      kind: null,
+      repeatedAction: null,
+      recover: false,
+      yieldRun: false
+    });
+    var DEFAULTS = {
+      window: 8,
+      repeatThreshold: 3,
+      stagnationThreshold: 4,
+      tier2After: 3,
+      tier3After: 5,
+      maxRecoveries: 2,
+      repetitionReachesRecovery: true
+    };
+    var StuckDetector = class {
+      opts;
+      records = [];
+      stallStreak = 0;
+      recoveryCount = 0;
+      lastEmittedTier = 0;
+      constructor(options = {}) {
+        this.opts = { ...DEFAULTS, ...options };
+      }
+      record(input) {
+        this.records.push(input);
+        if (this.records.length > this.opts.window) {
+          this.records.splice(0, this.records.length - this.opts.window);
+        }
+        const stall = this.detectStall();
+        if (!stall.stalled) {
+          this.stallStreak = 0;
+          this.lastEmittedTier = 0;
+          return NO_VERDICT;
+        }
+        this.stallStreak += 1;
+        let desired = 1;
+        if (this.stallStreak >= this.opts.tier3After)
+          desired = 3;
+        else if (this.stallStreak >= this.opts.tier2After)
+          desired = 2;
+        if (stall.kind === "stagnation" && desired > 2)
+          desired = 2;
+        if (!this.opts.repetitionReachesRecovery && stall.kind === "repetition" && desired > 2)
+          desired = 2;
+        if (desired <= this.lastEmittedTier)
+          return NO_VERDICT;
+        if (desired === 3) {
+          if (this.recoveryCount >= this.opts.maxRecoveries) {
+            this.lastEmittedTier = 4;
+            return {
+              tier: 4,
+              kind: stall.kind,
+              repeatedAction: stall.repeatedAction,
+              recover: false,
+              yieldRun: true
+            };
+          }
+          this.recoveryCount += 1;
+          this.records = [];
+          this.stallStreak = 0;
+          this.lastEmittedTier = 0;
+          return {
+            tier: 3,
+            kind: stall.kind,
+            repeatedAction: stall.repeatedAction,
+            recover: true,
+            yieldRun: false
+          };
+        }
+        this.lastEmittedTier = desired;
+        return {
+          tier: desired,
+          kind: stall.kind,
+          repeatedAction: stall.repeatedAction,
+          recover: false,
+          yieldRun: false
+        };
+      }
+      detectStall() {
+        const { stagnationThreshold, repeatThreshold } = this.opts;
+        if (this.records.length < stagnationThreshold) {
+          return { stalled: false, kind: null, repeatedAction: null };
+        }
+        const recent = this.records.slice(-stagnationThreshold);
+        const progressStalled = recent.length >= stagnationThreshold && recent.every((r) => r.progressKey === recent[recent.length - 1].progressKey);
+        if (progressStalled) {
+          const counts = /* @__PURE__ */ new Map();
+          for (const rec of this.records) {
+            for (const sig of rec.actionSignatures) {
+              counts.set(sig, (counts.get(sig) ?? 0) + 1);
+            }
+          }
+          let repeatedAction = null;
+          let max = 0;
+          for (const [sig, count] of counts) {
+            if (count > max) {
+              max = count;
+              repeatedAction = sig;
+            }
+          }
+          if (repeatedAction && max >= repeatThreshold) {
+            return { stalled: true, kind: "repetition", repeatedAction };
+          }
+        }
+        if (progressStalled) {
+          const sameRoute = recent.every((r) => r.route === recent[recent.length - 1].route);
+          const pageAffectingCount = recent.filter((r) => r.pageAffecting).length;
+          const distinctSignatures = new Set(recent.flatMap((r) => r.actionSignatures));
+          const lowDiversity = distinctSignatures.size >= 1 && distinctSignatures.size <= Math.max(1, Math.floor(pageAffectingCount / 2));
+          if (sameRoute && pageAffectingCount >= Math.ceil(stagnationThreshold / 2) && lowDiversity) {
+            return { stalled: true, kind: "stagnation", repeatedAction: null };
+          }
+        }
+        return { stalled: false, kind: null, repeatedAction: null };
+      }
+    };
+    exports.StuckDetector = StuckDetector;
+  }
+});
+
 // ../runner-core/dist/services/evidence-harvester.js
 var require_evidence_harvester = __commonJS({
   "../runner-core/dist/services/evidence-harvester.js"(exports) {
@@ -299916,8 +301362,10 @@ var require_discover_explorer = __commonJS({
     var capture_page_normalizer_js_1 = require_capture_page_normalizer();
     var snapshot_observation_js_1 = require_snapshot_observation();
     var snapshot_context_compactor_js_1 = require_snapshot_context_compactor();
+    var perception_enricher_js_1 = require_perception_enricher();
     var exploration_prompt_builder_js_2 = require_exploration_prompt_builder();
     var exploration_state_js_1 = require_exploration_state();
+    var stuck_detector_js_1 = require_stuck_detector();
     var evidence_harvester_js_1 = require_evidence_harvester();
     var exploration_parser_js_1 = require_exploration_parser();
     var snapshot_context_compactor_js_2 = require_snapshot_context_compactor();
@@ -300700,6 +302148,7 @@ ${credentialBlock}${redactedBlock}${inboxBlock}`;
       const v3Env = process.env.DISCOVERY_PROMPT_V3;
       const useV3 = v3Env !== "false";
       const useV2 = true;
+      const perceptionEnricherEnabled = (process.env.DISCOVERY_PERCEPTION_ENRICHER === "true" || process.env.DISCOVERY_PERCEPTION_ENRICHER === "1") && typeof options?.getPerceptionPage === "function";
       const state2 = (0, exploration_state_js_1.createExplorationState)();
       const recentExchanges = [];
       const transientDirectives = [];
@@ -300824,6 +302273,8 @@ ${inboxPromptBlock}`;
         let lastBriefRoute = "";
         let lastBriefIteration = 0;
         const BRIEF_INTERVAL = 5;
+        const stuckDetectorEnabled = process.env.DISCOVERY_STUCK_DETECTOR === "1" || process.env.DISCOVERY_STUCK_DETECTOR === "true";
+        const stuckDetector = stuckDetectorEnabled ? new stuck_detector_js_1.StuckDetector({ repetitionReachesRecovery: !isDeepMode }) : null;
         while (iteration < maxIterations && !explorationComplete) {
           iteration++;
           (0, exploration_state_js_1.reduceEvent)(state2, { type: "ITERATION_STARTED", iteration });
@@ -301295,6 +302746,19 @@ ${currentSummary}`;
                     const elapsed = Date.now() - readinessStartedAt;
                     logs2.push(`   [discover-explorer] proceeded with not-ready snapshot after ${readinessRetries} retries / ${elapsed}ms`);
                   }
+                  let recoveredClickables = [];
+                  if (perceptionEnricherEnabled) {
+                    try {
+                      const result = await (0, perception_enricher_js_1.enrichCapturedPage)(options?.getPerceptionPage?.(), {
+                        route: normalized.route,
+                        elements: normalized.elements,
+                        parsedInteractiveCount: normalized.snapshotMetrics?.parsedInteractiveCount
+                      }, { onLog: (msg) => logs2.push(`   ${msg}`) });
+                      recoveredClickables = result.recovered;
+                    } catch (perceptionErr) {
+                      logs2.push(`   [perception] enrich skipped \u2014 ${perceptionErr instanceof Error ? perceptionErr.message : String(perceptionErr)}`);
+                    }
+                  }
                   (0, exploration_state_js_1.reduceEvent)(state2, {
                     type: "PAGE_CAPTURED",
                     route: normalized.route,
@@ -301363,7 +302827,7 @@ ${currentSummary}`;
                   logs2.push(`   Captured page: ${normalized.route}, ${normalized.provenCommands.length} proven commands${normalized.alreadyCaptured ? " (RE-VISIT)" : ""}`);
                   const transitionHint = !normalized.alreadyCaptured && isSurveyMode ? { tip: `Also call record_transition with fromRoute, toRoute, triggerType, and triggerLabel (the exact link text you clicked to get here).` } : {};
                   const lastAction = normalized.observations.length > 0 ? normalized.observations[normalized.observations.length - 1].action : void 0;
-                  const snapshotBlock = (0, snapshot_observation_js_1.renderCompactSnapshotBlock)(normalized, { lastAction }, { elementLimit: 6, formLimit: 3, observationLimit: 3, mode: options?.mode ?? "full" });
+                  const snapshotBlock = (0, snapshot_observation_js_1.renderCompactSnapshotBlock)(normalized, { lastAction }, { elementLimit: 6, formLimit: 3, observationLimit: 3, mode: options?.mode ?? "full", recoveredClickables });
                   toolResults.push({
                     role: "tool",
                     tool_call_id: toolCall.id,
@@ -302302,6 +303766,59 @@ Exploration complete: ${summary}`);
             }
             delete toolResults.__accountAlreadyExistsDirective;
           }
+          if (stuckDetector && assistantMessage.tool_calls && assistantMessage.tool_calls.length > 0) {
+            const actionSignatures = [];
+            let pageAffecting = false;
+            for (const tc of assistantMessage.tool_calls) {
+              if ((0, stuck_detector_js_1.isPageAffectingTool)(tc.function.name))
+                pageAffecting = true;
+              let parsedArgs = {};
+              try {
+                parsedArgs = JSON.parse(tc.function.arguments || "{}");
+              } catch {
+              }
+              const sig = (0, stuck_detector_js_1.normalizeStuckSignature)(tc.function.name, parsedArgs);
+              if (sig)
+                actionSignatures.push(sig);
+            }
+            const progressKey = `${state2.currentRoute}|${state2.visitedRoutes.size}|${state2.recordedJourneys.length}|${lastCaptureIteration}`;
+            const verdict = stuckDetector.record({
+              iteration,
+              actionSignatures,
+              route: state2.currentRoute,
+              progressKey,
+              pageAffecting
+            });
+            if (verdict.tier > 0) {
+              const topFrontier = (0, exploration_state_js_1.getRankedFrontier)(state2).slice(0, 3);
+              const frontierHint = topFrontier.length > 0 ? ` (e.g. ${topFrontier.join(", ")})` : "";
+              const repeated = verdict.repeatedAction ? verdict.repeatedAction.slice(0, 80) : null;
+              const act = repeated ? `"${repeated}"` : "the same actions";
+              let directive = null;
+              if (verdict.yieldRun) {
+                logs2.push(`  Stuck detector: yielding after repeated local loop (${verdict.kind}, ${act})`);
+                explorationComplete = true;
+                summary = `Exploration stopped after ${iteration} iterations - the agent was stuck in a local loop (${verdict.kind}${repeated ? `: ${repeated}` : ""}) and harness recovery did not break it. Visited ${state2.visitedRoutes.size} pages, recorded ${state2.recordedJourneys.length} journeys.`;
+                break;
+              } else if (verdict.recover) {
+                directive = `You are stuck in a loop on ${state2.currentRoute}: you repeated ${act} several times with no new progress, and it is not working. Stop retrying it. You MUST now do something different - navigate to an unvisited route${frontierHint}, open an unexplored tab/menu, or call finish_exploration if you have explored everything reachable. Check the "Already interacted with" and "Do Not Retry" lists before acting.`;
+                logs2.push(`  Stuck detector: harness recovery (tier 3, ${verdict.kind}, ${act})`);
+              } else if (verdict.tier === 2) {
+                directive = `STOP repeating ${act} - you have made no new progress for several iterations on ${state2.currentRoute}. ${topFrontier.length > 0 ? `Navigate to one of these unvisited routes now: ${topFrontier.join(", ")}.` : "Open an unexplored tab/menu, or call capture_page for this page and then move on."} If you have explored everything reachable, call finish_exploration. Check the "Already interacted with" and "Do Not Retry" lists before acting.`;
+                logs2.push(`  Stuck detector: firm nudge (tier 2, ${verdict.kind}, ${act})`);
+              } else {
+                directive = `You appear to be repeating ${act} on ${state2.currentRoute} without making progress. Try a different element, open an unexplored tab/menu, or navigate to an unvisited route${frontierHint}. Check the "Already interacted with" and "Do Not Retry" lists before acting.`;
+                logs2.push(`  Stuck detector: soft nudge (tier 1, ${verdict.kind}, ${act})`);
+              }
+              if (directive) {
+                if (useV3) {
+                  transientDirectives.push(directive);
+                } else {
+                  messages.push({ role: "user", content: directive });
+                }
+              }
+            }
+          }
         }
         if (!explorationComplete) {
           logs2.push(`
@@ -303010,7 +304527,8 @@ ${credentialLines}
         userNotes: featureOpts.userNotes,
         onAICall: featureOpts.onAICall,
         onProgress: featureOpts.onProgress,
-        onCredentialUpdate: featureOpts.onCredentialUpdate
+        onCredentialUpdate: featureOpts.onCredentialUpdate,
+        getPerceptionPage: featureOpts.getPerceptionPage
       }, config);
     }
   }
@@ -310054,54 +311572,13 @@ var require_mobile_exploration_state = __commonJS({
 var require_mobile_discovery_agent = __commonJS({
   "../runner-core/dist/services/mobile/mobile-discovery-agent.js"(exports) {
     "use strict";
-    var __createBinding = exports && exports.__createBinding || (Object.create ? (function(o, m, k, k2) {
-      if (k2 === void 0) k2 = k;
-      var desc = Object.getOwnPropertyDescriptor(m, k);
-      if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-        desc = { enumerable: true, get: function() {
-          return m[k];
-        } };
-      }
-      Object.defineProperty(o, k2, desc);
-    }) : (function(o, m, k, k2) {
-      if (k2 === void 0) k2 = k;
-      o[k2] = m[k];
-    }));
-    var __setModuleDefault = exports && exports.__setModuleDefault || (Object.create ? (function(o, v) {
-      Object.defineProperty(o, "default", { enumerable: true, value: v });
-    }) : function(o, v) {
-      o["default"] = v;
-    });
-    var __importStar = exports && exports.__importStar || /* @__PURE__ */ (function() {
-      var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function(o2) {
-          var ar = [];
-          for (var k in o2) if (Object.prototype.hasOwnProperty.call(o2, k)) ar[ar.length] = k;
-          return ar;
-        };
-        return ownKeys(o);
-      };
-      return function(mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) {
-          for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        }
-        __setModuleDefault(result, mod);
-        return result;
-      };
-    })();
     Object.defineProperty(exports, "__esModule", { value: true });
     exports.runMobileDiscoveryOnRunner = runMobileDiscoveryOnRunner2;
     var mobile_explorer_js_1 = require_mobile_explorer();
     var mobile_discovery_prompts_js_1 = require_mobile_discovery_prompts();
+    var mobile_generator_js_1 = require_mobile_generator();
     var mobile_exploration_state_js_1 = require_mobile_exploration_state();
     var discover_planner_js_1 = require_discover_planner();
-    var GENERATOR_MODULE = "./mobile-generator.js";
-    var defaultRunGenerate = async (args) => {
-      const mod = await Promise.resolve(`${GENERATOR_MODULE}`).then((s) => __importStar(__require(s)));
-      return mod.runMobileGeneratePhase(args);
-    };
     var EXPLORE_BUDGET_DEEP = 60;
     var EXPLORE_BUDGET_SURVEY = 40;
     function platformForMedium(medium) {
@@ -310119,7 +311596,9 @@ var require_mobile_discovery_agent = __commonJS({
       return {
         collectedPages: explore.collectedPages,
         collectedTransitions,
-        pageScreenshots: explore.pageScreenshots,
+        // Native screenshots are multi-megabyte PNGs. The live mirror streams them
+        // through heartbeat telemetry; discovery checkpoints keep the screen graph
+        // and transitions so large Android surveys cannot exceed server body limits.
         exploreStats: explore.exploreStats,
         healthObservations: explore.healthObservations
       };
@@ -310136,7 +311615,7 @@ var require_mobile_discovery_agent = __commonJS({
       const onScreenshot = callbacks?.onScreenshot;
       const runExplore = callbacks?.runExplore ?? mobile_explorer_js_1.runMobileExplorePhase;
       const runPlan = callbacks?.runPlan ?? mobile_discovery_prompts_js_1.runMobileAIPlanner;
-      const runGenerate = callbacks?.runGenerate ?? defaultRunGenerate;
+      const runGenerate = callbacks?.runGenerate ?? mobile_generator_js_1.runMobileGeneratePhase;
       const log2 = (line) => {
         logs2.push(line);
         try {
@@ -310209,6 +311688,7 @@ Explore complete: ${explore.exploreStats.pagesDiscovered} screens, ${explore.exp
           featureName: ctx.featureName,
           existingTestNames: ctx.existingTestNames,
           existingFeatureNames: ctx.existingFeatureNames,
+          recordedJourneys: explore.recordedJourneys,
           collectedPages: screenMap,
           collectedTransitions,
           credentials: {
@@ -310276,9 +311756,8 @@ Plan: ${planResult.scenarios.length} scenarios, ${planResult.featureGroups.lengt
           ctx,
           onLog: (line) => log2(line),
           onAICall,
-          onTestGenerated: (test) => {
-            callbacks?.onTestGenerated?.(test, { phase: "verified" });
-          }
+          onScreenshot,
+          onTestGenerated: (test) => callbacks?.onTestGenerated?.(test, { phase: "verified" })
         });
         const generateElapsed = ((Date.now() - startTime) / 1e3).toFixed(1);
         log2(`
@@ -310802,7 +312281,8 @@ Respond with ONLY valid JSON:
           userNotes: ctx.userNotes,
           onAICall,
           onProgress,
-          onCredentialUpdate: ctx.onCredentialUpdate
+          onCredentialUpdate: ctx.onCredentialUpdate,
+          getPerceptionPage: () => handle?.page ?? null
         });
         logs2.push(...exploreResult.logs);
         screenshots.push(...exploreResult.screenshots);
@@ -311341,6 +312821,7 @@ Fatal error: ${msg}`);
             onAICall,
             onProgress,
             onCredentialUpdate: ctx.onCredentialUpdate,
+            getPerceptionPage: () => handle?.page ?? null,
             onTestPhaseChange: (phase) => {
               healthObserver?.setTestPhase(phase);
               liveCollector?.setTestPhase(phase);
@@ -323980,6 +325461,8 @@ var require_live_browser_registry = __commonJS({
     exports.liveBrowserRegistry = void 0;
     var THUMBNAIL_INTERVAL_MS = parseInt(process.env.LIVE_BROWSER_THUMBNAIL_INTERVAL_MS ?? "4000", 10) || 4e3;
     var THUMBNAIL_QUALITY = parseInt(process.env.LIVE_BROWSER_THUMBNAIL_QUALITY ?? "60", 10) || 60;
+    var BROWSER_THUMBNAIL_MAX_BASE64_BYTES = parseInt(process.env.LIVE_BROWSER_THUMBNAIL_MAX_BASE64_BYTES ?? "400000", 10) || 4e5;
+    var MOBILE_THUMBNAIL_MAX_BASE64_BYTES = parseInt(process.env.LIVE_MOBILE_THUMBNAIL_MAX_BASE64_BYTES ?? "4500000", 10) || 45e5;
     var STALE_SESSION_MS = parseInt(process.env.LIVE_BROWSER_STALE_MS ?? `${10 * 60 * 1e3}`, 10) || 10 * 60 * 1e3;
     var MAX_SESSIONS = parseInt(process.env.LIVE_BROWSER_MAX_SESSIONS ?? "32", 10) || 32;
     var LiveBrowserRegistry = class {
@@ -324074,7 +325557,8 @@ var require_live_browser_registry = __commonJS({
           entry.currentUrl = snapshot.currentUrl;
         }
         const thumbnail = snapshot.thumbnailJpegBase64;
-        if (thumbnail && thumbnail.length <= 16e4) {
+        const thumbnailLimit = entry.meta.surface === "mobile" ? MOBILE_THUMBNAIL_MAX_BASE64_BYTES : BROWSER_THUMBNAIL_MAX_BASE64_BYTES;
+        if (thumbnail && thumbnail.length <= thumbnailLimit) {
           entry.thumbnailJpegBase64 = thumbnail;
           entry.thumbnailCapturedAt = typeof snapshot.thumbnailCapturedAt === "number" && Number.isFinite(snapshot.thumbnailCapturedAt) ? snapshot.thumbnailCapturedAt : Date.now();
           entry.thumbnailWidth = typeof snapshot.thumbnailWidth === "number" && Number.isFinite(snapshot.thumbnailWidth) ? snapshot.thumbnailWidth : void 0;
@@ -324208,7 +325692,7 @@ var require_live_browser_registry = __commonJS({
             scale: "css"
           });
           const base64 = buf.toString("base64");
-          if (base64.length > 16e4) {
+          if (base64.length > BROWSER_THUMBNAIL_MAX_BASE64_BYTES) {
             return;
           }
           entry.thumbnailJpegBase64 = base64;
@@ -324474,6 +325958,7 @@ var require_dist2 = __commonJS({
     __exportStar(require_ai_provider(), exports);
     __exportStar(require_mobile_types(), exports);
     __exportStar(require_mobile_source_parser(), exports);
+    __exportStar(require_mobile_boundary(), exports);
     var mobile_explorer_js_1 = require_mobile_explorer();
     Object.defineProperty(exports, "runMobileExplorePhase", { enumerable: true, get: function() {
       return mobile_explorer_js_1.runMobileExplorePhase;
@@ -324520,6 +326005,7 @@ var require_dist2 = __commonJS({
       return api_call_redaction_js_1.headerVal;
     } });
     __exportStar(require_mcp_healer(), exports);
+    __exportStar(require_selector_registry_context(), exports);
     var grok_per_test_healer_js_1 = require_grok_per_test_healer();
     Object.defineProperty(exports, "executeGrokPerTestHeal", { enumerable: true, get: function() {
       return grok_per_test_healer_js_1.executeGrokPerTestHeal;
@@ -324805,7 +326291,7 @@ var require_package4 = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@validate.qa/runner",
-      version: "1.0.4",
+      version: "1.0.6",
       description: "validate local test runner - execute Playwright tests on your machine, connected to validate.qa cloud.",
       bin: {
         "validate-runner": "dist/cli.js"
@@ -324903,7 +326389,7 @@ var import_runner_core = __toESM(require_dist2());
 var import_runner_core2 = __toESM(require_dist2());
 
 // src/runner.ts
-var import_runner_core9 = __toESM(require_dist2());
+var import_runner_core10 = __toESM(require_dist2());
 
 // src/services/regression-runner.ts
 var import_runner_core3 = __toESM(require_dist2());
@@ -324918,7 +326404,7 @@ var import_runner_core5 = __toESM(require_dist2());
 var import_runner_core6 = __toESM(require_dist2());
 
 // src/runner.ts
-var import_runner_core10 = __toESM(require_dist2());
+var import_runner_core11 = __toESM(require_dist2());
 
 // src/services/auth-state.ts
 var INLINE_LOGIN_TAG = "@inline-login";
@@ -324938,6 +326424,7 @@ function shouldUseAuthState(tags, playwrightCode) {
 
 // src/services/appium-executor.ts
 init_dist();
+var import_runner_core8 = __toESM(require_dist2());
 
 // src/services/appium-lifecycle.ts
 import { spawn, execFileSync } from "child_process";
@@ -325477,6 +326964,647 @@ function getRunnerCapabilities() {
   };
 }
 
+// src/services/mobile/mobile-network-capture.ts
+var import_runner_core7 = __toESM(require_dist2());
+import { execFile, execFileSync as execFileSync3 } from "child_process";
+import { randomUUID } from "crypto";
+import { mkdtemp, rm, writeFile, readFile, readdir, mkdir, unlink } from "fs/promises";
+import { tmpdir, networkInterfaces } from "os";
+import { join as join2 } from "path";
+import { promisify } from "util";
+import {
+  getLocal,
+  generateCACertificate
+} from "mockttp";
+var execFileAsync = promisify(execFile);
+var MAX_CALLS = 1e3;
+var MAX_BODY_CAPTURE_BYTES = 64 * 1024;
+var DEVICE_CMD_TIMEOUT_MS = 15e3;
+var CA_KEY_BITS = 2048;
+var ANDROID_EMULATOR_HOST_LOOPBACK = "10.0.2.2";
+var PENDING_CLEANUP_DIR = join2(tmpdir(), "validateqa-mobile-capture-pending");
+function envFlag(name) {
+  const value = (process.env[name] ?? "").trim().toLowerCase();
+  return value === "1" || value === "true" || value === "yes" || value === "on";
+}
+function rawHeadersToPairs(rawHeaders) {
+  return rawHeaders.map(([name, value]) => ({ name, value }));
+}
+function headerValue(pairs, name) {
+  const lower = name.toLowerCase();
+  return pairs.find((h) => h.name.toLowerCase() === lower)?.value;
+}
+function resolveHostIp() {
+  const ifaces = networkInterfaces();
+  for (const addrs of Object.values(ifaces)) {
+    if (!addrs) continue;
+    for (const addr of addrs) {
+      if (addr.family === "IPv4" && !addr.internal) return addr.address;
+    }
+  }
+  return "127.0.0.1";
+}
+function resolveProxyHostForDevice(platform3, isPhysical) {
+  if (platform3 === "ANDROID" && !isPhysical) return ANDROID_EMULATOR_HOST_LOOPBACK;
+  if (platform3 === "IOS" && !isPhysical) return "127.0.0.1";
+  return resolveHostIp();
+}
+function normalizeRemoteAddress(addr) {
+  if (!addr) return "";
+  return addr.startsWith("::ffff:") ? addr.slice("::ffff:".length) : addr;
+}
+function isLoopbackAddress(addr) {
+  return addr === "127.0.0.1" || addr.startsWith("127.") || addr === "::1" || addr === "";
+}
+function isPrivateAddress(addr) {
+  if (/^10\./.test(addr)) return true;
+  if (/^192\.168\./.test(addr)) return true;
+  if (/^172\.(1[6-9]|2\d|3[01])\./.test(addr)) return true;
+  if (/^169\.254\./.test(addr)) return true;
+  const lower = addr.toLowerCase();
+  if (lower.startsWith("fe80:")) return true;
+  if (lower.startsWith("fc") || lower.startsWith("fd")) return true;
+  return false;
+}
+function isAllowedProxyPeer(remoteAddress, isPhysical) {
+  const addr = normalizeRemoteAddress(remoteAddress);
+  if (isLoopbackAddress(addr)) return true;
+  return isPhysical && isPrivateAddress(addr);
+}
+function installSourceIpGuard(server3, isPhysical, onLog) {
+  const underlying = server3.server;
+  if (!underlying || typeof underlying.on !== "function") {
+    onLog?.(
+      "[mobile-net] WARNING: could not attach source-IP guard to the proxy listener; the port is bound to all interfaces \u2014 firewall it to the device subnet."
+    );
+    return;
+  }
+  underlying.on("connection", (socket) => {
+    if (!isAllowedProxyPeer(socket.remoteAddress, isPhysical)) {
+      onLog?.(`[mobile-net] rejected proxy connection from disallowed source ${socket.remoteAddress}`);
+      socket.destroy();
+    }
+  });
+}
+function isTextish(contentType) {
+  if (!contentType) return false;
+  return /json|text|xml|graphql|html|csv|javascript|urlencoded/i.test(contentType);
+}
+async function readBodyText(body, contentType) {
+  if (!isTextish(contentType)) return void 0;
+  try {
+    const decoded = await body.getDecodedBuffer();
+    if (!decoded || decoded.length === 0) return void 0;
+    if (decoded.length > MAX_BODY_CAPTURE_BYTES) {
+      return decoded.subarray(0, MAX_BODY_CAPTURE_BYTES).toString("utf-8");
+    }
+    return decoded.toString("utf-8");
+  } catch {
+    return void 0;
+  }
+}
+var MitmProxy = class {
+  constructor(caKeyPem, caCertPem, caCertPath, isPhysical, tlsPassthroughAll, onLog) {
+    this.caKeyPem = caKeyPem;
+    this.caCertPem = caCertPem;
+    this.caCertPath = caCertPath;
+    this.isPhysical = isPhysical;
+    this.tlsPassthroughAll = tlsPassthroughAll;
+    this.onLog = onLog;
+  }
+  server = null;
+  inFlight = /* @__PURE__ */ new Map();
+  calls = [];
+  dropped = 0;
+  /** Flips true once any HTTPS response is successfully MITM-ed. */
+  httpsIntercepted = false;
+  /** Best-known reason interception is unavailable, refined by TLS failures. */
+  tlsFailureReason = null;
+  /** Count of opaque HTTPS tunnels when TLS passthrough is enabled. */
+  tlsPassthroughCount = 0;
+  /** Start listening; resolves with the actual bound port. */
+  async listen(preferredPort) {
+    const server3 = getLocal({
+      // Our generated CA — mockttp mints per-host leaf certs signed by it.
+      https: {
+        key: this.caKeyPem,
+        cert: this.caCertPem,
+        ...this.tlsPassthroughAll ? { tlsPassthrough: [{ hostname: "*" }] } : {}
+      },
+      // HTTP/2 with HTTP/1.1 fallback; mobile clients negotiate either.
+      http2: "fallback",
+      // Keep the proxy quiet unless explicitly debugging.
+      recordTraffic: false
+    });
+    await server3.forAnyRequest().thenPassThrough({ ignoreHostHttpsErrors: true });
+    await server3.on("request", (req) => this.onRequest(req));
+    await server3.on("response", (res) => this.onResponse(res));
+    await server3.on("tls-client-error", (failure) => this.onTlsClientError(failure));
+    await server3.on("tls-passthrough-opened", (event) => this.onTlsPassthroughOpened(event));
+    await (preferredPort > 0 ? server3.start(preferredPort) : server3.start());
+    installSourceIpGuard(server3, this.isPhysical, this.onLog);
+    this.server = server3;
+    return server3.port;
+  }
+  /** Captured calls, finalized through the shared redaction constructor. */
+  finalize() {
+    return this.calls.map(
+      (c) => (0, import_runner_core7.buildApiCallSummary)({
+        method: c.method,
+        url: c.url,
+        status: c.status,
+        durationMs: c.durationMs,
+        authHeader: c.authHeader,
+        cookieHeader: c.cookieHeader,
+        requestContentType: c.requestContentType,
+        responseContentType: c.responseContentType,
+        respHeaders: c.respHeaders,
+        reqBodyText: c.reqBodyText,
+        respBodyText: c.respBodyText,
+        responseSize: c.responseSize,
+        timestamp: c.startedAt,
+        testPhase: "UNKNOWN"
+      })
+    );
+  }
+  /** True once at least one HTTPS exchange was decrypted (CA trusted). */
+  get isIntercepting() {
+    return this.httpsIntercepted;
+  }
+  /** A precise reason interception is (still) unavailable, or null if it works. */
+  get interceptionReason() {
+    if (this.httpsIntercepted) return null;
+    if (this.tlsPassthroughAll) {
+      return "HTTPS TLS passthrough active: HTTPS bodies are not decrypted, but app traffic continues. Set VALIDATEQA_MOBILE_FORCE_TLS_MITM=1 for debug apps/devices that trust the validate.qa CA" + (this.caCertPath ? ` at ${this.caCertPath}.` : ".");
+    }
+    return this.tlsFailureReason;
+  }
+  async close() {
+    const server3 = this.server;
+    this.server = null;
+    this.inFlight.clear();
+    if (!server3) return;
+    try {
+      await server3.stop();
+    } catch (err) {
+      this.onLog?.(`[mobile-net] proxy stop error (ignored): ${errMsg(err)}`);
+    }
+    this.onLog?.(
+      `[mobile-net] proxy closed: ${this.calls.length} calls captured` + (this.dropped > 0 ? ` (${this.dropped} dropped over cap)` : "")
+    );
+  }
+  // ── request → buffer by id ────────────────────────────────────────────────
+  async onRequest(req) {
+    try {
+      const reqHeaders = rawHeadersToPairs(req.rawHeaders);
+      const requestContentType = headerValue(reqHeaders, "content-type");
+      const isHttps = isHttpsUrl(req.url);
+      const reqBodyText = (0, import_runner_core7.isApiCall)(req.url, requestContentType) ? await readBodyText(req.body, requestContentType) : void 0;
+      this.inFlight.set(req.id, {
+        method: req.method,
+        url: req.url,
+        startedAt: req.timingEvents.startTime,
+        reqHeaders,
+        requestContentType,
+        authHeader: headerValue(reqHeaders, "authorization"),
+        cookieHeader: headerValue(reqHeaders, "cookie"),
+        reqBodyText,
+        isHttps
+      });
+    } catch (err) {
+      this.onLog?.(`[mobile-net] request capture error (ignored): ${errMsg(err)}`);
+    }
+  }
+  // ── response → finalize the matched request ───────────────────────────────
+  async onResponse(res) {
+    const pending = this.inFlight.get(res.id);
+    if (!pending) return;
+    this.inFlight.delete(res.id);
+    try {
+      if (pending.isHttps && !this.httpsIntercepted) {
+        this.httpsIntercepted = true;
+        this.tlsFailureReason = null;
+        this.onLog?.("[mobile-net] HTTPS interception confirmed (CA trusted; bodies decrypted).");
+      }
+      const respHeaders = rawHeadersToPairs(res.rawHeaders);
+      const responseContentType = headerValue(respHeaders, "content-type");
+      const api = (0, import_runner_core7.isApiCall)(pending.url, responseContentType);
+      if (!api && (0, import_runner_core7.isStaticAssetByExt)(pending.url)) return;
+      if (this.calls.length >= MAX_CALLS) {
+        this.dropped++;
+        return;
+      }
+      const respBodyText = api ? await readBodyText(res.body, responseContentType) : void 0;
+      const responseSize = await measureBody(res.body);
+      const durationMs = computeDuration(pending.startedAt, res);
+      this.calls.push({
+        method: pending.method,
+        url: pending.url,
+        status: res.statusCode,
+        startedAt: pending.startedAt,
+        durationMs,
+        reqHeaders: pending.reqHeaders,
+        respHeaders,
+        requestContentType: pending.requestContentType,
+        responseContentType,
+        authHeader: pending.authHeader,
+        cookieHeader: pending.cookieHeader,
+        reqBodyText: pending.reqBodyText,
+        respBodyText,
+        responseSize,
+        intercepted: true
+      });
+    } catch (err) {
+      this.onLog?.(`[mobile-net] response capture error (ignored): ${errMsg(err)}`);
+    }
+  }
+  // ── tls-client-error → record WHY interception failed ─────────────────────
+  onTlsClientError(failure) {
+    if (this.httpsIntercepted) return;
+    const host = failure.destination?.hostname ?? failure.tlsMetadata.sniHostname ?? "unknown host";
+    const trustHint = this.caCertPath ? `Trust the validate.qa CA at ${this.caCertPath} to enable HTTPS body capture.` : "Trust the generated validate.qa CA to enable HTTPS body capture.";
+    let reason;
+    switch (failure.failureCause) {
+      case "cert-rejected":
+        reason = `TLS handshake to ${host} rejected our certificate: the device does not trust the validate.qa CA, so HTTPS bodies cannot be decrypted (plaintext HTTP still captured). ` + trustHint;
+        break;
+      case "closed":
+      case "reset":
+        reason = `TLS handshake to ${host} was dropped after our certificate was offered \u2014 this is the signature of certificate pinning in the app. HTTPS bodies for pinned hosts cannot be decrypted (plaintext HTTP and connect-level host metadata still captured).`;
+        break;
+      case "no-shared-cipher":
+        reason = `TLS handshake to ${host} failed: no shared cipher with the client.`;
+        break;
+      case "handshake-timeout":
+        reason = `TLS handshake to ${host} timed out before completing.`;
+        break;
+      default:
+        reason = `TLS handshake to ${host} failed (${failure.failureCause}); HTTPS not intercepted for it.`;
+    }
+    if (!this.tlsFailureReason || failure.failureCause === "cert-rejected" || failure.failureCause === "closed" || failure.failureCause === "reset") {
+      this.tlsFailureReason = reason;
+    }
+    this.onLog?.(`[mobile-net] ${reason}`);
+  }
+  onTlsPassthroughOpened(event) {
+    this.tlsPassthroughCount++;
+    if (this.tlsPassthroughCount === 1) {
+      const host = event.destination?.hostname ?? event.hostname ?? "unknown host";
+      this.onLog?.(
+        `[mobile-net] HTTPS TLS passthrough active for ${host}; app traffic is preserved, but HTTPS bodies are not decrypted.`
+      );
+    }
+  }
+};
+function isHttpsUrl(url) {
+  try {
+    return new URL(url).protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+async function measureBody(body) {
+  try {
+    const decoded = await body.getDecodedBuffer();
+    return decoded ? decoded.length : 0;
+  } catch {
+    return 0;
+  }
+}
+function computeDuration(startedAt, res) {
+  const sent = res.timingEvents.responseSentTimestamp;
+  const start = res.timingEvents.startTimestamp;
+  if (typeof sent === "number" && typeof start === "number" && sent >= start) {
+    return Math.round(sent - start);
+  }
+  const elapsed = Date.now() - startedAt;
+  return elapsed > 0 ? elapsed : 0;
+}
+async function generateCaCert(dir, onLog) {
+  try {
+    const { key, cert } = await generateCACertificate({
+      subject: {
+        commonName: "validate.qa Mobile Capture CA",
+        organizationName: "validate.qa"
+      },
+      bits: CA_KEY_BITS
+      // mockttp's generated CA carries its own (multi-year) validity window; we
+      // rely on stop() to remove the cert from the device promptly after the run
+      // rather than on a short expiry.
+    });
+    const caCertPath = join2(dir, "validateqa-mobile-ca.pem");
+    await writeFile(caCertPath, cert, "utf-8");
+    return { caCertPath, caKeyPem: key, caCertPem: cert };
+  } catch (err) {
+    onLog?.(`[mobile-net] CA generation failed; running plaintext-only: ${errMsg(err)}`);
+    return null;
+  }
+}
+async function androidReadProxy(deviceId) {
+  try {
+    const { stdout } = await execFileAsync(
+      "adb",
+      ["-s", deviceId, "shell", "settings", "get", "global", "http_proxy"],
+      { timeout: DEVICE_CMD_TIMEOUT_MS }
+    );
+    const value = stdout.trim();
+    return value === "" || value === "null" ? null : value;
+  } catch {
+    return null;
+  }
+}
+async function androidSetProxy(deviceId, hostPort, onLog) {
+  try {
+    await execFileAsync(
+      "adb",
+      ["-s", deviceId, "shell", "settings", "put", "global", "http_proxy", hostPort],
+      { timeout: DEVICE_CMD_TIMEOUT_MS }
+    );
+    return true;
+  } catch (err) {
+    onLog?.(`[mobile-net] adb set http_proxy failed: ${errMsg(err)}`);
+    return false;
+  }
+}
+async function androidClearProxy(deviceId, originalProxy, onLog) {
+  const restoreValue = originalProxy && originalProxy.length > 0 ? originalProxy : ":0";
+  try {
+    await execFileAsync(
+      "adb",
+      ["-s", deviceId, "shell", "settings", "put", "global", "http_proxy", restoreValue],
+      { timeout: DEVICE_CMD_TIMEOUT_MS }
+    );
+  } catch (err) {
+    onLog?.(`[mobile-net] adb restore http_proxy failed: ${errMsg(err)}`);
+  }
+}
+async function androidInstallCa(deviceId, caCertPath) {
+  const devicePath = "/sdcard/validateqa-mobile-ca.pem";
+  try {
+    await execFileAsync("adb", ["-s", deviceId, "push", caCertPath, devicePath], {
+      timeout: DEVICE_CMD_TIMEOUT_MS
+    });
+    return {
+      installed: false,
+      note: `CA copied from ${caCertPath} to ${devicePath} but NOT auto-trusted: Android 7+ apps must opt into user CAs (network_security_config), and the system store requires a rooted/writable image. HTTPS bodies decrypt only for apps that trust user CAs; pinned apps never decrypt.`
+    };
+  } catch (err) {
+    return { installed: false, note: `CA push failed: ${errMsg(err)}` };
+  }
+}
+async function androidRemoveCa(deviceId, onLog) {
+  try {
+    await execFileAsync(
+      "adb",
+      ["-s", deviceId, "shell", "rm", "-f", "/sdcard/validateqa-mobile-ca.pem"],
+      { timeout: DEVICE_CMD_TIMEOUT_MS }
+    );
+  } catch (err) {
+    onLog?.(`[mobile-net] adb remove CA failed: ${errMsg(err)}`);
+  }
+}
+async function iosSimTrustCa(deviceId, caCertPath) {
+  try {
+    await execFileAsync("xcrun", ["simctl", "keychain", deviceId, "add-root-cert", caCertPath], {
+      timeout: DEVICE_CMD_TIMEOUT_MS
+    });
+    return {
+      trusted: true,
+      note: "CA added to simulator keychain (add-root-cert). NOTE: the simulator has no per-app HTTP proxy setting controllable via simctl \u2014 it shares the host network, so only traffic that actually routes through the proxy is intercepted; pinned apps still never decrypt."
+    };
+  } catch (err) {
+    return { trusted: false, note: `simctl add-root-cert failed: ${errMsg(err)}` };
+  }
+}
+async function iosSimRemoveCa(deviceId, onLog) {
+  if (process.env.VALIDATEQA_MOBILE_SIM_KEYCHAIN_RESET === "1") {
+    try {
+      await execFileAsync("xcrun", ["simctl", "keychain", deviceId, "reset"], {
+        timeout: DEVICE_CMD_TIMEOUT_MS
+      });
+      onLog?.(`[mobile-net] simctl keychain reset run for ${deviceId} (opt-in; cleared ALL sim certs).`);
+    } catch (err) {
+      onLog?.(`[mobile-net] simctl keychain reset failed: ${errMsg(err)}`);
+    }
+    return;
+  }
+  onLog?.(
+    `[mobile-net] NOTE: the validate.qa capture CA remains TRUSTED in simulator ${deviceId}. simctl has no scoped remove (only a full keychain reset that wipes ALL certs), so we leave the single CA in place. Use a throwaway simulator, or set VALIDATEQA_MOBILE_SIM_KEYCHAIN_RESET=1 to reset the whole sim keychain on teardown.`
+  );
+}
+function errMsg(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+var activeCleanups = /* @__PURE__ */ new Map();
+var exitHandlersInstalled = false;
+function markerPath(sessionKey) {
+  return join2(PENDING_CLEANUP_DIR, `${sessionKey}.json`);
+}
+async function writePendingCleanup(sessionKey, marker) {
+  try {
+    await mkdir(PENDING_CLEANUP_DIR, { recursive: true });
+    await writeFile(markerPath(sessionKey), JSON.stringify(marker), "utf-8");
+  } catch {
+  }
+}
+async function removePendingCleanup(sessionKey) {
+  try {
+    await unlink(markerPath(sessionKey));
+  } catch {
+  }
+}
+function restoreDeviceSync(marker, onLog) {
+  const run2 = (args) => {
+    try {
+      execFileSync3("adb", args, { timeout: DEVICE_CMD_TIMEOUT_MS, stdio: "ignore" });
+    } catch {
+    }
+  };
+  if (marker.platform === "ANDROID") {
+    if (marker.proxySet) {
+      const restoreValue = marker.originalProxy && marker.originalProxy.length > 0 ? marker.originalProxy : ":0";
+      run2(["-s", marker.deviceId, "shell", "settings", "put", "global", "http_proxy", restoreValue]);
+    }
+    if (marker.caInstalledOnDevice) {
+      run2(["-s", marker.deviceId, "shell", "rm", "-f", "/sdcard/validateqa-mobile-ca.pem"]);
+    }
+  }
+  onLog?.(`[mobile-net] restored device ${marker.deviceId} from pending-cleanup marker.`);
+}
+async function reconcilePendingCleanups(onLog) {
+  let files;
+  try {
+    files = await readdir(PENDING_CLEANUP_DIR);
+  } catch {
+    return;
+  }
+  for (const file of files) {
+    if (!file.endsWith(".json")) continue;
+    const full = join2(PENDING_CLEANUP_DIR, file);
+    try {
+      const raw = await readFile(full, "utf-8");
+      const marker = JSON.parse(raw);
+      if (marker && typeof marker.deviceId === "string" && marker.platform) {
+        onLog?.(`[mobile-net] reconciling orphaned capture cleanup for ${marker.deviceId}.`);
+        restoreDeviceSync(marker, onLog);
+      }
+    } catch {
+    }
+    try {
+      await unlink(full);
+    } catch {
+    }
+  }
+}
+function ensureExitHandlers() {
+  if (exitHandlersInstalled) return;
+  exitHandlersInstalled = true;
+  const drain = () => {
+    for (const marker of activeCleanups.values()) {
+      restoreDeviceSync(marker);
+    }
+  };
+  process.on("beforeExit", drain);
+  process.on("exit", drain);
+  for (const signal of ["SIGTERM", "SIGINT"]) {
+    process.on(signal, () => {
+      drain();
+      process.removeAllListeners(signal);
+      process.kill(process.pid, signal);
+    });
+  }
+}
+async function startMobileNetworkCapture(options) {
+  const { platform: platform3, deviceId, isPhysical = false, preferredPort = 0, onLog } = options;
+  const forceTlsMitm = options.forceTlsMitm ?? envFlag("VALIDATEQA_MOBILE_FORCE_TLS_MITM");
+  const tlsPassthroughAll = !forceTlsMitm && (platform3 === "ANDROID" || platform3 === "IOS" && isPhysical);
+  await reconcilePendingCleanups(onLog);
+  ensureExitHandlers();
+  const sessionKey = randomUUID();
+  const originalProxy = platform3 === "ANDROID" ? await androidReadProxy(deviceId) : null;
+  let tmpDir = null;
+  let caCertPath = null;
+  let caKeyPem = null;
+  let caCertPem = null;
+  try {
+    tmpDir = await mkdtemp(join2(tmpdir(), "validateqa-mobile-ca-"));
+    const ca = await generateCaCert(tmpDir, onLog);
+    if (ca) {
+      caCertPath = ca.caCertPath;
+      caKeyPem = ca.caKeyPem;
+      caCertPem = ca.caCertPem;
+    }
+  } catch (err) {
+    onLog?.(`[mobile-net] CA setup degraded: ${errMsg(err)}`);
+  }
+  if (!caKeyPem || !caCertPem) {
+    try {
+      const fallback = await generateCACertificate();
+      caKeyPem = fallback.key;
+      caCertPem = fallback.cert;
+    } catch (err) {
+      onLog?.(`[mobile-net] fatal CA failure, cannot start proxy: ${errMsg(err)}`);
+      if (tmpDir) {
+        await rm(tmpDir, { recursive: true, force: true }).catch(() => void 0);
+      }
+      throw err instanceof Error ? err : new Error(String(err));
+    }
+  }
+  const proxy = new MitmProxy(caKeyPem, caCertPem, caCertPath, isPhysical, tlsPassthroughAll, onLog);
+  const proxyPort = await proxy.listen(preferredPort);
+  const proxyHost = resolveProxyHostForDevice(platform3, isPhysical);
+  const hostPort = `${proxyHost}:${proxyPort}`;
+  onLog?.(
+    `[mobile-net] ${tlsPassthroughAll ? "capture proxy" : "MITM proxy"} listening; device target ${hostPort} (${platform3}${isPhysical ? " physical" : ""})`
+  );
+  let wiringReason = "HTTPS interception pending: capture begins once the device routes a TLS handshake through the proxy.";
+  let proxySet = false;
+  let caInstalledOnDevice = false;
+  try {
+    if (platform3 === "ANDROID") {
+      proxySet = await androidSetProxy(deviceId, hostPort, onLog);
+      if (!proxySet) {
+        wiringReason = "adb proxy configuration failed; no device traffic will be routed through the proxy.";
+      } else if (tlsPassthroughAll) {
+        wiringReason = "Android HTTPS is tunneled without MITM by default because release apps usually do not trust user-installed CAs. Plaintext HTTP is still captured; HTTPS bodies are not decrypted. For debug apps/devices that trust the CA, set VALIDATEQA_MOBILE_FORCE_TLS_MITM=1" + (caCertPath ? ` and trust ${caCertPath}.` : ".");
+      } else if (caCertPath) {
+        const { note } = await androidInstallCa(deviceId, caCertPath);
+        caInstalledOnDevice = true;
+        wiringReason = note;
+      }
+    } else {
+      if (!isPhysical && caCertPath) {
+        const { trusted, note } = await iosSimTrustCa(deviceId, caCertPath);
+        caInstalledOnDevice = trusted;
+        wiringReason = note;
+      } else if (isPhysical) {
+        wiringReason = "Physical iOS HTTPS is tunneled without MITM by default. Set the Wi-Fi HTTP proxy and trust the CA manually, then run with VALIDATEQA_MOBILE_FORCE_TLS_MITM=1 to decrypt HTTPS bodies" + (caCertPath ? ` (${caCertPath}).` : ".");
+      }
+    }
+  } catch (err) {
+    wiringReason = `device wiring degraded: ${errMsg(err)}`;
+    onLog?.(`[mobile-net] ${wiringReason}`);
+  }
+  if (proxySet || caInstalledOnDevice) {
+    const marker = {
+      platform: platform3,
+      deviceId,
+      isPhysical,
+      proxySet,
+      originalProxy,
+      caInstalledOnDevice
+    };
+    activeCleanups.set(sessionKey, marker);
+    await writePendingCleanup(sessionKey, marker);
+  }
+  const capturedTmpDir = tmpDir;
+  const capturedCaCertPath = caCertPath;
+  let stopped = false;
+  let finalCalls = [];
+  const getCapabilities = () => {
+    if (proxy.isIntercepting) return { intercepting: true };
+    const reason = proxy.interceptionReason ?? wiringReason;
+    return reason ? { intercepting: false, reason } : { intercepting: false };
+  };
+  const stop = async () => {
+    if (stopped) return finalCalls;
+    stopped = true;
+    if (proxySet && platform3 === "ANDROID") {
+      await androidClearProxy(deviceId, originalProxy, onLog);
+    }
+    if (caInstalledOnDevice && capturedCaCertPath) {
+      if (platform3 === "ANDROID") {
+        await androidRemoveCa(deviceId, onLog);
+      } else if (!isPhysical) {
+        await iosSimRemoveCa(deviceId, onLog);
+      }
+    }
+    activeCleanups.delete(sessionKey);
+    await removePendingCleanup(sessionKey);
+    finalCalls = proxy.finalize();
+    await proxy.close();
+    if (capturedTmpDir) {
+      try {
+        await rm(capturedTmpDir, { recursive: true, force: true });
+      } catch (err) {
+        onLog?.(`[mobile-net] temp CA cleanup failed: ${errMsg(err)}`);
+      }
+    }
+    const apiCount = finalCalls.filter((c) => c.isApi).length;
+    onLog?.(
+      `[mobile-net] stopped: ${finalCalls.length} calls captured (${apiCount} API; HTTPS interception ${proxy.isIntercepting ? "ACTIVE" : "inactive"}).`
+    );
+    return finalCalls;
+  };
+  return {
+    proxyPort,
+    proxyHost,
+    caCertPath: capturedCaCertPath,
+    getCapabilities,
+    stop
+  };
+}
+
 // src/services/appium-executor.ts
 var DEFAULT_STEP_TIMEOUT_MS = 1e4;
 var WebDriverTransportError = class extends Error {
@@ -325588,6 +327716,86 @@ async function openDeepLink(sessionId, platform3, deeplink, appId) {
     body: JSON.stringify({ script: "mobile: deepLink", args })
   });
 }
+function readExecuteStringValue(result) {
+  if (result && typeof result === "object" && "value" in result) {
+    const value = result.value;
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return void 0;
+}
+function readActiveBundleId(result) {
+  if (result && typeof result === "object" && "value" in result) {
+    const value = result.value;
+    if (value && typeof value === "object" && "bundleId" in value) {
+      const bundleId = value.bundleId;
+      if (typeof bundleId === "string" && bundleId.trim()) return bundleId.trim();
+    }
+  }
+  return void 0;
+}
+function normalizeAndroidActivity(activity, pkg2) {
+  const trimmed = activity?.trim();
+  if (!trimmed) return void 0;
+  const packageName = pkg2?.trim();
+  if (!packageName) return trimmed;
+  if (trimmed.startsWith(".")) return `${packageName}${trimmed}`;
+  if (!trimmed.includes(".")) return `${packageName}.${trimmed}`;
+  return trimmed;
+}
+async function executeMobileScript(sessionId, script, args) {
+  return wdRequest(`/session/${sessionId}/execute/sync`, {
+    method: "POST",
+    body: JSON.stringify({ script, args })
+  });
+}
+async function readForegroundScreenSignal(sessionId, platform3) {
+  if (platform3 === "ANDROID") {
+    const [packageResult, activityResult] = await Promise.all([
+      executeMobileScript(sessionId, "mobile: getCurrentPackage", []),
+      executeMobileScript(sessionId, "mobile: getCurrentActivity", []).catch(() => void 0)
+    ]);
+    const pkg2 = readExecuteStringValue(packageResult);
+    if (!pkg2) return null;
+    const activity = normalizeAndroidActivity(readExecuteStringValue(activityResult), pkg2);
+    return {
+      platform: platform3,
+      bundleId: pkg2,
+      ...activity ? { activity } : {},
+      screenHash: "foreground"
+    };
+  }
+  const infoResult = await executeMobileScript(sessionId, "mobile: activeAppInfo", []);
+  const bundleId = readActiveBundleId(infoResult);
+  if (!bundleId) return null;
+  return { platform: platform3, bundleId, screenHash: "foreground" };
+}
+async function activateTargetApp(sessionId, platform3, appId) {
+  const args = platform3 === "IOS" ? [{ bundleId: appId }] : [{ appId }];
+  await executeMobileScript(sessionId, "mobile: activateApp", args);
+}
+async function restoreTargetAppIfExternal(sessionId, target, log2, source, failOnExternal) {
+  let boundary = null;
+  try {
+    const signal = await readForegroundScreenSignal(sessionId, target.platform);
+    boundary = signal ? (0, import_runner_core8.classifyMobileScreenBoundary)(signal, target.appId, target.platform) : null;
+  } catch (err) {
+    log2(`  App boundary check skipped after ${source}: ${err instanceof Error ? err.message : String(err)}`);
+    return;
+  }
+  if (!boundary || (0, import_runner_core8.isTargetLikeMobileBoundary)(boundary) || boundary.kind === "transient_external") {
+    return;
+  }
+  const message = `Foreground app changed to ${boundary.owner}, outside target app ${boundary.targetAppId}`;
+  log2(`  ${message}; activating target app.`);
+  try {
+    await activateTargetApp(sessionId, target.platform, target.appId);
+  } catch (err) {
+    log2(`  Could not reactivate ${target.appId}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (failOnExternal) {
+    throw new Error(`${message}; relaunched target app and failed the step so mobile tests do not continue in another app.`);
+  }
+}
 async function deleteSession(sessionId) {
   try {
     await wdRequest(`/session/${sessionId}`, { method: "DELETE" });
@@ -325714,6 +327922,29 @@ async function getActiveElementId(sessionId) {
     return null;
   }
 }
+async function sendKeysToFocusedInput(sessionId, value) {
+  await wdRequest(`/session/${sessionId}/keys`, {
+    method: "POST",
+    body: JSON.stringify({ text: value, value: Array.from(value) })
+  });
+}
+function shouldAbortAfterStepFailure(action) {
+  switch (action) {
+    case "launchApp":
+    case "tap":
+    case "type":
+    case "clear":
+    case "swipe":
+    case "scroll":
+    case "back":
+    case "home":
+    case "waitForElement":
+      return true;
+    case "assertVisible":
+    case "assertText":
+      return false;
+  }
+}
 async function executeTap(sessionId, step) {
   const bounds = boundsFromStep(step);
   if (step.target) {
@@ -325735,8 +327966,10 @@ async function executeTap(sessionId, step) {
 }
 async function executeType(sessionId, step) {
   if (step.value === void 0 || step.value === null || step.value === "") return;
+  const value = String(step.value);
   const bounds = boundsFromStep(step);
   let elementId = null;
+  let tappedBounds = false;
   if (step.target) {
     try {
       elementId = await findElement(sessionId, step.target, readStepTimeout(step));
@@ -325746,19 +327979,33 @@ async function executeType(sessionId, step) {
   }
   if (!elementId && bounds) {
     await tapCoordinates(sessionId, bounds);
+    tappedBounds = true;
     await new Promise((resolve) => setTimeout(resolve, MOBILE_FOCUS_SETTLE_MS));
     elementId = await getActiveElementId(sessionId);
   }
   if (!elementId) {
     elementId = await getActiveElementId(sessionId);
   }
-  if (!elementId) {
-    throw new Error("TYPE step could not resolve a target or focused element");
+  if (elementId) {
+    try {
+      await wdRequest(`/session/${sessionId}/element/${elementId}/value`, {
+        method: "POST",
+        body: JSON.stringify({ text: value })
+      });
+      return;
+    } catch (error2) {
+      if (!bounds) throw error2;
+    }
   }
-  await wdRequest(`/session/${sessionId}/element/${elementId}/value`, {
-    method: "POST",
-    body: JSON.stringify({ text: step.value })
-  });
+  if (bounds) {
+    if (!tappedBounds) {
+      await tapCoordinates(sessionId, bounds);
+      await new Promise((resolve) => setTimeout(resolve, MOBILE_FOCUS_SETTLE_MS));
+    }
+    await sendKeysToFocusedInput(sessionId, value);
+    return;
+  }
+  throw new Error("TYPE step could not resolve a target or focused element");
 }
 async function executeClear(sessionId, step) {
   const bounds = boundsFromStep(step);
@@ -325862,7 +328109,24 @@ async function executeMobileTest(options) {
   const startTime = Date.now();
   const stepResults = [];
   const screenshots = [];
+  let apiCalls = [];
   let sessionId = null;
+  let capture = null;
+  let captureStopped = false;
+  const stopCapture = async () => {
+    if (!capture || captureStopped) return apiCalls;
+    captureStopped = true;
+    try {
+      const captured = await capture.stop();
+      apiCalls = captured.map((call) => ({
+        ...call,
+        pageUrl: call.pageUrl ?? `mobile-test:${options.target.appId}`
+      }));
+    } catch (err) {
+      log2(`[mobile-net] capture stop failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return apiCalls;
+  };
   try {
     log2("Checking Appium server health...");
     const health = await checkAppiumHealth();
@@ -325890,6 +328154,21 @@ async function executeMobileTest(options) {
       selectedDevice = matchingDevices[0];
     }
     log2(`Using device: ${selectedDevice.name} (${selectedDevice.id})`);
+    try {
+      capture = await startMobileNetworkCapture({
+        platform: options.target.platform,
+        deviceId: selectedDevice.id,
+        appId: options.target.appId,
+        isPhysical: selectedDevice.isPhysical,
+        onLog: (line) => log2(line)
+      });
+      const caps = capture.getCapabilities();
+      if (!caps.intercepting) {
+        log2(`[mobile-net] HTTPS interception unavailable: ${caps.reason ?? "unknown reason"} (continuing - plaintext/metadata only)`);
+      }
+    } catch (err) {
+      log2(`[mobile-net] capture unavailable: ${err instanceof Error ? err.message : String(err)} (continuing without network log)`);
+    }
     if (selectedDevice.installedApps && selectedDevice.installedApps.length > 0) {
       if (!selectedDevice.installedApps.includes(options.target.appId)) {
         throw new Error(
@@ -325930,6 +328209,7 @@ async function executeMobileTest(options) {
         log2(`  \u2717 Deep link failed: ${err instanceof Error ? err.message : String(err)}`);
       }
     }
+    await restoreTargetAppIfExternal(sessionId, options.target, log2, "session start", false);
     let environmental = null;
     for (const step of options.steps) {
       const stepStart = Date.now();
@@ -325937,6 +328217,7 @@ async function executeMobileTest(options) {
       let status = "passed";
       let stepError;
       try {
+        await restoreTargetAppIfExternal(sessionId, options.target, log2, `step ${step.order} pre-check`, false);
         switch (step.action) {
           case "launchApp":
             log2("  App launched (handled by session creation)");
@@ -325976,6 +328257,7 @@ async function executeMobileTest(options) {
             break;
           }
         }
+        await restoreTargetAppIfExternal(sessionId, options.target, log2, `step ${step.order} (${step.action})`, true);
       } catch (err) {
         status = "failed";
         stepError = err instanceof Error ? err.message : String(err);
@@ -325996,13 +328278,19 @@ async function executeMobileTest(options) {
         log2(`Aborting remaining steps \u2014 Appium session is no longer usable: ${environmental}`);
         break;
       }
+      if (status === "failed" && shouldAbortAfterStepFailure(step.action)) {
+        log2(`Aborting remaining steps \u2014 ${step.action} failed, so downstream mobile steps are no longer reliable.`);
+        break;
+      }
     }
     const allPassed = !environmental && stepResults.every((r) => r.status === "passed" || r.status === "skipped");
     const firstError = environmental ?? (stepResults.find((r) => r.status === "failed")?.error ?? null);
+    await stopCapture();
     return {
       passed: allPassed,
       stepResults,
       screenshots,
+      apiCalls,
       logs: logLines.join("\n"),
       error: firstError,
       duration: Date.now() - startTime,
@@ -326011,10 +328299,12 @@ async function executeMobileTest(options) {
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
     log2(`Fatal error: ${errorMsg}`);
+    await stopCapture();
     return {
       passed: false,
       stepResults,
       screenshots,
+      apiCalls,
       logs: logLines.join("\n"),
       error: errorMsg,
       duration: Date.now() - startTime,
@@ -326024,6 +328314,7 @@ async function executeMobileTest(options) {
       environmental: errorMsg
     };
   } finally {
+    await stopCapture();
     if (sessionId) {
       log2("Tearing down Appium session...");
       await deleteSession(sessionId);
@@ -326031,7 +328322,7 @@ async function executeMobileTest(options) {
     }
   }
 }
-async function createMobileDiscoverySession(target) {
+async function createMobileDiscoverySession(target, options) {
   const health = await checkAppiumHealth();
   if (!health.ok) {
     await startAppiumServer();
@@ -326058,6 +328349,12 @@ async function createMobileDiscoverySession(target) {
       `App ${target.appId} not installed on ${selectedDevice.name}. Install it first.`
     );
   }
+  await options?.onDeviceSelected?.({
+    deviceId: selectedDevice.id,
+    name: selectedDevice.name,
+    isPhysical: selectedDevice.isPhysical === true,
+    platformVersion: selectedDevice.platformVersion
+  });
   const sessionId = await createSession({
     appId: target.appId,
     platform: target.platform,
@@ -326088,10 +328385,10 @@ async function createMobileDiscoverySession(target) {
 
 // src/services/mobile-bridge.ts
 import { createServer } from "http";
-import { execFileSync as execFileSync3 } from "child_process";
+import { execFileSync as execFileSync4 } from "child_process";
 import { randomBytes, timingSafeEqual } from "crypto";
 import { homedir as homedir2 } from "os";
-import { join as join2, dirname } from "path";
+import { join as join3, dirname } from "path";
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, unlinkSync as unlinkSync2, mkdirSync as mkdirSync2 } from "fs";
 init_dist();
 
@@ -326380,7 +328677,7 @@ async function getWindowSize3() {
 }
 var BRIDGE_PROCESS_MARKER = "validateqa-mobile-bridge";
 var BRIDGE_PORT = MOBILE_BRIDGE_PORT2;
-var BRIDGE_PID_FILE = join2(homedir2(), ".validate.qa", "mobile-bridge.pid");
+var BRIDGE_PID_FILE = join3(homedir2(), ".validate.qa", "mobile-bridge.pid");
 function readBridgePidFile() {
   try {
     const raw = readFileSync2(BRIDGE_PID_FILE, "utf-8").trim();
@@ -326407,19 +328704,19 @@ function killStaleBridge() {
   const pid = readBridgePidFile();
   if (!pid) return;
   try {
-    execFileSync3("kill", ["-0", String(pid)], { stdio: "ignore" });
+    execFileSync4("kill", ["-0", String(pid)], { stdio: "ignore" });
   } catch {
     clearBridgePidFile();
     return;
   }
   try {
-    const pidsOnPort = execFileSync3("lsof", ["-ti", `:${BRIDGE_PORT}`], { encoding: "utf-8" }).trim();
+    const pidsOnPort = execFileSync4("lsof", ["-ti", `:${BRIDGE_PORT}`], { encoding: "utf-8" }).trim();
     const pidList = pidsOnPort.split("\n").filter(Boolean);
     if (!pidList.includes(String(pid))) {
       return;
     }
-    execFileSync3("kill", ["-9", String(pid)], { stdio: "ignore" });
-    execFileSync3("sleep", ["1"], { stdio: "ignore" });
+    execFileSync4("kill", ["-9", String(pid)], { stdio: "ignore" });
+    execFileSync4("sleep", ["1"], { stdio: "ignore" });
   } catch {
   } finally {
     clearBridgePidFile();
@@ -327250,7 +329547,7 @@ function detachMirrorSession(sessionId) {
 }
 
 // src/services/mobile/mobile-bridge-driver.ts
-var import_runner_core7 = __toESM(require_dist2());
+var import_runner_core9 = __toESM(require_dist2());
 init_dist();
 var APPIUM_SESSION_ID_PATTERN2 = /^[a-f0-9-]{1,64}$/i;
 function readStringValue(result) {
@@ -327260,6 +329557,15 @@ function readStringValue(result) {
   }
   return void 0;
 }
+function normalizeAndroidActivity2(activity, pkg2) {
+  const trimmed = activity?.trim();
+  if (!trimmed) return void 0;
+  const packageName = pkg2?.trim();
+  if (!packageName) return trimmed;
+  if (trimmed.startsWith(".")) return `${packageName}${trimmed}`;
+  if (!trimmed.includes(".")) return `${packageName}.${trimmed}`;
+  return trimmed;
+}
 var MobileBridgeDriver = class {
   sessionId;
   platform;
@@ -327286,6 +329592,38 @@ var MobileBridgeDriver = class {
   appLifecycleArgs() {
     return this.platform === "ANDROID" ? { appId: this.appId } : { bundleId: this.appId };
   }
+  baseScreenSignal(source) {
+    const parsed = (0, import_runner_core9.parseMobileSource)(source, this.platform);
+    return {
+      platform: this.platform,
+      screenHash: parsed.screenSignal.screenHash,
+      ...parsed.screenSignal.activity ? { activity: parsed.screenSignal.activity } : {},
+      ...parsed.screenSignal.bundleId ? { bundleId: parsed.screenSignal.bundleId } : {}
+    };
+  }
+  async enrichScreenSignal(source) {
+    const signal = this.baseScreenSignal(source);
+    try {
+      if (this.platform === "ANDROID") {
+        const [activityRes, packageRes] = await Promise.all([
+          this.executeScript("mobile: getCurrentActivity", []).catch(() => void 0),
+          this.executeScript("mobile: getCurrentPackage", []).catch(() => void 0)
+        ]);
+        const activity = readStringValue(activityRes);
+        const pkg2 = readStringValue(packageRes);
+        if (pkg2) signal.bundleId = pkg2;
+        const normalizedActivity = normalizeAndroidActivity2(activity, pkg2);
+        if (normalizedActivity) signal.activity = normalizedActivity;
+      } else {
+        const infoRes = await this.executeScript("mobile: activeAppInfo", []).catch(() => void 0);
+        const bundleId = readActiveBundleId2(infoRes);
+        if (bundleId) signal.bundleId = bundleId;
+      }
+    } catch {
+    }
+    if (!signal.bundleId) signal.bundleId = this.appId;
+    return signal;
+  }
   /**
    * Run a `mobile:` script via execute/sync. Used by the NEW lifecycle
    * primitives (terminateApp/activateApp/deepLink/getCurrentActivity) that have
@@ -327300,9 +329638,7 @@ var MobileBridgeDriver = class {
   // ── Observation ────────────────────────────────────────
   /**
    * One round-trip observation: UI-tree XML + base64 screenshot + window size,
-   * plus a best-effort screen signal derived from the parsed XML (cheap — no
-   * extra device round-trip; the activity/bundleId enrichment is left to
-   * getScreenSignal()).
+   * plus a best-effort screen signal enriched with the foreground app identity.
    */
   async snapshot() {
     const [xml, screenshot, windowSize] = await Promise.all([
@@ -327311,10 +329647,7 @@ var MobileBridgeDriver = class {
       getWindowSize2(this.sessionPath)
     ]);
     const source = xml ?? "";
-    const screenSignal = {
-      platform: this.platform,
-      screenHash: (0, import_runner_core7.parseMobileSource)(source, this.platform).screenSignal.screenHash
-    };
+    const screenSignal = await this.enrichScreenSignal(source);
     return {
       xml: source,
       screenshot,
@@ -327343,7 +329676,8 @@ var MobileBridgeDriver = class {
       getScreenshot(this.sessionPath),
       getPageSource(this.sessionPath)
     ]);
-    return { ok: true, screenshot, source };
+    const screenSignal = await this.enrichScreenSignal(source ?? "");
+    return { ok: true, screenshot, source, screenSignal };
   }
   // ── Action primitives (1:1 with the bridge handleAction verbs) ──
   /** Center-tap the given bounds (coordinate-only; the loop always supplies bounds). */
@@ -327421,30 +329755,10 @@ var MobileBridgeDriver = class {
    */
   async getScreenSignal() {
     const source = await getPageSource(this.sessionPath) ?? "";
-    const screenHash = (0, import_runner_core7.parseMobileSource)(source, this.platform).screenSignal.screenHash;
-    const signal = { platform: this.platform, screenHash };
-    try {
-      if (this.platform === "ANDROID") {
-        const [activityRes, packageRes] = await Promise.all([
-          this.executeScript("mobile: getCurrentActivity", []).catch(() => void 0),
-          this.executeScript("mobile: getCurrentPackage", []).catch(() => void 0)
-        ]);
-        const activity = readStringValue(activityRes);
-        const pkg2 = readStringValue(packageRes);
-        if (activity) signal.activity = activity;
-        signal.bundleId = pkg2 ?? this.appId;
-      } else {
-        const infoRes = await this.executeScript("mobile: activeAppInfo", []).catch(() => void 0);
-        const bundleId = readActiveBundleId(infoRes);
-        signal.bundleId = bundleId ?? this.appId;
-      }
-    } catch {
-      if (!signal.bundleId) signal.bundleId = this.appId;
-    }
-    return signal;
+    return this.enrichScreenSignal(source);
   }
 };
-function readActiveBundleId(result) {
+function readActiveBundleId2(result) {
   if (result && typeof result === "object" && "value" in result) {
     const value = result.value;
     if (value && typeof value === "object" && "bundleId" in value) {
@@ -327455,617 +329769,6 @@ function readActiveBundleId(result) {
   return void 0;
 }
 
-// src/services/mobile/mobile-network-capture.ts
-var import_runner_core8 = __toESM(require_dist2());
-import { execFile, execFileSync as execFileSync4 } from "child_process";
-import { randomUUID } from "crypto";
-import { mkdtemp, rm, writeFile, readFile, readdir, mkdir, unlink } from "fs/promises";
-import { tmpdir, networkInterfaces } from "os";
-import { join as join3 } from "path";
-import { promisify } from "util";
-import {
-  getLocal,
-  generateCACertificate
-} from "mockttp";
-var execFileAsync = promisify(execFile);
-var MAX_CALLS = 1e3;
-var MAX_BODY_CAPTURE_BYTES = 64 * 1024;
-var DEVICE_CMD_TIMEOUT_MS = 15e3;
-var CA_KEY_BITS = 2048;
-var ANDROID_EMULATOR_HOST_LOOPBACK = "10.0.2.2";
-var PENDING_CLEANUP_DIR = join3(tmpdir(), "validateqa-mobile-capture-pending");
-function rawHeadersToPairs(rawHeaders) {
-  return rawHeaders.map(([name, value]) => ({ name, value }));
-}
-function headerValue(pairs, name) {
-  const lower = name.toLowerCase();
-  return pairs.find((h) => h.name.toLowerCase() === lower)?.value;
-}
-function resolveHostIp() {
-  const ifaces = networkInterfaces();
-  for (const addrs of Object.values(ifaces)) {
-    if (!addrs) continue;
-    for (const addr of addrs) {
-      if (addr.family === "IPv4" && !addr.internal) return addr.address;
-    }
-  }
-  return "127.0.0.1";
-}
-function resolveProxyHostForDevice(platform3, isPhysical) {
-  if (platform3 === "ANDROID" && !isPhysical) return ANDROID_EMULATOR_HOST_LOOPBACK;
-  if (platform3 === "IOS" && !isPhysical) return "127.0.0.1";
-  return resolveHostIp();
-}
-function normalizeRemoteAddress(addr) {
-  if (!addr) return "";
-  return addr.startsWith("::ffff:") ? addr.slice("::ffff:".length) : addr;
-}
-function isLoopbackAddress(addr) {
-  return addr === "127.0.0.1" || addr.startsWith("127.") || addr === "::1" || addr === "";
-}
-function isPrivateAddress(addr) {
-  if (/^10\./.test(addr)) return true;
-  if (/^192\.168\./.test(addr)) return true;
-  if (/^172\.(1[6-9]|2\d|3[01])\./.test(addr)) return true;
-  if (/^169\.254\./.test(addr)) return true;
-  const lower = addr.toLowerCase();
-  if (lower.startsWith("fe80:")) return true;
-  if (lower.startsWith("fc") || lower.startsWith("fd")) return true;
-  return false;
-}
-function isAllowedProxyPeer(remoteAddress, isPhysical) {
-  const addr = normalizeRemoteAddress(remoteAddress);
-  if (isLoopbackAddress(addr)) return true;
-  return isPhysical && isPrivateAddress(addr);
-}
-function installSourceIpGuard(server3, isPhysical, onLog) {
-  const underlying = server3.server;
-  if (!underlying || typeof underlying.on !== "function") {
-    onLog?.(
-      "[mobile-net] WARNING: could not attach source-IP guard to the proxy listener; the port is bound to all interfaces \u2014 firewall it to the device subnet."
-    );
-    return;
-  }
-  underlying.on("connection", (socket) => {
-    if (!isAllowedProxyPeer(socket.remoteAddress, isPhysical)) {
-      onLog?.(`[mobile-net] rejected proxy connection from disallowed source ${socket.remoteAddress}`);
-      socket.destroy();
-    }
-  });
-}
-function isTextish(contentType) {
-  if (!contentType) return false;
-  return /json|text|xml|graphql|html|csv|javascript|urlencoded/i.test(contentType);
-}
-async function readBodyText(body, contentType) {
-  if (!isTextish(contentType)) return void 0;
-  try {
-    const decoded = await body.getDecodedBuffer();
-    if (!decoded || decoded.length === 0) return void 0;
-    if (decoded.length > MAX_BODY_CAPTURE_BYTES) {
-      return decoded.subarray(0, MAX_BODY_CAPTURE_BYTES).toString("utf-8");
-    }
-    return decoded.toString("utf-8");
-  } catch {
-    return void 0;
-  }
-}
-var MitmProxy = class {
-  constructor(caKeyPem, caCertPem, isPhysical, onLog) {
-    this.caKeyPem = caKeyPem;
-    this.caCertPem = caCertPem;
-    this.isPhysical = isPhysical;
-    this.onLog = onLog;
-  }
-  server = null;
-  inFlight = /* @__PURE__ */ new Map();
-  calls = [];
-  dropped = 0;
-  /** Flips true once any HTTPS response is successfully MITM-ed. */
-  httpsIntercepted = false;
-  /** Best-known reason interception is unavailable, refined by TLS failures. */
-  tlsFailureReason = null;
-  /** Start listening; resolves with the actual bound port. */
-  async listen(preferredPort) {
-    const server3 = getLocal({
-      // Our generated CA — mockttp mints per-host leaf certs signed by it.
-      https: { key: this.caKeyPem, cert: this.caCertPem },
-      // HTTP/2 with HTTP/1.1 fallback; mobile clients negotiate either.
-      http2: "fallback",
-      // Keep the proxy quiet unless explicitly debugging.
-      recordTraffic: false
-    });
-    await server3.forAnyRequest().thenPassThrough({ ignoreHostHttpsErrors: true });
-    await server3.on("request", (req) => this.onRequest(req));
-    await server3.on("response", (res) => this.onResponse(res));
-    await server3.on("tls-client-error", (failure) => this.onTlsClientError(failure));
-    await (preferredPort > 0 ? server3.start(preferredPort) : server3.start());
-    installSourceIpGuard(server3, this.isPhysical, this.onLog);
-    this.server = server3;
-    return server3.port;
-  }
-  /** Captured calls, finalized through the shared redaction constructor. */
-  finalize() {
-    return this.calls.map(
-      (c) => (0, import_runner_core8.buildApiCallSummary)({
-        method: c.method,
-        url: c.url,
-        status: c.status,
-        durationMs: c.durationMs,
-        authHeader: c.authHeader,
-        cookieHeader: c.cookieHeader,
-        requestContentType: c.requestContentType,
-        responseContentType: c.responseContentType,
-        respHeaders: c.respHeaders,
-        reqBodyText: c.reqBodyText,
-        respBodyText: c.respBodyText,
-        responseSize: c.responseSize,
-        timestamp: c.startedAt,
-        testPhase: "UNKNOWN"
-      })
-    );
-  }
-  /** True once at least one HTTPS exchange was decrypted (CA trusted). */
-  get isIntercepting() {
-    return this.httpsIntercepted;
-  }
-  /** A precise reason interception is (still) unavailable, or null if it works. */
-  get interceptionReason() {
-    if (this.httpsIntercepted) return null;
-    return this.tlsFailureReason;
-  }
-  async close() {
-    const server3 = this.server;
-    this.server = null;
-    this.inFlight.clear();
-    if (!server3) return;
-    try {
-      await server3.stop();
-    } catch (err) {
-      this.onLog?.(`[mobile-net] proxy stop error (ignored): ${errMsg(err)}`);
-    }
-    this.onLog?.(
-      `[mobile-net] proxy closed: ${this.calls.length} calls captured` + (this.dropped > 0 ? ` (${this.dropped} dropped over cap)` : "")
-    );
-  }
-  // ── request → buffer by id ────────────────────────────────────────────────
-  async onRequest(req) {
-    try {
-      const reqHeaders = rawHeadersToPairs(req.rawHeaders);
-      const requestContentType = headerValue(reqHeaders, "content-type");
-      const isHttps = isHttpsUrl(req.url);
-      const reqBodyText = (0, import_runner_core8.isApiCall)(req.url, requestContentType) ? await readBodyText(req.body, requestContentType) : void 0;
-      this.inFlight.set(req.id, {
-        method: req.method,
-        url: req.url,
-        startedAt: req.timingEvents.startTime,
-        reqHeaders,
-        requestContentType,
-        authHeader: headerValue(reqHeaders, "authorization"),
-        cookieHeader: headerValue(reqHeaders, "cookie"),
-        reqBodyText,
-        isHttps
-      });
-    } catch (err) {
-      this.onLog?.(`[mobile-net] request capture error (ignored): ${errMsg(err)}`);
-    }
-  }
-  // ── response → finalize the matched request ───────────────────────────────
-  async onResponse(res) {
-    const pending = this.inFlight.get(res.id);
-    if (!pending) return;
-    this.inFlight.delete(res.id);
-    try {
-      if (pending.isHttps && !this.httpsIntercepted) {
-        this.httpsIntercepted = true;
-        this.tlsFailureReason = null;
-        this.onLog?.("[mobile-net] HTTPS interception confirmed (CA trusted; bodies decrypted).");
-      }
-      const respHeaders = rawHeadersToPairs(res.rawHeaders);
-      const responseContentType = headerValue(respHeaders, "content-type");
-      const api = (0, import_runner_core8.isApiCall)(pending.url, responseContentType);
-      if (!api && (0, import_runner_core8.isStaticAssetByExt)(pending.url)) return;
-      if (this.calls.length >= MAX_CALLS) {
-        this.dropped++;
-        return;
-      }
-      const respBodyText = api ? await readBodyText(res.body, responseContentType) : void 0;
-      const responseSize = await measureBody(res.body);
-      const durationMs = computeDuration(pending.startedAt, res);
-      this.calls.push({
-        method: pending.method,
-        url: pending.url,
-        status: res.statusCode,
-        startedAt: pending.startedAt,
-        durationMs,
-        reqHeaders: pending.reqHeaders,
-        respHeaders,
-        requestContentType: pending.requestContentType,
-        responseContentType,
-        authHeader: pending.authHeader,
-        cookieHeader: pending.cookieHeader,
-        reqBodyText: pending.reqBodyText,
-        respBodyText,
-        responseSize,
-        intercepted: true
-      });
-    } catch (err) {
-      this.onLog?.(`[mobile-net] response capture error (ignored): ${errMsg(err)}`);
-    }
-  }
-  // ── tls-client-error → record WHY interception failed ─────────────────────
-  onTlsClientError(failure) {
-    if (this.httpsIntercepted) return;
-    const host = failure.destination?.hostname ?? failure.tlsMetadata.sniHostname ?? "unknown host";
-    let reason;
-    switch (failure.failureCause) {
-      case "cert-rejected":
-        reason = `TLS handshake to ${host} rejected our certificate: the device does not trust the validate.qa CA, so HTTPS bodies cannot be decrypted (plaintext HTTP still captured). Install + trust the CA at caCertPath to enable interception.`;
-        break;
-      case "closed":
-      case "reset":
-        reason = `TLS handshake to ${host} was dropped after our certificate was offered \u2014 this is the signature of certificate pinning in the app. HTTPS bodies for pinned hosts cannot be decrypted (plaintext HTTP and connect-level host metadata still captured).`;
-        break;
-      case "no-shared-cipher":
-        reason = `TLS handshake to ${host} failed: no shared cipher with the client.`;
-        break;
-      case "handshake-timeout":
-        reason = `TLS handshake to ${host} timed out before completing.`;
-        break;
-      default:
-        reason = `TLS handshake to ${host} failed (${failure.failureCause}); HTTPS not intercepted for it.`;
-    }
-    if (!this.tlsFailureReason || failure.failureCause === "cert-rejected" || failure.failureCause === "closed" || failure.failureCause === "reset") {
-      this.tlsFailureReason = reason;
-    }
-    this.onLog?.(`[mobile-net] ${reason}`);
-  }
-};
-function isHttpsUrl(url) {
-  try {
-    return new URL(url).protocol === "https:";
-  } catch {
-    return false;
-  }
-}
-async function measureBody(body) {
-  try {
-    const decoded = await body.getDecodedBuffer();
-    return decoded ? decoded.length : 0;
-  } catch {
-    return 0;
-  }
-}
-function computeDuration(startedAt, res) {
-  const sent = res.timingEvents.responseSentTimestamp;
-  const start = res.timingEvents.startTimestamp;
-  if (typeof sent === "number" && typeof start === "number" && sent >= start) {
-    return Math.round(sent - start);
-  }
-  const elapsed = Date.now() - startedAt;
-  return elapsed > 0 ? elapsed : 0;
-}
-async function generateCaCert(dir, onLog) {
-  try {
-    const { key, cert } = await generateCACertificate({
-      subject: {
-        commonName: "validate.qa Mobile Capture CA",
-        organizationName: "validate.qa"
-      },
-      bits: CA_KEY_BITS
-      // mockttp's generated CA carries its own (multi-year) validity window; we
-      // rely on stop() to remove the cert from the device promptly after the run
-      // rather than on a short expiry.
-    });
-    const caCertPath = join3(dir, "validateqa-mobile-ca.pem");
-    await writeFile(caCertPath, cert, "utf-8");
-    return { caCertPath, caKeyPem: key, caCertPem: cert };
-  } catch (err) {
-    onLog?.(`[mobile-net] CA generation failed; running plaintext-only: ${errMsg(err)}`);
-    return null;
-  }
-}
-async function androidReadProxy(deviceId) {
-  try {
-    const { stdout } = await execFileAsync(
-      "adb",
-      ["-s", deviceId, "shell", "settings", "get", "global", "http_proxy"],
-      { timeout: DEVICE_CMD_TIMEOUT_MS }
-    );
-    const value = stdout.trim();
-    return value === "" || value === "null" ? null : value;
-  } catch {
-    return null;
-  }
-}
-async function androidSetProxy(deviceId, hostPort, onLog) {
-  try {
-    await execFileAsync(
-      "adb",
-      ["-s", deviceId, "shell", "settings", "put", "global", "http_proxy", hostPort],
-      { timeout: DEVICE_CMD_TIMEOUT_MS }
-    );
-    return true;
-  } catch (err) {
-    onLog?.(`[mobile-net] adb set http_proxy failed: ${errMsg(err)}`);
-    return false;
-  }
-}
-async function androidClearProxy(deviceId, originalProxy, onLog) {
-  const restoreValue = originalProxy && originalProxy.length > 0 ? originalProxy : ":0";
-  try {
-    await execFileAsync(
-      "adb",
-      ["-s", deviceId, "shell", "settings", "put", "global", "http_proxy", restoreValue],
-      { timeout: DEVICE_CMD_TIMEOUT_MS }
-    );
-  } catch (err) {
-    onLog?.(`[mobile-net] adb restore http_proxy failed: ${errMsg(err)}`);
-  }
-}
-async function androidInstallCa(deviceId, caCertPath) {
-  const devicePath = "/sdcard/validateqa-mobile-ca.pem";
-  try {
-    await execFileAsync("adb", ["-s", deviceId, "push", caCertPath, devicePath], {
-      timeout: DEVICE_CMD_TIMEOUT_MS
-    });
-    return {
-      installed: false,
-      note: "CA pushed to /sdcard but NOT auto-trusted: Android 7+ apps must opt into user CAs (network_security_config), and the system store requires a rooted/writable image. HTTPS bodies decrypt only for apps that trust user CAs; pinned apps never decrypt."
-    };
-  } catch (err) {
-    return { installed: false, note: `CA push failed: ${errMsg(err)}` };
-  }
-}
-async function androidRemoveCa(deviceId, onLog) {
-  try {
-    await execFileAsync(
-      "adb",
-      ["-s", deviceId, "shell", "rm", "-f", "/sdcard/validateqa-mobile-ca.pem"],
-      { timeout: DEVICE_CMD_TIMEOUT_MS }
-    );
-  } catch (err) {
-    onLog?.(`[mobile-net] adb remove CA failed: ${errMsg(err)}`);
-  }
-}
-async function iosSimTrustCa(deviceId, caCertPath) {
-  try {
-    await execFileAsync("xcrun", ["simctl", "keychain", deviceId, "add-root-cert", caCertPath], {
-      timeout: DEVICE_CMD_TIMEOUT_MS
-    });
-    return {
-      trusted: true,
-      note: "CA added to simulator keychain (add-root-cert). NOTE: the simulator has no per-app HTTP proxy setting controllable via simctl \u2014 it shares the host network, so only traffic that actually routes through the proxy is intercepted; pinned apps still never decrypt."
-    };
-  } catch (err) {
-    return { trusted: false, note: `simctl add-root-cert failed: ${errMsg(err)}` };
-  }
-}
-async function iosSimRemoveCa(deviceId, onLog) {
-  if (process.env.VALIDATEQA_MOBILE_SIM_KEYCHAIN_RESET === "1") {
-    try {
-      await execFileAsync("xcrun", ["simctl", "keychain", deviceId, "reset"], {
-        timeout: DEVICE_CMD_TIMEOUT_MS
-      });
-      onLog?.(`[mobile-net] simctl keychain reset run for ${deviceId} (opt-in; cleared ALL sim certs).`);
-    } catch (err) {
-      onLog?.(`[mobile-net] simctl keychain reset failed: ${errMsg(err)}`);
-    }
-    return;
-  }
-  onLog?.(
-    `[mobile-net] NOTE: the validate.qa capture CA remains TRUSTED in simulator ${deviceId}. simctl has no scoped remove (only a full keychain reset that wipes ALL certs), so we leave the single CA in place. Use a throwaway simulator, or set VALIDATEQA_MOBILE_SIM_KEYCHAIN_RESET=1 to reset the whole sim keychain on teardown.`
-  );
-}
-function errMsg(err) {
-  return err instanceof Error ? err.message : String(err);
-}
-var activeCleanups = /* @__PURE__ */ new Map();
-var exitHandlersInstalled = false;
-function markerPath(sessionKey) {
-  return join3(PENDING_CLEANUP_DIR, `${sessionKey}.json`);
-}
-async function writePendingCleanup(sessionKey, marker) {
-  try {
-    await mkdir(PENDING_CLEANUP_DIR, { recursive: true });
-    await writeFile(markerPath(sessionKey), JSON.stringify(marker), "utf-8");
-  } catch {
-  }
-}
-async function removePendingCleanup(sessionKey) {
-  try {
-    await unlink(markerPath(sessionKey));
-  } catch {
-  }
-}
-function restoreDeviceSync(marker, onLog) {
-  const run2 = (args) => {
-    try {
-      execFileSync4("adb", args, { timeout: DEVICE_CMD_TIMEOUT_MS, stdio: "ignore" });
-    } catch {
-    }
-  };
-  if (marker.platform === "ANDROID") {
-    if (marker.proxySet) {
-      const restoreValue = marker.originalProxy && marker.originalProxy.length > 0 ? marker.originalProxy : ":0";
-      run2(["-s", marker.deviceId, "shell", "settings", "put", "global", "http_proxy", restoreValue]);
-    }
-    if (marker.caInstalledOnDevice) {
-      run2(["-s", marker.deviceId, "shell", "rm", "-f", "/sdcard/validateqa-mobile-ca.pem"]);
-    }
-  }
-  onLog?.(`[mobile-net] restored device ${marker.deviceId} from pending-cleanup marker.`);
-}
-async function reconcilePendingCleanups(onLog) {
-  let files;
-  try {
-    files = await readdir(PENDING_CLEANUP_DIR);
-  } catch {
-    return;
-  }
-  for (const file of files) {
-    if (!file.endsWith(".json")) continue;
-    const full = join3(PENDING_CLEANUP_DIR, file);
-    try {
-      const raw = await readFile(full, "utf-8");
-      const marker = JSON.parse(raw);
-      if (marker && typeof marker.deviceId === "string" && marker.platform) {
-        onLog?.(`[mobile-net] reconciling orphaned capture cleanup for ${marker.deviceId}.`);
-        restoreDeviceSync(marker, onLog);
-      }
-    } catch {
-    }
-    try {
-      await unlink(full);
-    } catch {
-    }
-  }
-}
-function ensureExitHandlers() {
-  if (exitHandlersInstalled) return;
-  exitHandlersInstalled = true;
-  const drain = () => {
-    for (const marker of activeCleanups.values()) {
-      restoreDeviceSync(marker);
-    }
-  };
-  process.on("beforeExit", drain);
-  process.on("exit", drain);
-  for (const signal of ["SIGTERM", "SIGINT"]) {
-    process.on(signal, () => {
-      drain();
-      process.removeAllListeners(signal);
-      process.kill(process.pid, signal);
-    });
-  }
-}
-async function startMobileNetworkCapture(options) {
-  const { platform: platform3, deviceId, isPhysical = false, preferredPort = 0, onLog } = options;
-  await reconcilePendingCleanups(onLog);
-  ensureExitHandlers();
-  const sessionKey = randomUUID();
-  const originalProxy = platform3 === "ANDROID" ? await androidReadProxy(deviceId) : null;
-  let tmpDir = null;
-  let caCertPath = null;
-  let caKeyPem = null;
-  let caCertPem = null;
-  try {
-    tmpDir = await mkdtemp(join3(tmpdir(), "validateqa-mobile-ca-"));
-    const ca = await generateCaCert(tmpDir, onLog);
-    if (ca) {
-      caCertPath = ca.caCertPath;
-      caKeyPem = ca.caKeyPem;
-      caCertPem = ca.caCertPem;
-    }
-  } catch (err) {
-    onLog?.(`[mobile-net] CA setup degraded: ${errMsg(err)}`);
-  }
-  if (!caKeyPem || !caCertPem) {
-    try {
-      const fallback = await generateCACertificate();
-      caKeyPem = fallback.key;
-      caCertPem = fallback.cert;
-    } catch (err) {
-      onLog?.(`[mobile-net] fatal CA failure, cannot start proxy: ${errMsg(err)}`);
-      if (tmpDir) {
-        await rm(tmpDir, { recursive: true, force: true }).catch(() => void 0);
-      }
-      throw err instanceof Error ? err : new Error(String(err));
-    }
-  }
-  const proxy = new MitmProxy(caKeyPem, caCertPem, isPhysical, onLog);
-  const proxyPort = await proxy.listen(preferredPort);
-  const proxyHost = resolveProxyHostForDevice(platform3, isPhysical);
-  const hostPort = `${proxyHost}:${proxyPort}`;
-  onLog?.(
-    `[mobile-net] MITM proxy listening; device target ${hostPort} (${platform3}${isPhysical ? " physical" : ""})`
-  );
-  let wiringReason = "HTTPS interception pending: capture begins once the device routes a TLS handshake through the proxy.";
-  let proxySet = false;
-  let caInstalledOnDevice = false;
-  try {
-    if (platform3 === "ANDROID") {
-      proxySet = await androidSetProxy(deviceId, hostPort, onLog);
-      if (!proxySet) {
-        wiringReason = "adb proxy configuration failed; no device traffic will be routed through the proxy.";
-      } else if (caCertPath) {
-        const { note } = await androidInstallCa(deviceId, caCertPath);
-        caInstalledOnDevice = true;
-        wiringReason = note;
-      }
-    } else {
-      if (!isPhysical && caCertPath) {
-        const { trusted, note } = await iosSimTrustCa(deviceId, caCertPath);
-        caInstalledOnDevice = trusted;
-        wiringReason = note;
-      } else if (isPhysical) {
-        wiringReason = "Physical iOS device: set the Wi-Fi HTTP proxy + trust the CA in Settings \u2192 General \u2192 About \u2192 Certificate Trust Settings manually; capture is limited to whatever routes through.";
-      }
-    }
-  } catch (err) {
-    wiringReason = `device wiring degraded: ${errMsg(err)}`;
-    onLog?.(`[mobile-net] ${wiringReason}`);
-  }
-  if (proxySet || caInstalledOnDevice) {
-    const marker = {
-      platform: platform3,
-      deviceId,
-      isPhysical,
-      proxySet,
-      originalProxy,
-      caInstalledOnDevice
-    };
-    activeCleanups.set(sessionKey, marker);
-    await writePendingCleanup(sessionKey, marker);
-  }
-  const capturedTmpDir = tmpDir;
-  const capturedCaCertPath = caCertPath;
-  let stopped = false;
-  let finalCalls = [];
-  const getCapabilities = () => {
-    if (proxy.isIntercepting) return { intercepting: true };
-    const reason = proxy.interceptionReason ?? wiringReason;
-    return reason ? { intercepting: false, reason } : { intercepting: false };
-  };
-  const stop = async () => {
-    if (stopped) return finalCalls;
-    stopped = true;
-    if (proxySet && platform3 === "ANDROID") {
-      await androidClearProxy(deviceId, originalProxy, onLog);
-    }
-    if (caInstalledOnDevice && capturedCaCertPath) {
-      if (platform3 === "ANDROID") {
-        await androidRemoveCa(deviceId, onLog);
-      } else if (!isPhysical) {
-        await iosSimRemoveCa(deviceId, onLog);
-      }
-    }
-    activeCleanups.delete(sessionKey);
-    await removePendingCleanup(sessionKey);
-    finalCalls = proxy.finalize();
-    await proxy.close();
-    if (capturedTmpDir) {
-      try {
-        await rm(capturedTmpDir, { recursive: true, force: true });
-      } catch (err) {
-        onLog?.(`[mobile-net] temp CA cleanup failed: ${errMsg(err)}`);
-      }
-    }
-    const apiCount = finalCalls.filter((c) => c.isApi).length;
-    onLog?.(
-      `[mobile-net] stopped: ${finalCalls.length} calls captured (${apiCount} API; HTTPS interception ${proxy.isIntercepting ? "ACTIVE" : "inactive"}).`
-    );
-    return finalCalls;
-  };
-  return {
-    proxyPort,
-    proxyHost,
-    caCertPath: capturedCaCertPath,
-    getCapabilities,
-    stop
-  };
-}
-
 // src/services/doctor.ts
 import { execSync } from "child_process";
 import { existsSync as existsSync2 } from "fs";
@@ -328281,9 +329984,22 @@ function printDoctorReport(report) {
 
 // src/runner.ts
 init_dist();
-var import_runner_core11 = __toESM(require_dist2());
+var import_runner_core12 = __toESM(require_dist2());
 function fingerprintTest(test) {
-  return createHash("sha256").update(test.name).update("\n--suite--\n").update(test.suiteName ?? "").update("\n--type--\n").update(test.testType ?? "").update("\n--code--\n").update(test.playwrightCode).digest("hex").slice(0, 24);
+  const code = test.framework === "APPIUM" ? [test.appiumCode ?? "", JSON.stringify(test.steps ?? [])].join("\n--steps--\n") : test.playwrightCode ?? "";
+  return createHash("sha256").update(test.name).update("\n--suite--\n").update(test.suiteName ?? "").update("\n--type--\n").update(test.testType ?? "").update("\n--framework--\n").update(test.framework ?? "").update("\n--code--\n").update(code).digest("hex").slice(0, 24);
+}
+function mobileDiscoveryNetworkContext(result, appId) {
+  const page = result?.collectedPages?.find((p) => p.screenId || p.route);
+  const screenId = page?.screenId ?? page?.route;
+  return screenId ? `mobile:${screenId}` : `mobile:${appId}`;
+}
+function attachMobileDiscoveryNetworkContext(calls, result, appId) {
+  const pageUrl = mobileDiscoveryNetworkContext(result, appId);
+  return calls.map((call) => ({
+    ...call,
+    pageUrl: call.pageUrl ?? pageUrl
+  }));
 }
 var SECRET_VAR_PATTERN = /password|secret|token|api[_]?key|pass\b|credential|bearer|pat\b/i;
 var IS_CLOUD = process.env.RUNNER_CLOUD === "true";
@@ -328713,7 +330429,7 @@ function pruneCollectedPageForPost(page) {
   if (Array.isArray(out.observations)) out.observations = out.observations.slice(-200).map((obs) => compactForAudit(obs));
   return out;
 }
-function prepareDiscoveryResultForPost(result, logs2) {
+function prepareDiscoveryResultForPost(result, logs2, options = {}) {
   const safe = { ...result, logs: truncateTextTail(logs2, RESULT_LOG_MAX_CHARS, "discovery result log") };
   if (Array.isArray(safe.collectedPages)) safe.collectedPages = safe.collectedPages.map(pruneCollectedPageForPost);
   if (Array.isArray(safe.apiCalls)) safe.apiCalls = safe.apiCalls.map((call) => compactForAudit(call));
@@ -328729,6 +330445,10 @@ function prepareDiscoveryResultForPost(result, logs2) {
   if (safe.snapshotEvidence) safe.snapshotEvidence = compactForAudit(safe.snapshotEvidence);
   if (safe.discoveryCheckpoints) safe.discoveryCheckpoints = compactForAudit(safe.discoveryCheckpoints);
   if (safe.pageScreenshotKeys && safe.pageScreenshots) delete safe.pageScreenshots;
+  if (options.omitScreenshots) {
+    if (Array.isArray(safe.screenshots)) delete safe.screenshots;
+    if (safe.pageScreenshots) delete safe.pageScreenshots;
+  }
   if (safe.exploreAlreadySaved === true) {
     if (Array.isArray(safe.screenshots)) delete safe.screenshots;
     if (safe.pageScreenshots) delete safe.pageScreenshots;
@@ -328828,7 +330548,7 @@ async function executeRun(run2, opts, headers, requestLiveBrowserHeartbeat = ()
   const runMode = run2.mode ?? "run";
   const RUNNER_MODE = opts.runnerMode ?? "playwright-native";
   log.info(`Running test: ${run2.testCaseId ?? "auth-setup"} (run ${run2.runId}) [mode: ${runMode === "heal" ? "heal" : runMode === "auth-setup" ? "auth-setup" : RUNNER_MODE}]`);
-  const liveBrowserHandle = import_runner_core10.liveBrowserRegistry.register({
+  const liveBrowserHandle = import_runner_core11.liveBrowserRegistry.register({
     sessionId: `${run2.runId}`,
     mode: toLiveBrowserMode(runMode),
     runId: run2.runId,
@@ -328837,7 +330557,10 @@ async function executeRun(run2, opts, headers, requestLiveBrowserHeartbeat = ()
     testCaseId: run2.testCaseId ?? void 0
   });
   requestLiveBrowserHeartbeat(true);
-  const liveBrowserHeartbeatInterval = setInterval(() => requestLiveBrowserHeartbeat(), 5e3);
+  const liveBrowserHeartbeatInterval = setInterval(() => {
+    liveBrowserHandle.patch({});
+    requestLiveBrowserHeartbeat();
+  }, 5e3);
   liveBrowserHeartbeatInterval.unref?.();
   const runNativeWithLiveBrowser = (nativeOptions) => (0, import_runner_core.executeTestViaNativePlaywright)({
     ...nativeOptions,
@@ -328864,7 +330587,7 @@ async function executeRun(run2, opts, headers, requestLiveBrowserHeartbeat = ()
         log.fail(`PRE-FLIGHT FAILED - ${preflightError}`);
         return;
       }
-      const preflight = await (0, import_runner_core11.resolveBaseUrlPreflight)(run2.baseUrl);
+      const preflight = await (0, import_runner_core12.resolveBaseUrlPreflight)(run2.baseUrl);
       if (preflight.error) {
         await postResult(opts.serverUrl, headers, run2.runId, { status: "ERROR", error: preflight.error });
         log.fail(`PRE-FLIGHT FAILED - ${preflight.error}`);
@@ -328921,7 +330644,7 @@ async function executeRun(run2, opts, headers, requestLiveBrowserHeartbeat = ()
         return;
       }
       const healLogStream = createHealLogStreamer(opts.serverUrl, headers, run2.runId);
-      const batchResult = await (0, import_runner_core9.executeGrokPerBatchHeal)(tests, run2.baseUrl, {
+      const batchResult = await (0, import_runner_core10.executeGrokPerBatchHeal)(tests, run2.baseUrl, {
         testVariables: run2.testVariables,
         runNativeTest: runNativeWithLiveBrowser,
         validateContext: { runId: run2.runId, serverUrl: opts.serverUrl, authHeader: headers.Authorization },
@@ -329155,7 +330878,7 @@ ${finalVerifyResult.logs ?? ""}`;
           if (classifyErrorMessage(composedError ?? null) === "config_issue") {
             apiHealStatus = "ERROR";
           } else {
-            const rlDetection = (0, import_runner_core11.detectRateLimitBlock)({
+            const rlDetection = (0, import_runner_core12.detectRateLimitBlock)({
               testName: run2.testName ?? run2.testCaseId ?? void 0,
               tags: run2.tags ?? [],
               error: composedError ?? finalVerifyResult?.error ?? null,
@@ -329243,6 +330966,7 @@ ${finalVerifyResult.logs ?? ""}`;
         tags: run2.tags ?? [],
         surfaceIntelligence: run2.surfaceIntelligence,
         healingContext: run2.healingContext ?? null,
+        selectorRegistryContext: run2.selectorRegistryContext ?? null,
         lastFailureError: run2.lastFailureError,
         testVariables: run2.testVariables,
         onAICall: healAudit,
@@ -329261,7 +330985,7 @@ ${finalVerifyResult.logs ?? ""}`;
         log.info(`Heal engine: GROK (${source})`);
       }
       const grokHealLogStream = useGrokHeal ? createHealLogStreamer(opts.serverUrl, headers, run2.runId) : null;
-      const result2 = useGrokHeal ? await (0, import_runner_core9.executeGrokPerTestHeal)(run2.playwrightCode, run2.steps, run2.baseUrl, {
+      const result2 = useGrokHeal ? await (0, import_runner_core10.executeGrokPerTestHeal)(run2.playwrightCode, run2.steps, run2.baseUrl, {
         ...healOpts,
         onLog: grokHealLogStream.onLog
       }) : await (0, import_runner_core2.executeTestWithHealing)(run2.playwrightCode, run2.steps, run2.baseUrl, healOpts);
@@ -329294,7 +331018,7 @@ ${finalVerifyResult.logs ?? ""}`;
       let healStatus = result2.passed ? "PASSED" : isConfigIssue ? "ERROR" : "FAILED";
       let healError = result2.error;
       if (!result2.passed && !isConfigIssue) {
-        const rlDetection = (0, import_runner_core11.detectRateLimitBlock)({
+        const rlDetection = (0, import_runner_core12.detectRateLimitBlock)({
           testName: run2.testName ?? run2.testCaseId ?? void 0,
           tags: run2.tags ?? [],
           error: result2.error,
@@ -329477,6 +331201,7 @@ ${finalVerifyResult.logs ?? ""}`;
               tags: failedTest.tags ?? [],
               surfaceIntelligence: failedTest.healingContext ? null : run2.surfaceIntelligence,
               healingContext: failedTest.healingContext ?? null,
+              selectorRegistryContext: failedTest.selectorRegistryContext ?? null,
               lastFailureError: failedTest.error,
               testVariables: run2.testVariables,
               onAICall: healAudit,
@@ -329487,7 +331212,7 @@ ${finalVerifyResult.logs ?? ""}`;
               liveBrowserHandle,
               runNativeTest: runNativeWithLiveBrowser
             };
-            const healResult = useGrokHealSuite ? await (0, import_runner_core9.executeGrokPerTestHeal)(
+            const healResult = useGrokHealSuite ? await (0, import_runner_core10.executeGrokPerTestHeal)(
               failedTest.playwrightCode,
               failedTest.steps ?? [],
               run2.baseUrl,
@@ -329775,9 +331500,16 @@ ${finalVerifyResult.logs ?? ""}`;
               signal: AbortSignal.timeout(3e4)
             });
             if (res.ok) return;
-            log.warn(`[stream] discovery-plan attempt ${attempt + 1} returned ${res.status}`);
+            const responseText = await res.text().catch(() => "");
+            const statusMessage = responseText ? `${res.status}: ${responseText.slice(0, 500)}` : String(res.status);
+            if (res.status === 409) {
+              throw new Error(`Discovery plan checkpoint rejected: ${statusMessage}`);
+            }
+            log.warn(`[stream] discovery-plan attempt ${attempt + 1} returned ${statusMessage}`);
           } catch (err) {
-            log.warn(`[stream] discovery-plan attempt ${attempt + 1} failed: ${err instanceof Error ? err.message : String(err)}`);
+            const message = err instanceof Error ? err.message : String(err);
+            if (/Discovery plan checkpoint rejected/i.test(message)) throw err;
+            log.warn(`[stream] discovery-plan attempt ${attempt + 1} failed: ${message}`);
           }
           if (attempt < 2) await new Promise((r) => setTimeout(r, 3e3 * (attempt + 1)));
         }
@@ -329785,6 +331517,7 @@ ${finalVerifyResult.logs ?? ""}`;
       };
       let discoveryResult;
       const buildFinalBody = (r, overrideError, auditWarning) => {
+        const isNativeDiscovery = ctx.medium === "IOS_NATIVE" || ctx.medium === "ANDROID_NATIVE";
         const { exploreFinalMessages: _exploreFinalMessages, ...rest } = r;
         void _exploreFinalMessages;
         const logs2 = auditWarning ? [rest.logs, auditWarning].filter(Boolean).join("\n") : rest.logs;
@@ -329834,7 +331567,7 @@ ${finalVerifyResult.logs ?? ""}`;
           resolvedAppOrigin: rest.resolvedAppOrigin,
           plans: rest.plans,
           exploreStats: rest.exploreStats,
-          screenshots: rest.screenshots,
+          ...isNativeDiscovery ? {} : { screenshots: rest.screenshots },
           snapshotEvidence: rest.snapshotEvidence,
           discoveryCheckpoints: rest.discoveryCheckpoints,
           streamedTestCount: streamedTestKeys.size,
@@ -329843,8 +331576,10 @@ ${finalVerifyResult.logs ?? ""}`;
           ...explorePosted ? {} : {
             collectedPages: rest.collectedPages,
             collectedTransitions: rest.collectedTransitions,
-            pageScreenshots: rest.pageScreenshots,
-            pageScreenshotKeys: rest.pageScreenshotKeys
+            ...isNativeDiscovery ? {} : {
+              pageScreenshots: rest.pageScreenshots,
+              pageScreenshotKeys: rest.pageScreenshotKeys
+            }
           },
           ...harPosted ? {} : {
             apiCalls: rest.apiCalls,
@@ -329852,7 +331587,7 @@ ${finalVerifyResult.logs ?? ""}`;
           },
           // Only send tests that were NOT confirmed streamed to avoid duplicates
           tests: rest.tests.filter((t) => !streamedTestKeys.has(fingerprintTest(t)))
-        }, logs2);
+        }, logs2, { omitScreenshots: isNativeDiscovery });
       };
       const acquireLoginBrowser = async () => {
         const browser = await browserPool.acquireAsync(12e3);
@@ -329895,6 +331630,14 @@ ${finalVerifyResult.logs ?? ""}`;
             throw new Error("CONFIG_ISSUE: the shared mobile device is busy with an active recording session; mobile discovery will retry once it ends.");
           }
           const mobileOnLog = (line) => onLog("progress", line);
+          liveBrowserHandle.patch({
+            mode: ctx.mode === "survey" ? "survey" : "discovery",
+            testName: ctx.featureName ?? "Mobile discovery",
+            note: `${platform3} mobile discovery`,
+            surface: "mobile",
+            mobilePlatform: platform3
+          });
+          requestLiveBrowserHeartbeat(true);
           mobileOnLog(`Mobile discovery (${ctx.mode}) \u2014 ${platform3} / ${mobileTarget.appId}`);
           setExecutorBusy(true);
           let session = null;
@@ -329907,6 +331650,24 @@ ${finalVerifyResult.logs ?? ""}`;
               recordedDeviceId: mobileTarget.recordedDeviceId,
               launchMode: mobileTarget.launchMode,
               deeplink: mobileTarget.deeplink
+            }, {
+              onDeviceSelected: async (device) => {
+                try {
+                  capture = await startMobileNetworkCapture({
+                    platform: platform3,
+                    deviceId: device.deviceId,
+                    appId: mobileTarget.appId,
+                    isPhysical: device.isPhysical,
+                    onLog: mobileOnLog
+                  });
+                  const caps = capture.getCapabilities();
+                  if (!caps.intercepting) {
+                    mobileOnLog(`[mobile-net] HTTPS interception unavailable: ${caps.reason ?? "unknown reason"} (continuing \u2014 plaintext/metadata only)`);
+                  }
+                } catch (captureErr) {
+                  mobileOnLog(`[mobile-net] capture unavailable: ${captureErr instanceof Error ? captureErr.message : String(captureErr)} (continuing without network log)`);
+                }
+              }
             });
             mobileOnLog(`Appium session created: ${session.sessionId} on device ${session.deviceId}`);
             attachMirrorSession(session.sessionId, platform3);
@@ -329915,24 +331676,21 @@ ${finalVerifyResult.logs ?? ""}`;
               platform: platform3,
               appId: session.appId
             });
-            capture = await startMobileNetworkCapture({
-              platform: platform3,
-              deviceId: session.deviceId,
-              appId: session.appId,
-              isPhysical: session.isPhysical,
-              onLog: mobileOnLog
-            });
-            const caps = capture.getCapabilities();
-            if (!caps.intercepting) {
-              mobileOnLog(`[mobile-net] HTTPS interception unavailable: ${caps.reason ?? "unknown reason"} (continuing \u2014 plaintext/metadata only)`);
-            }
             discoveryResult = await (0, import_runner_core4.runMobileDiscoveryOnRunner)(ctx, driver, {
               onLog: mobileOnLog,
               onAICall: discoveryAudit,
               // Stream the live device mirror through the existing page-screenshot
-              // relay (mobile has no route, so key it as 'mobile'). Fire-and-forget.
+              // relay (mobile has no route, so key it as 'mobile') and the
+              // heartbeat live-session feed. The heartbeat frame gives the web
+              // UI a reliable mobile fallback when the direct bridge SSE is
+              // still opening or blocked by the user's network/tunnel.
               onScreenshot: (base64) => {
-                void onScreenshot("mobile", base64);
+                liveBrowserHandle.updateSnapshot({
+                  currentUrl: mobileTarget.appId,
+                  thumbnailJpegBase64: base64,
+                  thumbnailCapturedAt: Date.now()
+                });
+                requestLiveBrowserHeartbeat();
               },
               onExploreComplete,
               onTestGenerated,
@@ -329943,7 +331701,7 @@ ${finalVerifyResult.logs ?? ""}`;
               try {
                 const apiCalls = await capture.stop();
                 if (discoveryResult) {
-                  discoveryResult.apiCalls = apiCalls.length ? apiCalls : void 0;
+                  discoveryResult.apiCalls = apiCalls.length ? attachMobileDiscoveryNetworkContext(apiCalls, discoveryResult, session?.appId ?? mobileTarget.appId) : void 0;
                 }
               } catch (capErr) {
                 mobileOnLog(`[mobile-net] capture stop failed: ${capErr instanceof Error ? capErr.message : String(capErr)}`);
@@ -329959,7 +331717,7 @@ ${finalVerifyResult.logs ?? ""}`;
             setExecutorBusy(false);
           }
         } else if (ctx.mode === "import") {
-          const runRepoImport = ctx.frameworkImport?.kind === "repo-analysis" ? import_runner_core9.runRepoAnalysisOnRunner : import_runner_core9.runFrameworkImportOnRunner;
+          const runRepoImport = ctx.frameworkImport?.kind === "repo-analysis" ? import_runner_core10.runRepoAnalysisOnRunner : import_runner_core10.runFrameworkImportOnRunner;
           discoveryResult = await runRepoImport(ctx, { onTestGenerated, acquireLoginBrowser, onAudit: discoveryAudit }, {
             archiveUrl: ctx.frameworkImport?.source === "upload" ? `${opts.serverUrl}/api/runner/runs/${run2.runId}/import-archive` : void 0,
             archiveAuthHeader: headers.Authorization,
@@ -330260,6 +332018,7 @@ ${finalVerifyResult.logs ?? ""}`;
         status,
         stepResults: result2.stepResults,
         screenshots: result2.screenshots,
+        apiCalls: result2.apiCalls,
         logs: result2.logs,
         error: reportedError,
         duration: duration2
@@ -330288,7 +332047,7 @@ ${finalVerifyResult.logs ?? ""}`;
     let runStatus = result.passed ? "PASSED" : "FAILED";
     let runError = result.error;
     if (!result.passed) {
-      const rlDetection = (0, import_runner_core11.detectRateLimitBlock)({
+      const rlDetection = (0, import_runner_core12.detectRateLimitBlock)({
         testName: run2.testName ?? run2.testCaseId ?? void 0,
         tags: run2.tags ?? [],
         error: result.error,
@@ -330426,7 +332185,7 @@ async function startRunner(opts) {
     capture: envInt("MAX_CAPTURE", DEFAULT_TYPE_LIMITS.capture),
     run: envInt("MAX_RUN", DEFAULT_TYPE_LIMITS.run)
   };
-  const RESOURCE_GOVERNOR_OPTIONS = (0, import_runner_core11.createResourceGovernorOptions)({
+  const RESOURCE_GOVERNOR_OPTIONS = (0, import_runner_core12.createResourceGovernorOptions)({
     isCloud: IS_CLOUD,
     maxConcurrent: MAX_CONCURRENT,
     typeLimits: TYPE_LIMITS
@@ -330577,8 +332336,8 @@ async function startRunner(opts) {
         android: devices.some((d) => d.platform === "ANDROID" && d.isAvailable && d.state === "BOOTED")
       } : { web: true, ios: false, android: false };
       const bridge = enableMobile ? getBridgeState() : void 0;
-      const resourceStatus = (0, import_runner_core11.getResourceGovernorStatus)(RESOURCE_GOVERNOR_OPTIONS, Object.fromEntries(activeByType));
-      const processInventory = await (0, import_runner_core11.getBrowserProcessInventory)();
+      const resourceStatus = (0, import_runner_core12.getResourceGovernorStatus)(RESOURCE_GOVERNOR_OPTIONS, Object.fromEntries(activeByType));
+      const processInventory = await (0, import_runner_core12.getBrowserProcessInventory)();
       lastInventoryPids = new Set(processInventory.processes.map((p) => p.pid));
       lastInventoryKinds.clear();
       for (const p of processInventory.processes) lastInventoryKinds.set(p.pid, p.kind);
@@ -330605,8 +332364,8 @@ async function startRunner(opts) {
           resourceSnapshot: resourceStatus.snapshot,
           resourceGovernor: resourceStatus.governor,
           processInventory,
-          aiQueue: (0, import_runner_core11.getRunnerAIQueueStats)(),
-          liveBrowsers: import_runner_core10.liveBrowserRegistry.snapshotForHeartbeat(),
+          aiQueue: (0, import_runner_core12.getRunnerAIQueueStats)(),
+          liveBrowsers: import_runner_core11.liveBrowserRegistry.snapshotForHeartbeat(),
           // Pre-flight checks (ANDROID_HOME, Xcode, Appium drivers, adb, etc).
           // Cached & cheap — see getCachedDoctor above.
           doctor: getCachedDoctor()
@@ -330700,7 +332459,7 @@ async function startRunner(opts) {
   let pidsWatchdogWarned = false;
   const pidsWatchdog = setInterval(() => {
     if (shuttingDown) return;
-    const snapshot = (0, import_runner_core11.getResourceSnapshot)();
+    const snapshot = (0, import_runner_core12.getResourceSnapshot)();
     const pct = snapshot.pidsPct;
     if (pct == null || !Number.isFinite(pct)) return;
     if (pct >= PIDS_RECYCLE_PCT) {
@@ -330736,7 +332495,7 @@ async function startRunner(opts) {
               log.dim(`  Deferred ${run2.runId} (project ${runProject} at capacity ${getActiveForProject(runProject)}/${projectLimit})`);
               continue;
             }
-            const admission = (0, import_runner_core11.evaluateRunAdmission)(RESOURCE_GOVERNOR_OPTIONS, {
+            const admission = (0, import_runner_core12.evaluateRunAdmission)(RESOURCE_GOVERNOR_OPTIONS, {
               mode: runMode,
               activeRuns,
               activeByType: Object.fromEntries(activeByType),