@deeeed/metamask-harness 0.33.2 → 0.34.0

package/library/actions/mobile/perps/performance-capture.mjs

@@ -0,0 +1,383 @@
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const MARKER = '[HomepagePerf]';
+const STATE_FILE = '.homepage-performance-capture.json';
+
+function resolveWithin(root, relativePath, label) {
+  const absoluteRoot = path.resolve(root);
+  const absolutePath = path.resolve(absoluteRoot, relativePath);
+  const relative = path.relative(absoluteRoot, absolutePath);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`${label} must stay within ${absoluteRoot}.`);
+  }
+  return absolutePath;
+}
+
+async function fileSize(file) {
+  try {
+    return (await stat(file)).size;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return 0;
+    throw error;
+  }
+}
+
+function parseRecord(line) {
+  const markerIndex = line.indexOf(MARKER);
+  if (markerIndex < 0) return null;
+  const payload = line.slice(markerIndex + MARKER.length).trim();
+  try {
+    const event = JSON.parse(payload);
+    return event && typeof event === 'object' && !Array.isArray(event) ? event : null;
+  } catch {
+    return null;
+  }
+}
+
+function increment(counts, value) {
+  const key = value == null || value === '' ? 'unknown' : String(value);
+  counts[key] = (counts[key] ?? 0) + 1;
+}
+
+function roundMs(value) {
+  return Number(value.toFixed(3));
+}
+
+function contentVariantSatisfies(actual, required) {
+  if (actual === required) return true;
+  return (
+    actual === 'positions_and_orders' &&
+    (required === 'positions' || required === 'orders')
+  );
+}
+
+function requiredFreshStreams(contentVariant, requiredVariants) {
+  if (requiredVariants.length === 0) return ['positions', 'orders'];
+  const streams = new Set();
+  for (const required of requiredVariants) {
+    if (!contentVariantSatisfies(contentVariant, required)) continue;
+    if (required === 'positions') streams.add('positions');
+    else if (required === 'orders') streams.add('orders');
+    else if (required === 'positions_and_orders') {
+      streams.add('positions');
+      streams.add('orders');
+    } else {
+      // Empty/trending content is derived from both collections.
+      streams.add('positions');
+      streams.add('orders');
+    }
+  }
+  return [...streams];
+}
+
+function visibleMeasurements(records, requiredFreshContentVariants = []) {
+  const demands = records.filter((record) => record.stage === 'viewport_demand');
+  return demands.map((demand) => {
+    const demandId = String(demand.demand_id ?? '');
+    const startedAt = Number(demand.monotonic_ms);
+    const frames = records.filter(
+      (record) =>
+        record.stage === 'next_frame_checkpoint' &&
+        String(record.demand_id ?? '') === demandId,
+    );
+    const frameTimes = frames
+      .map((record) => Number(record.frame_checkpoint_monotonic_ms ?? record.monotonic_ms))
+      .filter(Number.isFinite);
+    const firstVisibleAt = frameTimes.length > 0 ? Math.min(...frameTimes) : null;
+    const firstFreshByStream = {};
+    const freshStreamsSeen = new Set();
+    let freshVisibleAt = null;
+    let freshContentVariant = null;
+    const sortedFrames = [...frames].sort(
+      (left, right) =>
+        Number(left.frame_checkpoint_monotonic_ms ?? left.monotonic_ms) -
+        Number(right.frame_checkpoint_monotonic_ms ?? right.monotonic_ms),
+    );
+    for (const frame of sortedFrames) {
+      const freshVisible =
+        frame.source === 'fresh_socket' ||
+        (frame.source === 'resident_state' &&
+          frame.origin_source === 'fresh_socket' &&
+          frame.fresh_for_lifecycle === true);
+      if (!freshVisible || !frame.stream) continue;
+      const frameAt = Number(frame.frame_checkpoint_monotonic_ms ?? frame.monotonic_ms);
+      if (!Number.isFinite(frameAt)) continue;
+      const stream = String(frame.stream);
+      firstFreshByStream[stream] = Math.min(firstFreshByStream[stream] ?? frameAt, frameAt);
+      freshStreamsSeen.add(stream);
+      const contentVariant = String(frame.content_variant ?? '');
+      const contentMatches =
+        requiredFreshContentVariants.length === 0 ||
+        requiredFreshContentVariants.every((required) =>
+          contentVariantSatisfies(contentVariant, required),
+        );
+      const requiredStreams = requiredFreshStreams(
+        contentVariant,
+        requiredFreshContentVariants,
+      );
+      if (
+        freshVisibleAt === null &&
+        contentMatches &&
+        requiredStreams.length > 0 &&
+        requiredStreams.every((requiredStream) =>
+          freshStreamsSeen.has(requiredStream),
+        )
+      ) {
+        freshVisibleAt = frameAt;
+        freshContentVariant = contentVariant || null;
+      }
+    }
+    if (
+      freshVisibleAt === null &&
+      requiredFreshContentVariants.length === 0 &&
+      firstFreshByStream.positions != null &&
+      firstFreshByStream.orders != null
+    ) {
+      freshVisibleAt = Math.max(firstFreshByStream.positions, firstFreshByStream.orders);
+    }
+    const dataAges = frames.map((record) => Number(record.data_age_ms)).filter(Number.isFinite);
+    return {
+      demandId,
+      lifecycle: demand.lifecycle ?? 'unknown',
+      startedAtMonotonicMs: Number.isFinite(startedAt) ? startedAt : null,
+      firstVisibleAtMonotonicMs: firstVisibleAt,
+      ttcMs:
+        Number.isFinite(startedAt) && firstVisibleAt != null
+          ? roundMs(firstVisibleAt - startedAt)
+          : null,
+      freshVisibleAtMonotonicMs: freshVisibleAt,
+      freshContentVariant,
+      dataReadyAtDemand: sortedFrames.some(
+        (frame) =>
+          frame.data_ready_at_demand === true &&
+          (frame.source === 'fresh_socket' ||
+            (frame.origin_source === 'fresh_socket' && frame.fresh_for_lifecycle === true)),
+      ),
+      dfdMs:
+        Number.isFinite(startedAt) && freshVisibleAt != null
+          ? roundMs(freshVisibleAt - startedAt)
+          : null,
+      deliverySources: [...new Set(frames.map((record) => String(record.source ?? 'unknown')))],
+      contentVariant: frames.find((record) => record.content_variant)?.content_variant ?? null,
+      maxDataAgeMs: dataAges.length > 0 ? Math.max(...dataAges) : null,
+    };
+  });
+}
+
+function socketPipelineMeasurements(records) {
+  const sockets = records.filter(
+    (record) => record.stage === 'socket_received' && record.delivery_id,
+  );
+  return sockets.flatMap((socket) => {
+    const deliveryId = String(socket.delivery_id);
+    const socketAt = Number(socket.monotonic_ms);
+    const commit = records.find(
+      (record) => record.stage === 'react_commit' && String(record.delivery_id ?? '') === deliveryId,
+    );
+    const frame = records.find(
+      (record) => record.stage === 'next_frame_checkpoint' && String(record.delivery_id ?? '') === deliveryId,
+    );
+    if (!commit || !frame || !Number.isFinite(socketAt)) return [];
+    const commitAt = Number(commit.monotonic_ms);
+    const frameAt = Number(frame.frame_checkpoint_monotonic_ms ?? frame.monotonic_ms);
+    const subscriberCandidates = records
+      .filter(
+        (record) =>
+          record.stage === 'subscriber_delivery' &&
+          String(record.delivery_id ?? '') === deliveryId &&
+          Number(record.monotonic_ms) <= commitAt,
+      )
+      .map((record) => Number(record.monotonic_ms))
+      .filter(Number.isFinite);
+    const subscriberAt = subscriberCandidates.length > 0
+      ? Math.max(...subscriberCandidates)
+      : socketAt;
+    return [{
+      deliveryId,
+      stream: socket.stream ?? null,
+      lifecycle: commit.lifecycle ?? socket.lifecycle ?? 'unknown',
+      socketToVisibleMs: roundMs(frameAt - socketAt),
+      socketToSubscriberMs: roundMs(subscriberAt - socketAt),
+      subscriberToCommitMs: roundMs(commitAt - subscriberAt),
+      commitToFrameMs: roundMs(frameAt - commitAt),
+    }];
+  });
+}
+
+function summarize(
+  records,
+  sourcePath,
+  offset,
+  bytesScanned,
+  requiredFreshContentVariants = [],
+) {
+  const stages = {};
+  const lifecycles = {};
+  const streams = {};
+  const sources = {};
+  for (const record of records) {
+    increment(stages, record.stage);
+    increment(lifecycles, record.lifecycle);
+    increment(streams, record.stream);
+    increment(sources, record.source);
+  }
+  const monotonicValues = records
+    .map((record) => Number(record.monotonic_ms))
+    .filter(Number.isFinite);
+  return {
+    schemaVersion: 1,
+    marker: MARKER,
+    sourcePath,
+    offset,
+    bytesScanned,
+    recordCount: records.length,
+    stages,
+    lifecycles,
+    streams,
+    sources,
+    firstMonotonicMs: monotonicValues.length > 0 ? Math.min(...monotonicValues) : null,
+    lastMonotonicMs: monotonicValues.length > 0 ? Math.max(...monotonicValues) : null,
+    visibleMeasurements: visibleMeasurements(records, requiredFreshContentVariants),
+    socketPipelineMeasurements: socketPipelineMeasurements(records),
+  };
+}
+
+export async function captureHomepagePerformance(input) {
+  const node = input.node ?? {};
+  const phase = String(node.phase ?? '').toLowerCase();
+  if (phase !== 'start' && phase !== 'end') {
+    throw new Error('metamask.perps.capture_performance requires phase=start or phase=end.');
+  }
+
+  const projectRoot = input.context?.projectRoot;
+  const artifactsDir = input.context?.artifactsDir;
+  if (!projectRoot || !artifactsDir) {
+    throw new Error('metamask.perps.capture_performance requires projectRoot and artifactsDir.');
+  }
+  const sourcePath = String(node.source_path ?? 'temp/recipe/runtime/app-console.log');
+  const sourceFile = resolveWithin(projectRoot, sourcePath, 'source_path');
+  const stateFile = resolveWithin(artifactsDir, STATE_FILE, 'capture state');
+  await mkdir(artifactsDir, { recursive: true });
+
+  if (phase === 'start') {
+    const offset = await fileSize(sourceFile);
+    await writeFile(stateFile, `${JSON.stringify({ sourcePath, offset }, null, 2)}\n`);
+    return { phase, sourcePath, offset };
+  }
+
+  let state;
+  try {
+    state = JSON.parse(await readFile(stateFile, 'utf8'));
+  } catch (error) {
+    throw new Error(
+      'metamask.perps.capture_performance phase=end requires a successful phase=start in the same recipe run.',
+      { cause: error },
+    );
+  }
+  if (state.sourcePath !== sourcePath || !Number.isInteger(state.offset) || state.offset < 0) {
+    throw new Error('metamask.perps.capture_performance capture state is invalid or uses a different source_path.');
+  }
+
+  const content = await readFile(sourceFile);
+  const offset = state.offset <= content.length ? state.offset : 0;
+  const segment = content.subarray(offset).toString('utf8');
+  const lines = segment.split(/\r?\n/u).filter((line) => line.includes(MARKER));
+  const records = lines.map(parseRecord).filter(Boolean);
+  const requireRecords = node.require_records !== false;
+  const requiredStages = Array.isArray(node.required_stages)
+    ? node.required_stages.map(String)
+    : [];
+  const presentStages = new Set(records.map((record) => String(record.stage ?? '')));
+  const missingStages = requiredStages.filter((stage) => !presentStages.has(stage));
+  const requiredLifecycles = Array.isArray(node.required_lifecycles)
+    ? node.required_lifecycles.map(String)
+    : [];
+  const presentLifecycles = new Set(records.map((record) => String(record.lifecycle ?? '')));
+  const missingLifecycles = requiredLifecycles.filter(
+    (lifecycle) => !presentLifecycles.has(lifecycle),
+  );
+  const requiredSources = Array.isArray(node.required_sources)
+    ? node.required_sources.map(String)
+    : [];
+  const presentSources = new Set(records.map((record) => String(record.source ?? '')));
+  const missingSources = requiredSources.filter((source) => !presentSources.has(source));
+  const requiredFreshContentVariants = Array.isArray(node.required_fresh_content_variants)
+    ? node.required_fresh_content_variants.map(String)
+    : [];
+  const measurements = visibleMeasurements(records, requiredFreshContentVariants);
+  const presentFreshContentVariants = new Set(
+    measurements
+      .filter((measurement) => measurement.dfdMs !== null)
+      .map((measurement) => String(measurement.freshContentVariant ?? '')),
+  );
+  const missingFreshContentVariants = requiredFreshContentVariants.filter(
+    (variant) =>
+      ![...presentFreshContentVariants].some((actual) =>
+        contentVariantSatisfies(actual, variant),
+      ),
+  );
+
+  const prefix = String(node.artifact_prefix ?? 'logs/homepage-performance');
+  const logPath = `${prefix}.log`;
+  const summaryPath = `${prefix}-summary.json`;
+  const logFile = resolveWithin(artifactsDir, logPath, 'artifact_prefix');
+  const summaryFile = resolveWithin(artifactsDir, summaryPath, 'artifact_prefix');
+  const validation = {
+    status:
+      (!requireRecords || records.length > 0) &&
+      missingStages.length === 0 &&
+      missingLifecycles.length === 0 &&
+      missingSources.length === 0 &&
+      missingFreshContentVariants.length === 0
+        ? 'pass'
+        : 'fail',
+    requireRecords,
+    missingStages,
+    missingLifecycles,
+    missingSources,
+    missingFreshContentVariants,
+  };
+  const summary = {
+    ...summarize(
+      records,
+      sourcePath,
+      offset,
+      content.length - offset,
+      requiredFreshContentVariants,
+    ),
+    validation,
+  };
+  const nodeId = String(input.context?.nodeId ?? 'capture-performance');
+  await mkdir(path.dirname(logFile), { recursive: true });
+  await writeFile(logFile, lines.length > 0 ? `${lines.join('\n')}\n` : '');
+  await writeFile(summaryFile, `${JSON.stringify(summary, null, 2)}\n`);
+  await rm(stateFile, { force: true });
+
+  if (requireRecords && records.length === 0) {
+    throw new Error(`No ${MARKER} records were emitted after the capture started.`);
+  }
+  if (missingStages.length > 0) {
+    throw new Error(`Missing required ${MARKER} stages: ${missingStages.join(', ')}.`);
+  }
+  if (missingLifecycles.length > 0) {
+    throw new Error(`Missing required ${MARKER} lifecycles: ${missingLifecycles.join(', ')}.`);
+  }
+  if (missingSources.length > 0) {
+    throw new Error(`Missing required ${MARKER} sources: ${missingSources.join(', ')}.`);
+  }
+  if (missingFreshContentVariants.length > 0) {
+    throw new Error(
+      `Missing required fresh ${MARKER} content variants: ${missingFreshContentVariants.join(', ')}.`,
+    );
+  }
+
+  return {
+    phase,
+    ...summary,
+    artifacts: [
+      { path: logPath, type: 'log', nodeId },
+      { path: summaryPath, type: 'report', nodeId },
+    ],
+  };
+}

