@validate.qa/runner 1.0.79 → 1.0.81

package/dist/cli.js

@@ -1907,7 +1907,7 @@ function isValidLiveFrame(frame) {
     return false;
   return true;
 }
-var readEnvInt, LIVE_FRAME_PUSH_MAX_BASE64_BYTES, LIVE_THUMBNAIL_MAX_BASE64_BYTES, LIVE_FRAME_MAX_DIMENSION, LIVE_FRAME_JPEG_QUALITY, LIVE_FRAME_MIN_PUSH_INTERVAL_MS, LIVE_FRAME_UNFOCUSED_INTERVAL_MS, LIVE_FRAME_STALE_MS, LIVE_FRAME_MAX_SESSIONS_PER_PROJECT, MOBILE_MJPEG_SETTINGS, MOBILE_MJPEG_FIRST_FRAME_TIMEOUT_MS, MOBILE_MJPEG_MAX_FRAME_BYTES;
+var readEnvInt, LIVE_FRAME_PUSH_MAX_BASE64_BYTES, LIVE_THUMBNAIL_MAX_BASE64_BYTES, LIVE_FRAME_MAX_DIMENSION, LIVE_FRAME_JPEG_QUALITY, LIVE_FRAME_MIN_PUSH_INTERVAL_MS, LIVE_FRAME_UNFOCUSED_INTERVAL_MS, LIVE_FRAME_IDLE_PUSH_INTERVAL_MS, LIVE_FRAME_STALE_MS, LIVE_FRAME_MAX_SESSIONS_PER_PROJECT, MOBILE_MJPEG_SETTINGS, MOBILE_MJPEG_FIRST_FRAME_TIMEOUT_MS, MOBILE_MJPEG_MAX_FRAME_BYTES;
 var init_live_frame = __esm({
   "../shared/dist/live-frame.js"() {
     "use strict";
@@ -1923,6 +1923,7 @@ var init_live_frame = __esm({
     LIVE_FRAME_JPEG_QUALITY = readEnvInt("LIVE_FRAME_JPEG_QUALITY", 55);
     LIVE_FRAME_MIN_PUSH_INTERVAL_MS = readEnvInt("LIVE_FRAME_MIN_PUSH_INTERVAL_MS", 125);
     LIVE_FRAME_UNFOCUSED_INTERVAL_MS = readEnvInt("LIVE_FRAME_UNFOCUSED_INTERVAL_MS", 2e3);
+    LIVE_FRAME_IDLE_PUSH_INTERVAL_MS = readEnvInt("LIVE_FRAME_IDLE_PUSH_INTERVAL_MS", 5e3);
     LIVE_FRAME_STALE_MS = readEnvInt("LIVE_FRAME_STALE_MS", 3e4);
     LIVE_FRAME_MAX_SESSIONS_PER_PROJECT = readEnvInt("LIVE_FRAME_MAX_SESSIONS_PER_PROJECT", 32);
     MOBILE_MJPEG_SETTINGS = {
@@ -6360,6 +6361,7 @@ __export(dist_exports, {
   GROUP_LABELS: () => GROUP_LABELS,
   LEGACY_TTS_MODEL_MAP: () => LEGACY_TTS_MODEL_MAP,
   LEGACY_TTS_VOICE_ID_MAP: () => LEGACY_TTS_VOICE_ID_MAP,
+  LIVE_FRAME_IDLE_PUSH_INTERVAL_MS: () => LIVE_FRAME_IDLE_PUSH_INTERVAL_MS,
   LIVE_FRAME_JPEG_QUALITY: () => LIVE_FRAME_JPEG_QUALITY,
   LIVE_FRAME_MAX_DIMENSION: () => LIVE_FRAME_MAX_DIMENSION,
   LIVE_FRAME_MAX_SESSIONS_PER_PROJECT: () => LIVE_FRAME_MAX_SESSIONS_PER_PROJECT,
@@ -321051,6 +321053,7 @@ var require_primary_action_ledger = __commonJS({
     exports2.isLedgerActive = isLedgerActive;
     exports2.isGateEnforcing = isGateEnforcing;
     exports2.isSteeringActive = isSteeringActive;
+    exports2.isPrimaryActionCoverageGapEnabled = isPrimaryActionCoverageGapEnabled;
     exports2.leadingVerb = leadingVerb;
     exports2.classifyPrimaryAction = classifyPrimaryAction;
     exports2.containerScopeOf = containerScopeOf;
@@ -321065,6 +321068,8 @@ var require_primary_action_ledger = __commonJS({
     exports2.classifyActionOutcome = classifyActionOutcome;
     exports2.detectPrimaryActions = detectPrimaryActions;
     exports2.summarizeLedger = summarizeLedger;
+    exports2.summarizeUnexercisedPrimaries = summarizeUnexercisedPrimaries;
+    exports2.buildUnexercisedPrimaryCoverageGaps = buildUnexercisedPrimaryCoverageGaps;
     var reveal_diff_js_1 = require_reveal_diff();
     var exploration_parser_js_1 = require_exploration_parser();
     function getPrimaryActionGateMode(env = process.env) {
@@ -321084,6 +321089,10 @@ var require_primary_action_ledger = __commonJS({
     function isSteeringActive(mode) {
       return mode === "advisory" || mode === "enforce";
     }
+    function isPrimaryActionCoverageGapEnabled(env = process.env) {
+      const raw = (env.DISCOVERY_PRIMARY_ACTION_COVERAGE_GAP ?? "").trim().toLowerCase();
+      return raw === "1" || raw === "true" || raw === "on" || raw === "enabled";
+    }
     exports2.PRIMARY_ACTION_VERB_RE = /^(run|analyze|analyse|generate|regenerate|process|submit|save|create|send|upload|search|export|import|calculate|recalculate|compute|convert|start|scan|translate|transcribe|render|publish|sync|deploy|enrich|summar(?:ize|ise))\b/i;
     exports2.AMBIGUOUS_ACTION_VERB_RE = /^(continue|next|apply|go|proceed|confirm|update|add|edit|ok|done|finish|complete|approve|enable|activate)\b/i;
     exports2.DESTRUCTIVE_ACTION_VERB_RE = /^(delete|remove|archive|reset|disconnect|deactivate|destroy|purge|revoke|discard|drop|wipe|erase|unsubscribe|cancel|clear|trash)\b/i;
@@ -321347,6 +321356,47 @@ var require_primary_action_ledger = __commonJS({
       }
       return `actions=${c.total} primary{detected=${c.detected} attempted=${c.attempted} captured=${c.captured} blocked=${c.blocked} exempt=${c.exempt}} ambiguous=${c.ambiguous}`;
     }
+    function summarizeUnexercisedPrimaries(ledger, routeInScope, cap = 12) {
+      const out = [];
+      for (const e of getBlockingActionDebt(ledger, routeInScope)) {
+        if (e.status !== "DETECTED" && e.status !== "ATTEMPTED")
+          continue;
+        out.push({ label: e.label, route: e.route, containerScope: e.containerScope, status: e.status });
+        if (out.length >= cap)
+          break;
+      }
+      return out;
+    }
+    var REGEXP_META_RE = /[.*+?^${}()|[\]\\]/g;
+    function labelCoveredByPlan(normLabel, plannedLower) {
+      if (!normLabel.includes(" "))
+        return false;
+      const escaped = normLabel.replace(REGEXP_META_RE, "\\$&");
+      return new RegExp(`(^|\\W)${escaped}($|\\W)`).test(plannedLower);
+    }
+    function buildUnexercisedPrimaryCoverageGaps(unexercised, plannedScenarioText, nowIso) {
+      const gaps = [];
+      const seen = /* @__PURE__ */ new Set();
+      const planned = plannedScenarioText.toLowerCase();
+      for (const a of unexercised) {
+        const norm = normLabelKey(a.label);
+        const key = `${norm}|${a.route}`;
+        if (seen.has(key))
+          continue;
+        seen.add(key);
+        if (labelCoveredByPlan(norm, planned))
+          continue;
+        const clickedNote = a.status === "ATTEMPTED" ? "clicked, but no result state was captured" : "never clicked";
+        gaps.push({
+          scenarioName: `Exercise "${a.label}"`,
+          reason: `Primary action "${a.label}" was detected on ${a.route} but never exercised to an observed result (${clickedNote}).`,
+          suggestion: `Exercise "${a.label}" to a captured result \u2014 open its result modal/panel and capture it BEFORE closing \u2014 or schedule a deep run scoped to this action, so a real test can be authored.`,
+          unmetPrerequisites: [],
+          detectedAt: nowIso
+        });
+      }
+      return gaps;
+    }
   }
 });
 
@@ -322835,6 +322885,9 @@ var require_exploration_prompt_builder = __commonJS({
         "These are the feature's core actions \u2014 what it EXISTS to do. You are on a PROVISIONED TEST ACCOUNT, so exercising them is the point of this exploration. For each: click it, wait for it to finish (an async job can take 10-60s \u2014 keep waiting and capturing, do not give up early), then capture_page the result (a new panel, row, score, status, or route change).",
         `Spending in-app COMPUTE credits is expected and budgeted \u2014 running an Analyze / Generate / Run / Process ONCE to observe its output is exactly what you should do; an "N of M used" usage or AI-credit meter is NOT a reason to skip. These were auto-screened, but YOU are the final check: if you can see a specific listed action actually charges REAL money at a checkout (Buy / Upgrade / Subscribe), makes an irreversible or destructive change (Delete / Wipe / Deploy to production), or sends a message to real people (Send email / Invite), SKIP just that one \u2014 note it as blocked with the reason and move on. Don't finish until every other action below has produced an observed outcome:`
       ];
+      if ((0, primary_action_ledger_js_1.isPrimaryActionCoverageGapEnabled)()) {
+        out.push("If the result opens in a modal, dialog, or panel, call capture_page WHILE IT IS STILL OPEN \u2014 do not close or dismiss it first, or the result state is never recorded and the action does not count as covered. An action reachable only from inside this feature's own result modal is in-scope: exercise it to a captured result before closing, even if it generates content that belongs to another builder.");
+      }
       for (const e of debt.slice(0, 8)) {
         const note = e.status === "ATTEMPTED" ? " \u2014 clicked but no result captured yet" : "";
         out.push(`  - "${e.label}" on ${e.route}${note}`);
@@ -326655,6 +326708,7 @@ ${inbox_tools_js_1.EMAIL_VERIFICATION_UNAVAILABLE_OVERRIDE_BLOCK}` : ""}`;
       const primaryActionMode = (0, primary_action_ledger_js_1.getPrimaryActionGateMode)();
       const primaryActionLedgerActive = (0, primary_action_ledger_js_1.isLedgerActive)(primaryActionMode) && options?.mode === "deep";
       const primaryActionEnforcing = primaryActionLedgerActive && (0, primary_action_ledger_js_1.isGateEnforcing)(primaryActionMode);
+      const primaryActionCoverageGapEnabled = primaryActionLedgerActive && (0, primary_action_ledger_js_1.isPrimaryActionCoverageGapEnabled)();
       const prevRouteSignatures = /* @__PURE__ */ new Map();
       const prevInteractionCountsByRoute = /* @__PURE__ */ new Map();
       let previousCaptureRoute = null;
@@ -326665,6 +326719,16 @@ ${inbox_tools_js_1.EMAIL_VERIFICATION_UNAVAILABLE_OVERRIDE_BLOCK}` : ""}`;
       let finishBounce = (0, survey_link_frontier_js_1.initialFinishBounceState)();
       let lastLandedPageUrl = null;
       const state2 = (0, exploration_state_js_1.createExplorationState)();
+      const buildUnexercisedPrimarySummary = () => {
+        if (!primaryActionCoverageGapEnabled)
+          return void 0;
+        const fa = options?.focusAreas ?? [];
+        if (fa.length === 0)
+          return void 0;
+        const otherRoutes = options?.featureContext?.otherFeatures?.flatMap((f) => f.pages);
+        const summary2 = (0, primary_action_ledger_js_1.summarizeUnexercisedPrimaries)(state2.actionLedger, (r) => (0, exploration_parser_js_1.routeIsWithinFocusAreas)(r, fa, otherRoutes), 12);
+        return summary2.length > 0 ? summary2 : void 0;
+      };
       function ingestLinksFromText(rawText) {
         if (!linkFrontierEnabled || !rawText || !rawText.includes("- /url:"))
           return;
@@ -328895,6 +328959,7 @@ Exploration ended after ${iteration} iterations without calling finish_explorati
             summary: state2.summary || summary,
             collectedPages: state2.collectedPages,
             collectedTransitions: state2.collectedTransitions,
+            unexercisedPrimaryActions: buildUnexercisedPrimarySummary(),
             iterationTimeline: iterationTimeline.length > 0 ? iterationTimeline : void 0
           };
         }
@@ -328989,6 +329054,7 @@ Fatal error: ${msg}`);
             summary: `Fatal error: ${msg}`,
             collectedPages: state2.collectedPages,
             collectedTransitions: state2.collectedTransitions,
+            unexercisedPrimaryActions: buildUnexercisedPrimarySummary(),
             iterationTimeline: iterationTimeline.length > 0 ? iterationTimeline : void 0,
             truncated: true,
             truncatedReason,
@@ -337175,6 +337241,7 @@ var require_discover_agent = __commonJS({
     var discover_planner_js_1 = require_discover_planner();
     var discover_generator_js_1 = require_discover_generator();
     var discover_ai_planner_js_1 = require_discover_ai_planner();
+    var primary_action_ledger_js_1 = require_primary_action_ledger();
     var discovery_lint_flags_js_1 = require_discovery_lint_flags();
     var verification_inbox_js_1 = require_verification_inbox();
     var inbox_tools_js_1 = require_inbox_tools();
@@ -338477,6 +338544,16 @@ Plan: ${planResult.scenarios.length} scenarios (budget: ${featureTestBudget})`);
           checkpointFallbackReason = planResult.fallbackReason;
           plannerWarning = planResult.warning;
           plannerCoverageGaps = planResult.coverageGaps;
+          const unexercisedPrimaries = exploreResult.unexercisedPrimaryActions ?? [];
+          if (unexercisedPrimaries.length > 0) {
+            const plannedText = planResult.scenarios.map((s) => `${s.name} ${s.goal ?? ""} ${(s.targetPages ?? []).join(" ")}`).join(" ");
+            const ledgerGaps = (0, primary_action_ledger_js_1.buildUnexercisedPrimaryCoverageGaps)(unexercisedPrimaries, plannedText, (/* @__PURE__ */ new Date()).toISOString());
+            if (ledgerGaps.length > 0) {
+              plannerCoverageGaps = [...plannerCoverageGaps ?? [], ...ledgerGaps];
+            }
+            const suppressed = unexercisedPrimaries.length - ledgerGaps.length;
+            logs2.push(`  [primary-action-ledger] ${unexercisedPrimaries.length} in-scope primary action(s) un-exercised; surfaced ${ledgerGaps.length} as coverage gap(s)${suppressed > 0 ? ` (${suppressed} already covered by the plan / deduped)` : ""}`);
+          }
         }
         if (callbackOptions?.onPlanReady) {
           try {
@@ -353260,7 +353337,7 @@ var require_package4 = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@validate.qa/runner",
-      version: "1.0.79",
+      version: "1.0.81",
       description: "validate local test runner - execute Playwright tests on your machine, connected to validate.qa cloud.",
       bin: {
         "validate-runner": "dist/cli.js"
@@ -353529,6 +353606,9 @@ async function enforceRunnerUpToDate(currentVersion, opts = {}) {
   return result;
 }
 
+// src/runner.ts
+init_dist();
+
 // src/services/appium-executor.ts
 init_dist();
 
@@ -358890,6 +358970,7 @@ function startMjpegStream(options) {
 // src/services/mobile-bridge.ts
 init_dist();
 var MOBILE_BRIDGE_PORT2 = 9515;
+var RELAY_DEMAND_POLL_MS = 2e3;
 var MAX_REQUEST_BODY_BYTES = 64 * 1024;
 var MAX_TEXT_INPUT_LENGTH = 4e3;
 var MAX_APP_ID_LENGTH = 255;
@@ -359401,6 +359482,18 @@ async function handleSessionStop(_req, res) {
   sendJSON(res, 200, { ok: true });
 }
 var runnerChannels = /* @__PURE__ */ new Map();
+var relayDemandTimer = null;
+function setMirrorRelay(deviceId, relay) {
+  const ch = runnerChannels.get(deviceId);
+  if (!ch) return;
+  ch.relay = relay;
+  if (relay) {
+    ensureRelayDemandSupervisor();
+    if (hasChannelDemand(ch)) ensureChannelPolling(ch);
+  } else {
+    stopChannelCaptureIfIdle(ch);
+  }
+}
 function readDeviceIdParam(req) {
   try {
     const url = new URL(req.url || "", "http://localhost");
@@ -359432,7 +359525,7 @@ function writeFrameToChannelClient(ch, client, frame) {
       } catch {
       }
       ch.clients.delete(client);
-      stopChannelPollingIfIdle(ch);
+      stopChannelCaptureIfIdle(ch);
       return;
     }
     client.write(`data: ${JSON.stringify(frame)}
@@ -359444,6 +359537,12 @@ function writeFrameToChannelClient(ch, client, frame) {
 function broadcastChannelFrame(ch, frame) {
   ch.lastFrame = frame;
   for (const client of ch.clients) writeFrameToChannelClient(ch, client, frame);
+  if (ch.relay && frame.screenshot) {
+    try {
+      ch.relay.onFrame(frame.screenshot, frame.mimeType ?? "image/png");
+    } catch {
+    }
+  }
 }
 function tryStartChannelMjpeg(ch) {
   if (ch.mjpeg || ch.mjpegStarting || ch.mjpegUnavailable) return;
@@ -359481,7 +359580,7 @@ function tryStartChannelMjpeg(ch) {
       ch.mjpeg = null;
       ch.mjpegStarting = false;
       ch.mjpegUnavailable = true;
-      if (wasActive && ch.clients.size > 0) ensureChannelPolling(ch);
+      if (wasActive && hasChannelDemand(ch)) ensureChannelPolling(ch);
     }
   });
   const firstFrameDeadline = setTimeout(() => {
@@ -359489,12 +359588,30 @@ function tryStartChannelMjpeg(ch) {
     ch.mjpegStarting = false;
     ch.mjpegUnavailable = true;
     handle.stop();
-    if (ch.clients.size > 0) ensureChannelPolling(ch);
+    if (hasChannelDemand(ch)) ensureChannelPolling(ch);
   }, MOBILE_MJPEG_FIRST_FRAME_TIMEOUT_MS);
   firstFrameDeadline.unref?.();
 }
+function hasChannelDemand(ch) {
+  if (ch.clients.size > 0) return true;
+  return ch.relay !== null;
+}
+function ensureRelayDemandSupervisor() {
+  if (relayDemandTimer) return;
+  relayDemandTimer = setInterval(() => {
+    for (const ch of [...runnerChannels.values()]) {
+      if (hasChannelDemand(ch)) ensureChannelPolling(ch);
+      else stopChannelCaptureIfIdle(ch);
+    }
+    if (runnerChannels.size === 0 && relayDemandTimer) {
+      clearInterval(relayDemandTimer);
+      relayDemandTimer = null;
+    }
+  }, RELAY_DEMAND_POLL_MS);
+  relayDemandTimer.unref?.();
+}
 async function pollRunnerChannel(ch) {
-  if (ch.clients.size === 0 || ch.polling) return;
+  if (!hasChannelDemand(ch) || ch.polling) return;
   if (ch.mjpeg) return;
   ch.polling = true;
   try {
@@ -359525,6 +359642,7 @@ async function pollRunnerChannel(ch) {
   }
 }
 function ensureChannelPolling(ch) {
+  if (!hasChannelDemand(ch)) return;
   tryStartChannelMjpeg(ch);
   if (ch.mjpeg || ch.pollTimer) return;
   ch.pollTimer = setInterval(() => {
@@ -359532,8 +359650,8 @@ function ensureChannelPolling(ch) {
   }, MOBILE_SCREENSHOT_INTERVAL_MS);
   ch.pollTimer.unref?.();
 }
-function stopChannelPollingIfIdle(ch) {
-  if (ch.clients.size > 0) return;
+function stopChannelCaptureIfIdle(ch) {
+  if (hasChannelDemand(ch)) return;
   if (ch.pollTimer) {
     clearInterval(ch.pollTimer);
     ch.pollTimer = null;
@@ -359552,6 +359670,7 @@ function closeRunnerChannel(ch) {
     ch.mjpeg.stop();
     ch.mjpeg = null;
   }
+  ch.relay = null;
   for (const client of ch.clients) {
     try {
       client.end();
@@ -359560,7 +359679,7 @@ function closeRunnerChannel(ch) {
   }
   ch.clients.clear();
   ch.lastFrame = null;
-  runnerChannels.delete(ch.deviceId);
+  if (runnerChannels.get(ch.deviceId) === ch) runnerChannels.delete(ch.deviceId);
 }
 function closeAllRunnerChannels() {
   for (const ch of [...runnerChannels.values()]) closeRunnerChannel(ch);
@@ -359582,7 +359701,7 @@ async function serveRunnerMirror(req, res, ch) {
   }
   req.on("close", () => {
     ch.clients.delete(res);
-    stopChannelPollingIfIdle(ch);
+    stopChannelCaptureIfIdle(ch);
   });
 }
 async function handleMirror(req, res) {
@@ -360140,7 +360259,8 @@ function attachMirrorSession(sessionId, platform3, deviceId) {
       mjpeg: null,
       mjpegLastFrameAt: 0,
       mjpegStarting: false,
-      mjpegUnavailable: false
+      mjpegUnavailable: false,
+      relay: null
     };
     ch.sessionId = sessionId;
     ch.platform = platform3;
@@ -360154,7 +360274,7 @@ function attachMirrorSession(sessionId, platform3, deviceId) {
     runnerChannels.set(deviceId, ch);
     void applyMjpegSettings(`/session/${sessionId}`, MOBILE_MJPEG_SETTINGS).catch(() => {
     });
-    if (ch.clients.size > 0) {
+    if (hasChannelDemand(ch)) {
       ensureChannelPolling(ch);
       void pollRunnerChannel(ch);
     }
@@ -361126,6 +361246,13 @@ function attachMobileDiscoveryNetworkContext(calls, result, appId) {
   }));
 }
 var runnerPackage = require_package4();
+var MIRROR_RELAY_FRESH_MS = 3e3;
+var liveFrameWatchedByProject = /* @__PURE__ */ new Map();
+var liveFrameIdleProbeAt = /* @__PURE__ */ new Map();
+var LIVE_FRAME_IDLE_PROBE_MAX_ENTRIES = 256;
+function isLiveFrameWatched(projectId) {
+  return !projectId || liveFrameWatchedByProject.get(projectId) !== false;
+}
 var SECRET_VAR_PATTERN = /password|secret|token|api[_]?key|pass\b|credential|bearer|pat\b/i;
 var IS_CLOUD = parseBoolFlag(process.env.RUNNER_CLOUD);
 var RUNNER_NAME = runnerPackage.name ?? "@validate.qa/runner";
@@ -361903,6 +362030,22 @@ async function executeRun(run2, opts, headers, requestLiveBrowserHeartbeat = ()
     testCaseId: run2.testCaseId ?? void 0
   });
   requestLiveBrowserHeartbeat(true);
+  let lastMirrorRelayFrameAt = 0;
+  const attachMirrorWithRelay = (sessionId, platform3, deviceId) => {
+    attachMirrorSession(sessionId, platform3, deviceId);
+    if (!deviceId) return;
+    setMirrorRelay(deviceId, {
+      onFrame: (base64, mimeType) => {
+        lastMirrorRelayFrameAt = Date.now();
+        liveBrowserHandle.updateSnapshot({
+          thumbnailJpegBase64: base64,
+          thumbnailCapturedAt: Date.now(),
+          mimeType
+        });
+      },
+      wanted: () => isLiveFrameWatched(run2.projectId)
+    });
+  };
   const liveBrowserHeartbeatInterval = setInterval(() => {
     liveBrowserHandle.patch({});
     requestLiveBrowserHeartbeat();
@@ -362806,7 +362949,7 @@ ${finalVerifyResult.logs ?? ""}`;
               deeplink: harvestTarget.deeplink
             },
             onSessionReady: (sessionId, deviceId, sessionPlatform) => {
-              attachMirrorSession(sessionId, sessionPlatform, deviceId);
+              attachMirrorWithRelay(sessionId, sessionPlatform, deviceId);
               const name = getCachedDeviceSnapshot().find((d) => d.id === deviceId)?.name;
               liveBrowserHandle.patch({ deviceId, ...name ? { deviceName: name } : {} });
               requestLiveBrowserHeartbeat(true);
@@ -363276,7 +363419,7 @@ ${finalVerifyResult.logs ?? ""}`;
               }
             );
             mobileOnLog(`Appium session created: ${session.sessionId} on device ${session.deviceId}`);
-            attachMirrorSession(session.sessionId, platform3, session.deviceId);
+            attachMirrorWithRelay(session.sessionId, platform3, session.deviceId);
             const driver = new MobileBridgeDriver({
               sessionId: session.sessionId,
               platform: platform3,
@@ -363313,7 +363456,7 @@ ${finalVerifyResult.logs ?? ""}`;
                   throw new Error("discovery teardown started during session recovery \u2014 replacement session closed");
                 }
                 session = replacement;
-                attachMirrorSession(replacement.sessionId, platform3, replacement.deviceId);
+                attachMirrorWithRelay(replacement.sessionId, platform3, replacement.deviceId);
                 liveBrowserHandle.patch({
                   deviceId: replacement.deviceId,
                   deviceName: replacement.deviceName
@@ -363334,6 +363477,10 @@ ${finalVerifyResult.logs ?? ""}`;
               // UI a reliable mobile fallback when the direct bridge SSE is
               // still opening or blocked by the user's network/tunnel.
               onScreenshot: (base64) => {
+                if (Date.now() - lastMirrorRelayFrameAt < MIRROR_RELAY_FRESH_MS) {
+                  liveBrowserHandle.updateSnapshot({ currentUrl: mobileTarget.appId });
+                  return;
+                }
                 liveBrowserHandle.updateSnapshot({
                   currentUrl: mobileTarget.appId,
                   thumbnailJpegBase64: base64,
@@ -363806,7 +363953,7 @@ ${finalVerifyResult.logs ?? ""}`;
                   deeplink: target.deeplink
                 });
                 liveSession = opened;
-                attachMirrorSession(opened.sessionId, target.platform, opened.deviceId);
+                attachMirrorWithRelay(opened.sessionId, target.platform, opened.deviceId);
                 bridgeDriver = new MobileBridgeDriver({
                   sessionId: opened.sessionId,
                   platform: target.platform,
@@ -363996,7 +364143,7 @@ ${finalVerifyResult.logs ?? ""}`;
             // Stream this run to its OWN per-device dashboard tile (keyed by the
             // leased device id) so N parallel Appium runs each show a live mirror.
             onSessionReady: (sessionId, deviceId, sessionPlatform) => {
-              attachMirrorSession(sessionId, sessionPlatform, deviceId);
+              attachMirrorWithRelay(sessionId, sessionPlatform, deviceId);
               requestLiveBrowserHeartbeat(true);
             },
             onSessionEnding: (deviceId) => {
@@ -364588,12 +364735,31 @@ async function startRunner(opts) {
   const publishLiveFrame = (frame) => {
     if (!frame.projectId) return;
     if (liveFramePushInFlight.has(frame.sessionId)) return;
+    if (!isLiveFrameWatched(frame.projectId)) {
+      const lastProbeAt = liveFrameIdleProbeAt.get(frame.sessionId) ?? 0;
+      if (frame.capturedAt - lastProbeAt < LIVE_FRAME_IDLE_PUSH_INTERVAL_MS) return;
+      if (liveFrameIdleProbeAt.size >= LIVE_FRAME_IDLE_PROBE_MAX_ENTRIES) {
+        const expiredBefore = frame.capturedAt - LIVE_FRAME_IDLE_PUSH_INTERVAL_MS;
+        for (const [sessionId, probedAt] of liveFrameIdleProbeAt) {
+          if (probedAt >= expiredBefore) break;
+          liveFrameIdleProbeAt.delete(sessionId);
+        }
+      }
+      liveFrameIdleProbeAt.set(frame.sessionId, frame.capturedAt);
+    }
     liveFramePushInFlight.add(frame.sessionId);
+    const frameProjectId = frame.projectId;
     void fetch(`${serverUrl}/api/runner/live-frame`, {
       method: "POST",
       headers,
       body: JSON.stringify(frame),
       signal: AbortSignal.timeout(5e3)
+    }).then(async (res) => {
+      if (!res.ok) return;
+      const ack = await res.json().catch(() => null);
+      if (ack && typeof ack.watching === "boolean") {
+        liveFrameWatchedByProject.set(frameProjectId, ack.watching);
+      }
     }).catch(() => {
     }).finally(() => {
       liveFramePushInFlight.delete(frame.sessionId);

package/dist/cli.mjs

@@ -1912,7 +1912,7 @@ function isValidLiveFrame(frame) {
     return false;
   return true;
 }
-var readEnvInt, LIVE_FRAME_PUSH_MAX_BASE64_BYTES, LIVE_THUMBNAIL_MAX_BASE64_BYTES, LIVE_FRAME_MAX_DIMENSION, LIVE_FRAME_JPEG_QUALITY, LIVE_FRAME_MIN_PUSH_INTERVAL_MS, LIVE_FRAME_UNFOCUSED_INTERVAL_MS, LIVE_FRAME_STALE_MS, LIVE_FRAME_MAX_SESSIONS_PER_PROJECT, MOBILE_MJPEG_SETTINGS, MOBILE_MJPEG_FIRST_FRAME_TIMEOUT_MS, MOBILE_MJPEG_MAX_FRAME_BYTES;
+var readEnvInt, LIVE_FRAME_PUSH_MAX_BASE64_BYTES, LIVE_THUMBNAIL_MAX_BASE64_BYTES, LIVE_FRAME_MAX_DIMENSION, LIVE_FRAME_JPEG_QUALITY, LIVE_FRAME_MIN_PUSH_INTERVAL_MS, LIVE_FRAME_UNFOCUSED_INTERVAL_MS, LIVE_FRAME_IDLE_PUSH_INTERVAL_MS, LIVE_FRAME_STALE_MS, LIVE_FRAME_MAX_SESSIONS_PER_PROJECT, MOBILE_MJPEG_SETTINGS, MOBILE_MJPEG_FIRST_FRAME_TIMEOUT_MS, MOBILE_MJPEG_MAX_FRAME_BYTES;
 var init_live_frame = __esm({
   "../shared/dist/live-frame.js"() {
     "use strict";
@@ -1928,6 +1928,7 @@ var init_live_frame = __esm({
     LIVE_FRAME_JPEG_QUALITY = readEnvInt("LIVE_FRAME_JPEG_QUALITY", 55);
     LIVE_FRAME_MIN_PUSH_INTERVAL_MS = readEnvInt("LIVE_FRAME_MIN_PUSH_INTERVAL_MS", 125);
     LIVE_FRAME_UNFOCUSED_INTERVAL_MS = readEnvInt("LIVE_FRAME_UNFOCUSED_INTERVAL_MS", 2e3);
+    LIVE_FRAME_IDLE_PUSH_INTERVAL_MS = readEnvInt("LIVE_FRAME_IDLE_PUSH_INTERVAL_MS", 5e3);
     LIVE_FRAME_STALE_MS = readEnvInt("LIVE_FRAME_STALE_MS", 3e4);
     LIVE_FRAME_MAX_SESSIONS_PER_PROJECT = readEnvInt("LIVE_FRAME_MAX_SESSIONS_PER_PROJECT", 32);
     MOBILE_MJPEG_SETTINGS = {
@@ -6365,6 +6366,7 @@ __export(dist_exports, {
   GROUP_LABELS: () => GROUP_LABELS,
   LEGACY_TTS_MODEL_MAP: () => LEGACY_TTS_MODEL_MAP,
   LEGACY_TTS_VOICE_ID_MAP: () => LEGACY_TTS_VOICE_ID_MAP,
+  LIVE_FRAME_IDLE_PUSH_INTERVAL_MS: () => LIVE_FRAME_IDLE_PUSH_INTERVAL_MS,
   LIVE_FRAME_JPEG_QUALITY: () => LIVE_FRAME_JPEG_QUALITY,
   LIVE_FRAME_MAX_DIMENSION: () => LIVE_FRAME_MAX_DIMENSION,
   LIVE_FRAME_MAX_SESSIONS_PER_PROJECT: () => LIVE_FRAME_MAX_SESSIONS_PER_PROJECT,
@@ -321056,6 +321058,7 @@ var require_primary_action_ledger = __commonJS({
     exports.isLedgerActive = isLedgerActive;
     exports.isGateEnforcing = isGateEnforcing;
     exports.isSteeringActive = isSteeringActive;
+    exports.isPrimaryActionCoverageGapEnabled = isPrimaryActionCoverageGapEnabled;
     exports.leadingVerb = leadingVerb;
     exports.classifyPrimaryAction = classifyPrimaryAction;
     exports.containerScopeOf = containerScopeOf;
@@ -321070,6 +321073,8 @@ var require_primary_action_ledger = __commonJS({
     exports.classifyActionOutcome = classifyActionOutcome;
     exports.detectPrimaryActions = detectPrimaryActions;
     exports.summarizeLedger = summarizeLedger;
+    exports.summarizeUnexercisedPrimaries = summarizeUnexercisedPrimaries;
+    exports.buildUnexercisedPrimaryCoverageGaps = buildUnexercisedPrimaryCoverageGaps;
     var reveal_diff_js_1 = require_reveal_diff();
     var exploration_parser_js_1 = require_exploration_parser();
     function getPrimaryActionGateMode(env = process.env) {
@@ -321089,6 +321094,10 @@ var require_primary_action_ledger = __commonJS({
     function isSteeringActive(mode) {
       return mode === "advisory" || mode === "enforce";
     }
+    function isPrimaryActionCoverageGapEnabled(env = process.env) {
+      const raw = (env.DISCOVERY_PRIMARY_ACTION_COVERAGE_GAP ?? "").trim().toLowerCase();
+      return raw === "1" || raw === "true" || raw === "on" || raw === "enabled";
+    }
     exports.PRIMARY_ACTION_VERB_RE = /^(run|analyze|analyse|generate|regenerate|process|submit|save|create|send|upload|search|export|import|calculate|recalculate|compute|convert|start|scan|translate|transcribe|render|publish|sync|deploy|enrich|summar(?:ize|ise))\b/i;
     exports.AMBIGUOUS_ACTION_VERB_RE = /^(continue|next|apply|go|proceed|confirm|update|add|edit|ok|done|finish|complete|approve|enable|activate)\b/i;
     exports.DESTRUCTIVE_ACTION_VERB_RE = /^(delete|remove|archive|reset|disconnect|deactivate|destroy|purge|revoke|discard|drop|wipe|erase|unsubscribe|cancel|clear|trash)\b/i;
@@ -321352,6 +321361,47 @@ var require_primary_action_ledger = __commonJS({
       }
       return `actions=${c.total} primary{detected=${c.detected} attempted=${c.attempted} captured=${c.captured} blocked=${c.blocked} exempt=${c.exempt}} ambiguous=${c.ambiguous}`;
     }
+    function summarizeUnexercisedPrimaries(ledger, routeInScope, cap = 12) {
+      const out = [];
+      for (const e of getBlockingActionDebt(ledger, routeInScope)) {
+        if (e.status !== "DETECTED" && e.status !== "ATTEMPTED")
+          continue;
+        out.push({ label: e.label, route: e.route, containerScope: e.containerScope, status: e.status });
+        if (out.length >= cap)
+          break;
+      }
+      return out;
+    }
+    var REGEXP_META_RE = /[.*+?^${}()|[\]\\]/g;
+    function labelCoveredByPlan(normLabel, plannedLower) {
+      if (!normLabel.includes(" "))
+        return false;
+      const escaped = normLabel.replace(REGEXP_META_RE, "\\$&");
+      return new RegExp(`(^|\\W)${escaped}($|\\W)`).test(plannedLower);
+    }
+    function buildUnexercisedPrimaryCoverageGaps(unexercised, plannedScenarioText, nowIso) {
+      const gaps = [];
+      const seen = /* @__PURE__ */ new Set();
+      const planned = plannedScenarioText.toLowerCase();
+      for (const a of unexercised) {
+        const norm = normLabelKey(a.label);
+        const key = `${norm}|${a.route}`;
+        if (seen.has(key))
+          continue;
+        seen.add(key);
+        if (labelCoveredByPlan(norm, planned))
+          continue;
+        const clickedNote = a.status === "ATTEMPTED" ? "clicked, but no result state was captured" : "never clicked";
+        gaps.push({
+          scenarioName: `Exercise "${a.label}"`,
+          reason: `Primary action "${a.label}" was detected on ${a.route} but never exercised to an observed result (${clickedNote}).`,
+          suggestion: `Exercise "${a.label}" to a captured result \u2014 open its result modal/panel and capture it BEFORE closing \u2014 or schedule a deep run scoped to this action, so a real test can be authored.`,
+          unmetPrerequisites: [],
+          detectedAt: nowIso
+        });
+      }
+      return gaps;
+    }
   }
 });
 
@@ -322840,6 +322890,9 @@ var require_exploration_prompt_builder = __commonJS({
         "These are the feature's core actions \u2014 what it EXISTS to do. You are on a PROVISIONED TEST ACCOUNT, so exercising them is the point of this exploration. For each: click it, wait for it to finish (an async job can take 10-60s \u2014 keep waiting and capturing, do not give up early), then capture_page the result (a new panel, row, score, status, or route change).",
         `Spending in-app COMPUTE credits is expected and budgeted \u2014 running an Analyze / Generate / Run / Process ONCE to observe its output is exactly what you should do; an "N of M used" usage or AI-credit meter is NOT a reason to skip. These were auto-screened, but YOU are the final check: if you can see a specific listed action actually charges REAL money at a checkout (Buy / Upgrade / Subscribe), makes an irreversible or destructive change (Delete / Wipe / Deploy to production), or sends a message to real people (Send email / Invite), SKIP just that one \u2014 note it as blocked with the reason and move on. Don't finish until every other action below has produced an observed outcome:`
       ];
+      if ((0, primary_action_ledger_js_1.isPrimaryActionCoverageGapEnabled)()) {
+        out.push("If the result opens in a modal, dialog, or panel, call capture_page WHILE IT IS STILL OPEN \u2014 do not close or dismiss it first, or the result state is never recorded and the action does not count as covered. An action reachable only from inside this feature's own result modal is in-scope: exercise it to a captured result before closing, even if it generates content that belongs to another builder.");
+      }
       for (const e of debt.slice(0, 8)) {
         const note = e.status === "ATTEMPTED" ? " \u2014 clicked but no result captured yet" : "";
         out.push(`  - "${e.label}" on ${e.route}${note}`);
@@ -326660,6 +326713,7 @@ ${inbox_tools_js_1.EMAIL_VERIFICATION_UNAVAILABLE_OVERRIDE_BLOCK}` : ""}`;
       const primaryActionMode = (0, primary_action_ledger_js_1.getPrimaryActionGateMode)();
       const primaryActionLedgerActive = (0, primary_action_ledger_js_1.isLedgerActive)(primaryActionMode) && options?.mode === "deep";
       const primaryActionEnforcing = primaryActionLedgerActive && (0, primary_action_ledger_js_1.isGateEnforcing)(primaryActionMode);
+      const primaryActionCoverageGapEnabled = primaryActionLedgerActive && (0, primary_action_ledger_js_1.isPrimaryActionCoverageGapEnabled)();
       const prevRouteSignatures = /* @__PURE__ */ new Map();
       const prevInteractionCountsByRoute = /* @__PURE__ */ new Map();
       let previousCaptureRoute = null;
@@ -326670,6 +326724,16 @@ ${inbox_tools_js_1.EMAIL_VERIFICATION_UNAVAILABLE_OVERRIDE_BLOCK}` : ""}`;
       let finishBounce = (0, survey_link_frontier_js_1.initialFinishBounceState)();
       let lastLandedPageUrl = null;
       const state2 = (0, exploration_state_js_1.createExplorationState)();
+      const buildUnexercisedPrimarySummary = () => {
+        if (!primaryActionCoverageGapEnabled)
+          return void 0;
+        const fa = options?.focusAreas ?? [];
+        if (fa.length === 0)
+          return void 0;
+        const otherRoutes = options?.featureContext?.otherFeatures?.flatMap((f) => f.pages);
+        const summary2 = (0, primary_action_ledger_js_1.summarizeUnexercisedPrimaries)(state2.actionLedger, (r) => (0, exploration_parser_js_1.routeIsWithinFocusAreas)(r, fa, otherRoutes), 12);
+        return summary2.length > 0 ? summary2 : void 0;
+      };
       function ingestLinksFromText(rawText) {
         if (!linkFrontierEnabled || !rawText || !rawText.includes("- /url:"))
           return;
@@ -328900,6 +328964,7 @@ Exploration ended after ${iteration} iterations without calling finish_explorati
             summary: state2.summary || summary,
             collectedPages: state2.collectedPages,
             collectedTransitions: state2.collectedTransitions,
+            unexercisedPrimaryActions: buildUnexercisedPrimarySummary(),
             iterationTimeline: iterationTimeline.length > 0 ? iterationTimeline : void 0
           };
         }
@@ -328994,6 +329059,7 @@ Fatal error: ${msg}`);
             summary: `Fatal error: ${msg}`,
             collectedPages: state2.collectedPages,
             collectedTransitions: state2.collectedTransitions,
+            unexercisedPrimaryActions: buildUnexercisedPrimarySummary(),
             iterationTimeline: iterationTimeline.length > 0 ? iterationTimeline : void 0,
             truncated: true,
             truncatedReason,
@@ -337180,6 +337246,7 @@ var require_discover_agent = __commonJS({
     var discover_planner_js_1 = require_discover_planner();
     var discover_generator_js_1 = require_discover_generator();
     var discover_ai_planner_js_1 = require_discover_ai_planner();
+    var primary_action_ledger_js_1 = require_primary_action_ledger();
     var discovery_lint_flags_js_1 = require_discovery_lint_flags();
     var verification_inbox_js_1 = require_verification_inbox();
     var inbox_tools_js_1 = require_inbox_tools();
@@ -338482,6 +338549,16 @@ Plan: ${planResult.scenarios.length} scenarios (budget: ${featureTestBudget})`);
           checkpointFallbackReason = planResult.fallbackReason;
           plannerWarning = planResult.warning;
           plannerCoverageGaps = planResult.coverageGaps;
+          const unexercisedPrimaries = exploreResult.unexercisedPrimaryActions ?? [];
+          if (unexercisedPrimaries.length > 0) {
+            const plannedText = planResult.scenarios.map((s) => `${s.name} ${s.goal ?? ""} ${(s.targetPages ?? []).join(" ")}`).join(" ");
+            const ledgerGaps = (0, primary_action_ledger_js_1.buildUnexercisedPrimaryCoverageGaps)(unexercisedPrimaries, plannedText, (/* @__PURE__ */ new Date()).toISOString());
+            if (ledgerGaps.length > 0) {
+              plannerCoverageGaps = [...plannerCoverageGaps ?? [], ...ledgerGaps];
+            }
+            const suppressed = unexercisedPrimaries.length - ledgerGaps.length;
+            logs2.push(`  [primary-action-ledger] ${unexercisedPrimaries.length} in-scope primary action(s) un-exercised; surfaced ${ledgerGaps.length} as coverage gap(s)${suppressed > 0 ? ` (${suppressed} already covered by the plan / deduped)` : ""}`);
+          }
         }
         if (callbackOptions?.onPlanReady) {
           try {
@@ -353265,7 +353342,7 @@ var require_package4 = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@validate.qa/runner",
-      version: "1.0.79",
+      version: "1.0.81",
       description: "validate local test runner - execute Playwright tests on your machine, connected to validate.qa cloud.",
       bin: {
         "validate-runner": "dist/cli.js"
@@ -353534,6 +353611,9 @@ async function enforceRunnerUpToDate(currentVersion, opts = {}) {
   return result;
 }
 
+// src/runner.ts
+init_dist();
+
 // src/services/appium-executor.ts
 init_dist();
 
@@ -358898,6 +358978,7 @@ function startMjpegStream(options) {
 // src/services/mobile-bridge.ts
 init_dist();
 var MOBILE_BRIDGE_PORT2 = 9515;
+var RELAY_DEMAND_POLL_MS = 2e3;
 var MAX_REQUEST_BODY_BYTES = 64 * 1024;
 var MAX_TEXT_INPUT_LENGTH = 4e3;
 var MAX_APP_ID_LENGTH = 255;
@@ -359409,6 +359490,18 @@ async function handleSessionStop(_req, res) {
   sendJSON(res, 200, { ok: true });
 }
 var runnerChannels = /* @__PURE__ */ new Map();
+var relayDemandTimer = null;
+function setMirrorRelay(deviceId, relay) {
+  const ch = runnerChannels.get(deviceId);
+  if (!ch) return;
+  ch.relay = relay;
+  if (relay) {
+    ensureRelayDemandSupervisor();
+    if (hasChannelDemand(ch)) ensureChannelPolling(ch);
+  } else {
+    stopChannelCaptureIfIdle(ch);
+  }
+}
 function readDeviceIdParam(req) {
   try {
     const url = new URL(req.url || "", "http://localhost");
@@ -359440,7 +359533,7 @@ function writeFrameToChannelClient(ch, client, frame) {
       } catch {
       }
       ch.clients.delete(client);
-      stopChannelPollingIfIdle(ch);
+      stopChannelCaptureIfIdle(ch);
       return;
     }
     client.write(`data: ${JSON.stringify(frame)}
@@ -359452,6 +359545,12 @@ function writeFrameToChannelClient(ch, client, frame) {
 function broadcastChannelFrame(ch, frame) {
   ch.lastFrame = frame;
   for (const client of ch.clients) writeFrameToChannelClient(ch, client, frame);
+  if (ch.relay && frame.screenshot) {
+    try {
+      ch.relay.onFrame(frame.screenshot, frame.mimeType ?? "image/png");
+    } catch {
+    }
+  }
 }
 function tryStartChannelMjpeg(ch) {
   if (ch.mjpeg || ch.mjpegStarting || ch.mjpegUnavailable) return;
@@ -359489,7 +359588,7 @@ function tryStartChannelMjpeg(ch) {
       ch.mjpeg = null;
       ch.mjpegStarting = false;
       ch.mjpegUnavailable = true;
-      if (wasActive && ch.clients.size > 0) ensureChannelPolling(ch);
+      if (wasActive && hasChannelDemand(ch)) ensureChannelPolling(ch);
     }
   });
   const firstFrameDeadline = setTimeout(() => {
@@ -359497,12 +359596,30 @@ function tryStartChannelMjpeg(ch) {
     ch.mjpegStarting = false;
     ch.mjpegUnavailable = true;
     handle.stop();
-    if (ch.clients.size > 0) ensureChannelPolling(ch);
+    if (hasChannelDemand(ch)) ensureChannelPolling(ch);
   }, MOBILE_MJPEG_FIRST_FRAME_TIMEOUT_MS);
   firstFrameDeadline.unref?.();
 }
+function hasChannelDemand(ch) {
+  if (ch.clients.size > 0) return true;
+  return ch.relay !== null;
+}
+function ensureRelayDemandSupervisor() {
+  if (relayDemandTimer) return;
+  relayDemandTimer = setInterval(() => {
+    for (const ch of [...runnerChannels.values()]) {
+      if (hasChannelDemand(ch)) ensureChannelPolling(ch);
+      else stopChannelCaptureIfIdle(ch);
+    }
+    if (runnerChannels.size === 0 && relayDemandTimer) {
+      clearInterval(relayDemandTimer);
+      relayDemandTimer = null;
+    }
+  }, RELAY_DEMAND_POLL_MS);
+  relayDemandTimer.unref?.();
+}
 async function pollRunnerChannel(ch) {
-  if (ch.clients.size === 0 || ch.polling) return;
+  if (!hasChannelDemand(ch) || ch.polling) return;
   if (ch.mjpeg) return;
   ch.polling = true;
   try {
@@ -359533,6 +359650,7 @@ async function pollRunnerChannel(ch) {
   }
 }
 function ensureChannelPolling(ch) {
+  if (!hasChannelDemand(ch)) return;
   tryStartChannelMjpeg(ch);
   if (ch.mjpeg || ch.pollTimer) return;
   ch.pollTimer = setInterval(() => {
@@ -359540,8 +359658,8 @@ function ensureChannelPolling(ch) {
   }, MOBILE_SCREENSHOT_INTERVAL_MS);
   ch.pollTimer.unref?.();
 }
-function stopChannelPollingIfIdle(ch) {
-  if (ch.clients.size > 0) return;
+function stopChannelCaptureIfIdle(ch) {
+  if (hasChannelDemand(ch)) return;
   if (ch.pollTimer) {
     clearInterval(ch.pollTimer);
     ch.pollTimer = null;
@@ -359560,6 +359678,7 @@ function closeRunnerChannel(ch) {
     ch.mjpeg.stop();
     ch.mjpeg = null;
   }
+  ch.relay = null;
   for (const client of ch.clients) {
     try {
       client.end();
@@ -359568,7 +359687,7 @@ function closeRunnerChannel(ch) {
   }
   ch.clients.clear();
   ch.lastFrame = null;
-  runnerChannels.delete(ch.deviceId);
+  if (runnerChannels.get(ch.deviceId) === ch) runnerChannels.delete(ch.deviceId);
 }
 function closeAllRunnerChannels() {
   for (const ch of [...runnerChannels.values()]) closeRunnerChannel(ch);
@@ -359590,7 +359709,7 @@ async function serveRunnerMirror(req, res, ch) {
   }
   req.on("close", () => {
     ch.clients.delete(res);
-    stopChannelPollingIfIdle(ch);
+    stopChannelCaptureIfIdle(ch);
   });
 }
 async function handleMirror(req, res) {
@@ -360148,7 +360267,8 @@ function attachMirrorSession(sessionId, platform3, deviceId) {
       mjpeg: null,
       mjpegLastFrameAt: 0,
       mjpegStarting: false,
-      mjpegUnavailable: false
+      mjpegUnavailable: false,
+      relay: null
     };
     ch.sessionId = sessionId;
     ch.platform = platform3;
@@ -360162,7 +360282,7 @@ function attachMirrorSession(sessionId, platform3, deviceId) {
     runnerChannels.set(deviceId, ch);
     void applyMjpegSettings(`/session/${sessionId}`, MOBILE_MJPEG_SETTINGS).catch(() => {
     });
-    if (ch.clients.size > 0) {
+    if (hasChannelDemand(ch)) {
       ensureChannelPolling(ch);
       void pollRunnerChannel(ch);
     }
@@ -361134,6 +361254,13 @@ function attachMobileDiscoveryNetworkContext(calls, result, appId) {
   }));
 }
 var runnerPackage = require_package4();
+var MIRROR_RELAY_FRESH_MS = 3e3;
+var liveFrameWatchedByProject = /* @__PURE__ */ new Map();
+var liveFrameIdleProbeAt = /* @__PURE__ */ new Map();
+var LIVE_FRAME_IDLE_PROBE_MAX_ENTRIES = 256;
+function isLiveFrameWatched(projectId) {
+  return !projectId || liveFrameWatchedByProject.get(projectId) !== false;
+}
 var SECRET_VAR_PATTERN = /password|secret|token|api[_]?key|pass\b|credential|bearer|pat\b/i;
 var IS_CLOUD = parseBoolFlag(process.env.RUNNER_CLOUD);
 var RUNNER_NAME = runnerPackage.name ?? "@validate.qa/runner";
@@ -361911,6 +362038,22 @@ async function executeRun(run2, opts, headers, requestLiveBrowserHeartbeat = ()
     testCaseId: run2.testCaseId ?? void 0
   });
   requestLiveBrowserHeartbeat(true);
+  let lastMirrorRelayFrameAt = 0;
+  const attachMirrorWithRelay = (sessionId, platform3, deviceId) => {
+    attachMirrorSession(sessionId, platform3, deviceId);
+    if (!deviceId) return;
+    setMirrorRelay(deviceId, {
+      onFrame: (base64, mimeType) => {
+        lastMirrorRelayFrameAt = Date.now();
+        liveBrowserHandle.updateSnapshot({
+          thumbnailJpegBase64: base64,
+          thumbnailCapturedAt: Date.now(),
+          mimeType
+        });
+      },
+      wanted: () => isLiveFrameWatched(run2.projectId)
+    });
+  };
   const liveBrowserHeartbeatInterval = setInterval(() => {
     liveBrowserHandle.patch({});
     requestLiveBrowserHeartbeat();
@@ -362814,7 +362957,7 @@ ${finalVerifyResult.logs ?? ""}`;
               deeplink: harvestTarget.deeplink
             },
             onSessionReady: (sessionId, deviceId, sessionPlatform) => {
-              attachMirrorSession(sessionId, sessionPlatform, deviceId);
+              attachMirrorWithRelay(sessionId, sessionPlatform, deviceId);
               const name = getCachedDeviceSnapshot().find((d) => d.id === deviceId)?.name;
               liveBrowserHandle.patch({ deviceId, ...name ? { deviceName: name } : {} });
               requestLiveBrowserHeartbeat(true);
@@ -363284,7 +363427,7 @@ ${finalVerifyResult.logs ?? ""}`;
               }
             );
             mobileOnLog(`Appium session created: ${session.sessionId} on device ${session.deviceId}`);
-            attachMirrorSession(session.sessionId, platform3, session.deviceId);
+            attachMirrorWithRelay(session.sessionId, platform3, session.deviceId);
             const driver = new MobileBridgeDriver({
               sessionId: session.sessionId,
               platform: platform3,
@@ -363321,7 +363464,7 @@ ${finalVerifyResult.logs ?? ""}`;
                   throw new Error("discovery teardown started during session recovery \u2014 replacement session closed");
                 }
                 session = replacement;
-                attachMirrorSession(replacement.sessionId, platform3, replacement.deviceId);
+                attachMirrorWithRelay(replacement.sessionId, platform3, replacement.deviceId);
                 liveBrowserHandle.patch({
                   deviceId: replacement.deviceId,
                   deviceName: replacement.deviceName
@@ -363342,6 +363485,10 @@ ${finalVerifyResult.logs ?? ""}`;
               // UI a reliable mobile fallback when the direct bridge SSE is
               // still opening or blocked by the user's network/tunnel.
               onScreenshot: (base64) => {
+                if (Date.now() - lastMirrorRelayFrameAt < MIRROR_RELAY_FRESH_MS) {
+                  liveBrowserHandle.updateSnapshot({ currentUrl: mobileTarget.appId });
+                  return;
+                }
                 liveBrowserHandle.updateSnapshot({
                   currentUrl: mobileTarget.appId,
                   thumbnailJpegBase64: base64,
@@ -363814,7 +363961,7 @@ ${finalVerifyResult.logs ?? ""}`;
                   deeplink: target.deeplink
                 });
                 liveSession = opened;
-                attachMirrorSession(opened.sessionId, target.platform, opened.deviceId);
+                attachMirrorWithRelay(opened.sessionId, target.platform, opened.deviceId);
                 bridgeDriver = new MobileBridgeDriver({
                   sessionId: opened.sessionId,
                   platform: target.platform,
@@ -364004,7 +364151,7 @@ ${finalVerifyResult.logs ?? ""}`;
             // Stream this run to its OWN per-device dashboard tile (keyed by the
             // leased device id) so N parallel Appium runs each show a live mirror.
             onSessionReady: (sessionId, deviceId, sessionPlatform) => {
-              attachMirrorSession(sessionId, sessionPlatform, deviceId);
+              attachMirrorWithRelay(sessionId, sessionPlatform, deviceId);
               requestLiveBrowserHeartbeat(true);
             },
             onSessionEnding: (deviceId) => {
@@ -364596,12 +364743,31 @@ async function startRunner(opts) {
   const publishLiveFrame = (frame) => {
     if (!frame.projectId) return;
     if (liveFramePushInFlight.has(frame.sessionId)) return;
+    if (!isLiveFrameWatched(frame.projectId)) {
+      const lastProbeAt = liveFrameIdleProbeAt.get(frame.sessionId) ?? 0;
+      if (frame.capturedAt - lastProbeAt < LIVE_FRAME_IDLE_PUSH_INTERVAL_MS) return;
+      if (liveFrameIdleProbeAt.size >= LIVE_FRAME_IDLE_PROBE_MAX_ENTRIES) {
+        const expiredBefore = frame.capturedAt - LIVE_FRAME_IDLE_PUSH_INTERVAL_MS;
+        for (const [sessionId, probedAt] of liveFrameIdleProbeAt) {
+          if (probedAt >= expiredBefore) break;
+          liveFrameIdleProbeAt.delete(sessionId);
+        }
+      }
+      liveFrameIdleProbeAt.set(frame.sessionId, frame.capturedAt);
+    }
     liveFramePushInFlight.add(frame.sessionId);
+    const frameProjectId = frame.projectId;
     void fetch(`${serverUrl}/api/runner/live-frame`, {
       method: "POST",
       headers,
       body: JSON.stringify(frame),
       signal: AbortSignal.timeout(5e3)
+    }).then(async (res) => {
+      if (!res.ok) return;
+      const ack = await res.json().catch(() => null);
+      if (ack && typeof ack.watching === "boolean") {
+        liveFrameWatchedByProject.set(frameProjectId, ack.watching);
+      }
     }).catch(() => {
     }).finally(() => {
       liveFramePushInFlight.delete(frame.sessionId);

package/package.json

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