@deeeed/metamask-harness 0.33.3 → 0.34.1

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

@@ -0,0 +1,465 @@
+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 firstFreshDeliveryChecks(records, requirements) {
+  return requirements.map((requirement) => {
+    const stream = String(requirement.stream);
+    const requiredLifecycle =
+      requirement.lifecycle === undefined
+        ? null
+        : String(requirement.lifecycle);
+    const subscriberThrottleMs = Number(requirement.subscriber_throttle_ms);
+    const maxSocketToSubscriberMs = Number(
+      requirement.max_socket_to_subscriber_ms,
+    );
+    const socket = records.find(
+      (record) =>
+        record.stage === 'socket_received' &&
+        record.source === 'fresh_socket' &&
+        record.stream === stream &&
+        (requiredLifecycle === null ||
+          record.lifecycle === requiredLifecycle) &&
+        record.delivery_id,
+    );
+    const delivery = socket
+      ? records.find(
+          (record) =>
+            record.stage === 'subscriber_delivery' &&
+            record.delivery_id === socket.delivery_id &&
+            record.stream === stream &&
+            record.lifecycle === socket.lifecycle &&
+            Number(record.throttle_ms ?? 0) === subscriberThrottleMs,
+        )
+      : null;
+    const socketAt = Number(socket?.monotonic_ms);
+    const subscriberAt = Number(delivery?.monotonic_ms);
+    const socketToSubscriberMs =
+      Number.isFinite(socketAt) && Number.isFinite(subscriberAt)
+        ? roundMs(subscriberAt - socketAt)
+        : null;
+    return {
+      stream,
+      lifecycle: socket?.lifecycle ?? requiredLifecycle,
+      subscriberThrottleMs,
+      maxSocketToSubscriberMs,
+      deliveryId: socket?.delivery_id ?? null,
+      socketToSubscriberMs,
+      status:
+        socketToSubscriberMs !== null &&
+        socketToSubscriberMs <= maxSocketToSubscriberMs
+          ? 'pass'
+          : 'fail',
+    };
+  });
+}
+
+function summarize(
+  records,
+  sourcePath,
+  offset,
+  bytesScanned,
+  requiredFreshContentVariants = [],
+  firstFreshDeliveryRequirements = [],
+) {
+  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),
+    firstFreshDeliveryChecks: firstFreshDeliveryChecks(
+      records,
+      firstFreshDeliveryRequirements,
+    ),
+  };
+}
+
+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 firstFreshDeliveryRequirements = Array.isArray(
+    node.first_fresh_delivery_requirements,
+  )
+    ? node.first_fresh_delivery_requirements
+    : [];
+  const deliveryChecks = firstFreshDeliveryChecks(
+    records,
+    firstFreshDeliveryRequirements,
+  );
+  const failedFirstFreshDeliveries = deliveryChecks.filter(
+    (check) => check.status === 'fail',
+  );
+
+  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 &&
+      failedFirstFreshDeliveries.length === 0
+        ? 'pass'
+        : 'fail',
+    requireRecords,
+    missingStages,
+    missingLifecycles,
+    missingSources,
+    missingFreshContentVariants,
+    failedFirstFreshDeliveries,
+  };
+  const summary = {
+    ...summarize(
+      records,
+      sourcePath,
+      offset,
+      content.length - offset,
+      requiredFreshContentVariants,
+      firstFreshDeliveryRequirements,
+    ),
+    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(', ')}.`,
+    );
+  }
+  if (failedFirstFreshDeliveries.length > 0) {
+    const failures = failedFirstFreshDeliveries.map(
+      (check) =>
+        `${check.stream}/${check.lifecycle ?? 'any'} throttle=${check.subscriberThrottleMs}ms ` +
+        `measured=${check.socketToSubscriberMs ?? 'missing'}ms max=${check.maxSocketToSubscriberMs}ms`,
+    );
+    throw new Error(
+      `First fresh ${MARKER} delivery requirements failed: ${failures.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

@@ -23,6 +23,41 @@ export const MOBILE_BRIDGE_ERROR_CODES = BRIDGE_ERROR_CODES;
 
 const execFileAsync = promisify(execFile);
 
+let adapterActionActive = false;
+let actionBridgeLockPath = null;
+
+function resolveBridgeLockPath(input, env) {
+  const configuredRuntime = env.RECIPE_RUNTIME_DIR;
+  const runtime = configuredRuntime
+    ? (path.isAbsolute(configuredRuntime)
+      ? configuredRuntime
+      : path.resolve(input.context.projectRoot, configuredRuntime))
+    : path.join(input.context.projectRoot, 'temp', 'recipe', 'runtime');
+  return path.join(runtime, 'cdp-bridge.lock');
+}
+
+async function acquireActionBridgeLock(input, env) {
+  if (actionBridgeLockPath) return String(process.pid);
+  const lockPath = resolveBridgeLockPath(input, env);
+  await mkdir(path.dirname(lockPath), { recursive: true });
+  await writeFile(lockPath, String(process.pid));
+  actionBridgeLockPath = lockPath;
+  return String(process.pid);
+}
+
+async function releaseActionBridgeLock() {
+  const lockPath = actionBridgeLockPath;
+  actionBridgeLockPath = null;
+  if (!lockPath) return;
+  try {
+    if ((await readFile(lockPath, 'utf8')).trim() === String(process.pid)) {
+      await rm(lockPath, { force: true });
+    }
+  } catch {
+    // The bridge child or a newer owner may already have replaced the lock.
+  }
+}
+
 // Recover the typed code a cdp-bridge child reported: the stderr marker is
 // authoritative (it carries the class the bridge classified at the source), the
 // coded exit status is the fallback for output-less failures, and a raw message
@@ -52,8 +87,14 @@ export async function writeOutput(input, output) {
 
 export async function runAdapter(callback) {
   const input = await loadInput();
-  const output = await callback(input);
-  await writeOutput(input, output);
+  adapterActionActive = true;
+  try {
+    const output = await callback(input);
+    await writeOutput(input, output);
+  } finally {
+    adapterActionActive = false;
+    await releaseActionBridgeLock();
+  }
 }
 
 function bridgeScript(input) {
@@ -127,7 +168,13 @@ export async function bridgeEnv(input) {
   // (e.g. "Pixel 6" matches Metro deviceName "Pixel 6 - 16 - API 36").
   const serialStr = adbSerial != null ? String(adbSerial) : '';
   const deviceStr = androidDevice != null ? String(androidDevice) : '';
-  if (serialStr && deviceStr === serialStr) {
+  if (
+    shouldResolveAndroidTargetModel(
+      serialStr,
+      deviceStr,
+      androidTargetDeviceName,
+    )
+  ) {
     const model = await resolveAndroidModel(serialStr);
     if (model) {
       env.ANDROID_TARGET_DEVICE_NAME = model;
@@ -150,6 +197,17 @@ export async function bridgeEnv(input) {
   return env;
 }
 
+export function shouldResolveAndroidTargetModel(
+  adbSerial,
+  androidDevice,
+  androidTargetDeviceName,
+) {
+  const serial = String(adbSerial ?? '').trim();
+  const device = String(androidDevice ?? '').trim();
+  const targetName = String(androidTargetDeviceName ?? '').trim();
+  return Boolean(serial && !targetName && (!device || device === serial));
+}
+
 function resolveMobileTarget(input) {
   const contextEnv = input.context?.env || {};
   const watcherPort = input.node?.watcher_port ?? input.node?.metro_port ?? input.node?.cdp_port ?? contextEnv.WATCHER_PORT ?? contextEnv.CDP_PORT ?? contextEnv.RECIPE_CDP_PORT ?? process.env.WATCHER_PORT ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
@@ -314,6 +372,9 @@ export async function bridgeCommand(input, args) {
   const script = bridgeScript(input);
   // bridgeEnv is async: it may call `adb getprop` to resolve the Metro device name.
   const env = await bridgeEnv(input);
+  if (adapterActionActive) {
+    env.CDP_BRIDGE_LOCK_OWNER_PID = await acquireActionBridgeLock(input, env);
+  }
   const result = await new Promise((resolve, reject) => {
     const timeoutMs = Number(input.node?.bridge_timeout_ms ?? input.node?.cdp_timeout_ms ?? process.env.CDP_TIMEOUT ?? 30000);
     const child = spawn(process.execPath, [script, ...args], {
@@ -730,6 +791,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);
@@ -777,6 +839,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 ??