package/library/actions/mobile/perps/perps.mjs

@@ -139,6 +139,21 @@ async function readOpenOrders(input) {
   return orders;
 }
 
+async function clearPerformanceCaches(input) {
+  return evalAsync(
+    input,
+    `(function(){
+      var bridge = globalThis.__AGENTIC__;
+      if (!bridge || typeof bridge.clearPerpsPerformanceCaches !== 'function') {
+        throw new Error('__AGENTIC__.clearPerpsPerformanceCaches is unavailable; reload the current Mobile development source.');
+      }
+      return Promise.resolve(bridge.clearPerpsPerformanceCaches()).then(function(result){
+        return JSON.stringify(result);
+      });
+    })()`,
+  );
+}
+
 async function waitForPositionsAbsent(input, symbols, timeoutMs = 30000) {
   const deadline = Date.now() + timeoutMs;
   let last = [];
@@ -830,6 +845,7 @@ const DIRECT_ACTIONS = new Map([
   ['metamask.perps.place_order', placeOrder],
   ['metamask.perps.ensure_positions', ensurePositions],
   ['metamask.perps.ensure_orders', ensureOrders],
+  ['metamask.perps.clear_performance_caches', clearPerformanceCaches],
   ['metamask.perps.start_state', startState],
   ['metamask.perps.teardown_state', teardownState],
 ]);

package/library/actions/mobile/platform/bridge.mjs

@@ -442,34 +442,188 @@ export async function evalSync(input, expression) {
   return parseMaybeJson(await bridgeCommand(input, ['eval', expression]));
 }
 
+const TARGET_TRANSITION_CODES = new Set([
+  BRIDGE_ERROR_CODES.NO_TARGET,
+  BRIDGE_ERROR_CODES.CDP_TIMEOUT,
+  BRIDGE_ERROR_CODES.WS_CLOSED,
+]);
+
+function isTargetTransition(error) {
+  return TARGET_TRANSITION_CODES.has(error?.code);
+}
+
+function valueContains(actual, expected) {
+  if (Array.isArray(expected)) {
+    return Array.isArray(actual) &&
+      actual.length === expected.length &&
+      expected.every((value, index) => valueContains(actual[index], value));
+  }
+  if (expected && typeof expected === 'object') {
+    return actual && typeof actual === 'object' &&
+      Object.entries(expected).every(([key, value]) => valueContains(actual[key], value));
+  }
+  return Object.is(actual, expected);
+}
+
+function routeMatches(route, expectedRoute, expectedParams) {
+  return routeName(route) === expectedRoute &&
+    (expectedParams === undefined || valueContains(route?.params ?? {}, expectedParams));
+}
+
+function routeTransitionProven(previousRoute, currentRoute, expectedRoute, expectedParams) {
+  if (!previousRoute || !routeMatches(currentRoute, expectedRoute, expectedParams)) return false;
+  if (!routeMatches(previousRoute, expectedRoute, expectedParams)) return true;
+  return Boolean(
+    previousRoute.key &&
+      currentRoute?.key &&
+      previousRoute.key !== currentRoute.key,
+  );
+}
+
+async function waitForNextRouteProbe(deadline) {
+  const remaining = deadline - Date.now();
+  if (remaining > 0) await sleep(Math.min(250, remaining));
+}
+
 export async function navigate(input, route, params = {}, expectedRoute) {
-  const navigation = await bridgeCommand(input, ['navigate', route, JSON.stringify(params)]);
-  const verifiedRoute = String(
-    expectedRoute ??
-      (navigation && typeof navigation === 'object' && navigation.navigated
-        ? navigation.navigated
-        : route),
+  const timeoutMs = Number(input.node?.navigation_timeout_ms ?? 15000);
+  const requestedRoute = String(expectedRoute ?? route);
+  const requestedParams = requestedRoute === String(route) ? params : undefined;
+  const transitionCodes = [];
+  let lastTransitionError = null;
+  let navigateAttempts = 0;
+  let previousRoute = null;
+  let recoveryDeadline = null;
+  let recoveryPending = false;
+
+  try {
+    previousRoute = await bridgeCommand(input, ['get-route']);
+  } catch (error) {
+    if (!isTargetTransition(error)) throw error;
+  }
+
+  while (navigateAttempts < 2 || recoveryPending) {
+    if (recoveryPending) {
+      const deadline = recoveryDeadline ?? Date.now() + timeoutMs;
+      let currentRoute = null;
+      while (Date.now() < deadline) {
+        try {
+          currentRoute = await bridgeCommand(input, ['get-route']);
+          if (currentRoute !== null) break;
+        } catch (error) {
+          if (!isTargetTransition(error)) throw error;
+          lastTransitionError = error;
+          transitionCodes.push(error.code);
+        }
+        await waitForNextRouteProbe(deadline);
+      }
+      if (routeTransitionProven(
+        previousRoute,
+        currentRoute,
+        requestedRoute,
+        requestedParams,
+      )) {
+        return {
+          navigated: route,
+          params,
+          previousRoute,
+          currentRoute,
+          deviceName: null,
+          platform: null,
+          verifiedRoute: requestedRoute,
+          bridgeRecovery: {
+            codes: [...new Set(transitionCodes)],
+            navigateAttempts,
+          },
+        };
+      }
+      if (!previousRoute && routeMatches(currentRoute, requestedRoute, requestedParams)) {
+        break;
+      }
+      recoveryPending = false;
+      if (Date.now() >= deadline || navigateAttempts >= 2) break;
+      previousRoute = currentRoute;
+    }
+
+    navigateAttempts += 1;
+    try {
+      const navigation = await bridgeCommand(
+        input,
+        ['navigate', route, JSON.stringify(params)],
+      );
+      const verifiedRoute = String(
+        expectedRoute ??
+          (navigation && typeof navigation === 'object' && navigation.navigated
+            ? navigation.navigated
+            : route),
+      );
+      const verifiedParams = verifiedRoute === String(route) ? params : undefined;
+      const currentRoute = await waitForRoute(
+        input,
+        verifiedRoute,
+        timeoutMs,
+        verifiedParams,
+      );
+      return {
+        ...navigation,
+        currentRoute,
+        verifiedRoute,
+        ...(transitionCodes.length > 0
+          ? {
+              bridgeRecovery: {
+                codes: [...new Set(transitionCodes)],
+                navigateAttempts,
+              },
+            }
+          : {}),
+      };
+    } catch (error) {
+      if (!isTargetTransition(error)) throw error;
+      lastTransitionError = error;
+      transitionCodes.push(error.code);
+      recoveryDeadline = Date.now() + timeoutMs;
+      recoveryPending = true;
+      await waitForNextRouteProbe(recoveryDeadline);
+    }
+  }
+
+  throw lastTransitionError ?? new Error(
+    `Timed out navigating Mobile to route '${requestedRoute}' after ${timeoutMs}ms.`,
   );
-  const currentRoute = await waitForRoute(input, verifiedRoute, Number(input.node?.navigation_timeout_ms ?? 15000));
-  return { ...navigation, currentRoute, verifiedRoute };
 }
 
 function routeName(route) {
   return route && typeof route === 'object' ? String(route.name ?? '') : '';
 }
 
-export async function waitForRoute(input, expectedRoute, timeoutMs = 15000) {
+export async function waitForRoute(
+  input,
+  expectedRoute,
+  timeoutMs = 15000,
+  expectedParams,
+) {
   const expected = String(expectedRoute);
   const deadline = Date.now() + timeoutMs;
   // lastRoute is null when bridgeCommand returns null (transient: route not yet
   // settled mid-navigation). Null means "not ready yet" — keep polling.
   let lastRoute = null;
+  let lastTransitionError = null;
   let pollCount = 0;
+  const transitionCodes = [];
   while (Date.now() < deadline) {
-    lastRoute = await bridgeCommand(input, ['get-route']);
-    if (routeName(lastRoute) === expected) return lastRoute;
+    try {
+      lastRoute = await bridgeCommand(input, ['get-route']);
+    } catch (error) {
+      if (!isTargetTransition(error)) throw error;
+      lastTransitionError = error;
+      transitionCodes.push(error.code);
+      pollCount += 1;
+      await waitForNextRouteProbe(deadline);
+      continue;
+    }
+    if (routeMatches(lastRoute, expected, expectedParams)) return lastRoute;
     pollCount += 1;
-    await sleep(250);
+    await waitForNextRouteProbe(deadline);
   }
   const target = resolveMobileTarget(input);
   const deviceHint = [
@@ -483,13 +637,18 @@ export async function waitForRoute(input, expectedRoute, timeoutMs = 15000) {
   const lastReply = lastRoute === null
     ? 'empty/undefined (route transiently unavailable — bridge not yet settled)'
     : JSON.stringify(lastRoute);
-  throw new Error(
+  const timeoutError = new Error(
     `Timed out waiting for Mobile route '${expected}' after ${timeoutMs}ms (${pollCount} polls).\n` +
     `  Expected route: ${expected}\n` +
+    `  Expected params: ${expectedParams === undefined ? 'any' : JSON.stringify(expectedParams)}\n` +
     `  Last parsed route: ${JSON.stringify(lastRoute)}\n` +
     `  Last bridge reply: ${lastReply}\n` +
+    `  Bridge transitions: ${transitionCodes.length > 0 ? [...new Set(transitionCodes)].join(', ') : 'none'}\n` +
     `  Device: ${deviceHint}`,
   );
+  throw lastTransitionError
+    ? coded(timeoutError, lastTransitionError.code)
+    : timeoutError;
 }
 
 export async function simulatorScreenshot(input, relPath) {
@@ -571,6 +730,7 @@ async function androidScreenshot(input, relPath) {
     temporaryDirectory = await createScreenshotTemporaryDirectory();
     const adbSerial = await resolveAndroidScreenshotSerial(input);
     const adbPath = resolveMobileToolPath('adb', { required: true });
+    await assertAndroidScreenshotIsAllowed(adbPath, adbSerial);
     let result;
     try {
       result = await runScreenshotProcess(adbPath, ['-s', adbSerial, 'exec-out', 'screencap', '-p'], true);
@@ -618,6 +778,62 @@ async function androidScreenshot(input, relPath) {
   }
 }
 
+async function assertAndroidScreenshotIsAllowed(adbPath, adbSerial) {
+  let result;
+  try {
+    result = await runScreenshotProcess(
+      adbPath,
+      ['-s', adbSerial, 'shell', 'dumpsys', 'window'],
+      false,
+    );
+  } catch (error) {
+    throw new Error(
+      `adb screenshot could not inspect the focused window for ${adbSerial}: ${error instanceof Error ? error.message : String(error)}\n` +
+      `  Next: mm-harness doctor --adapter mobile --device ${adbSerial} --json`,
+    );
+  }
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `adb screenshot could not inspect the focused window for ${adbSerial}: ${result.stderr || result.stdout}\n` +
+      `  Next: mm-harness doctor --adapter mobile --device ${adbSerial} --json`,
+    );
+  }
+
+  const focusMatch = result.stdout.match(/mCurrentFocus=Window\{([^\s}]+)/u);
+  if (!focusMatch) {
+    throw new Error(
+      `adb screenshot could not identify the focused Android window for ${adbSerial}.\n` +
+      '  Next: wake and unlock the selected device, wait for the target screen to settle, then rerun the same mm-harness command.',
+    );
+  }
+
+  const focusedWindowId = focusMatch[1];
+  const windowStart = result.stdout.search(
+    new RegExp(`^\\s*Window #\\d+ Window\\{${escapeRegExp(focusedWindowId)}(?:\\s|\\})`, 'mu'),
+  );
+  const nextWindow = windowStart < 0
+    ? -1
+    : result.stdout.slice(windowStart).search(/\n\s*Window #\d+ Window\{/u);
+  const focusedWindow = windowStart < 0
+    ? ''
+    : result.stdout.slice(
+      windowStart,
+      nextWindow < 0 ? undefined : windowStart + nextWindow,
+    );
+  if (/\b(?:FLAG_)?SECURE\b/u.test(focusedWindow)) {
+    const error = new Error(
+      `Android screenshot is protected by FLAG_SECURE on the focused window for ${adbSerial}; the resulting black image is not valid visual evidence.\n` +
+      '  Next: use a non-protected screen (for MetaMask Mobile, unlock the wallet first), then rerun the same mm-harness command.',
+    );
+    error.code = 'SCREENSHOT_PROTECTED';
+    throw error;
+  }
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+
 async function resolveAndroidScreenshotSerial(input) {
   const contextEnv = input.context?.env || {};
   const explicit = input.node?.adb_serial ??