@deeeed/metamask-harness 0.43.0 → 0.44.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## Unreleased
 
+## 0.44.0 - 2026-08-25
+
+### Fixed
+
+- Remove `cold_disk_cache` from the `perps.performance` lifecycle enum because disk hydration is a cache source within a lifecycle, not a standalone lifecycle.
+- Await promise-returning Mobile `press-test-id` and `set-input` bridge handlers so recipe nodes finish only after the in-app operation settles.
+- Keep Mobile broker commands available while Hermes installs the in-app bridge after a target handoff, instead of reconnecting the inspector until actions time out.
+- Honor `launch --build` when a healthy Mobile runtime is already connected; the explicit native build can no longer return a false pass without invoking the build leaf.
+- Let resident Homepage and short-resume performance recipes finish from the ordered visible-content sequence without requiring a new live takeover.
+- Make Mobile reload stay on the pinned device, fail before an active Android Hermes sampler can abort the app, and fail if the process exits or a replacement target never appears; reload never relaunches the app.
+- Bind run evidence to the executable Harness source, build, bin, package, library, and adapter inputs plus task-local command/config helpers, and reject input drift or symlink swaps.
+- Persist recovery and mutation lists in recipe packages, include a redacted run-scoped application log, reject failed recovery before retrying, and prove lifecycle continuity with native process IDs, including opaque runtimes when requested.
+- Refuse stale Mobile source under every heal policy unless an authored `app.lifecycle restart` reloads it, and invalidate run evidence if recipe, library, or product provenance drifts after preparation.
+- Require Homepage demand, committed UI, resolved content, and live-current frame records before the canonical Mobile Perps performance recipe can pass.
+- Fail a Mobile recipe or action without implicitly restarting Metro or the app; process restarts remain explicit lifecycle actions.
+- Keep one Mobile inspector connection open while React Native replays its console buffer, avoiding repeated `Runtime.enable` requests that can stall Metro after unlock.
+- Allow `metamask.wallet.lock` to use the same visible Android controls on development and opaque clients.
+- Keep account-selection proof attached across the temporary Hermes/CDP stall caused by the account switch itself.
+- Add `metamask.perps.ensure_mode` so recipes can reach Lite or Pro through the visible mode control without inheriting prior device state.
+- Preserve Homepage boundary source and content-variant metadata in performance summaries, and bind recipe manifests to the exact product checkout commit.
+- Accept only structured, generation-coherent Perps live-stream records as performance proof, and keep Mobile wallet and mode probes inside one absolute action deadline.
+- Keep the latest automatic Mobile HUD update in the CDP broker and retry it until the in-app bridge applies it when the pinned Hermes target returns, without restarting the app.
+- Keep the Perps performance recipe's empty-account setup read-only and allow its setup-only prime capture to contain no performance records.
+- Redact quoted JSON credential fields before persisting run-scoped application logs.
+
 ## 0.43.0 - 2026-08-21
 
 ### Added

package/adapters/mobile/bridge-runtime/cdp-bridge.cjs

@@ -18,6 +18,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { execFileSync } = require('node:child_process');
 const { loadPort } = require('./lib/config.cjs');
 const {
   discoverTarget,
@@ -36,6 +37,126 @@ const {
 } = require('./lib/bridge-errors.cjs');
 const { cdpEval, cdpEvalAsync } = require('./lib/cdp-eval.cjs');
 const { buildArmSnippet, buildCollectSnippet } = require('./lib/issue-capture.cjs');
+const APPLY_HUD_UPDATE_FUNCTION = `function(step) {
+  const bridge = this.__AGENTIC__;
+  if (step === null) {
+    if (typeof bridge?.hideStep !== 'function') return false;
+    setTimeout(() => bridge.hideStep(), 0);
+    return true;
+  }
+  if (typeof bridge?.showStep !== 'function') return false;
+  setTimeout(() => bridge.showStep(step), 0);
+  return true;
+}`;
+
+function mobileToolPath(tool) {
+  return process.env[`MM_HARNESS_${tool.toUpperCase()}_PATH`] || tool;
+}
+
+function bootedIosDevice(deviceName) {
+  if (!deviceName) return null;
+  try {
+    const devices = JSON.parse(
+      execFileSync('xcrun', ['simctl', 'list', 'devices', 'available', '-j'], {
+        encoding: 'utf8',
+      }),
+    );
+    const device = Object.values(devices.devices || {})
+      .flat()
+      .find(
+        (candidate) =>
+          (candidate?.name === deviceName || candidate?.udid === deviceName) &&
+          candidate?.state === 'Booted',
+      );
+    return device?.udid ? device : null;
+  } catch {
+    return null;
+  }
+}
+
+function tapVisibleIosAccessibilityTarget(testId, deviceName, platform) {
+  if (platform !== 'ios') return null;
+  const device = bootedIosDevice(deviceName);
+  if (!device) return null;
+  try {
+    const idb = mobileToolPath('idb');
+    const elements = JSON.parse(
+      execFileSync(
+        idb,
+        ['ui', 'describe-all', '--udid', device.udid, '--json'],
+        { encoding: 'utf8' },
+      ),
+    );
+    const windowFrame = elements
+      .map((element) => element?.frame)
+      .filter(
+        (frame) =>
+          frame &&
+          frame.x === 0 &&
+          frame.y === 0 &&
+          frame.width > 0 &&
+          frame.height > 0,
+      )
+      .sort(
+        (first, second) =>
+          second.width * second.height - first.width * first.height,
+      )[0];
+    if (!windowFrame) return null;
+    const target = elements.find((element) => {
+      const frame = element?.frame;
+      return (
+        element?.AXUniqueId === testId &&
+        element?.enabled !== false &&
+        element?.hittable !== false &&
+        frame &&
+        frame.width > 0 &&
+        frame.height > 0 &&
+        frame.x >= 0 &&
+        frame.y >= 0 &&
+        frame.x + frame.width <= windowFrame.width &&
+        frame.y + frame.height <= windowFrame.height
+      );
+    });
+    if (!target) return null;
+    const x = Math.round(target.frame.x + target.frame.width / 2);
+    const y = Math.round(target.frame.y + target.frame.height / 2);
+    execFileSync(
+      idb,
+      ['ui', 'tap', String(x), String(y), '--udid', device.udid],
+      { encoding: 'utf8' },
+    );
+    return { ok: true, testId, deviceName, provider: 'idb-accessibility' };
+  } catch {
+    return null;
+  }
+}
+
+async function applyHudUpdate(client, step) {
+  const globalObject = await client.send('Runtime.evaluate', {
+    expression: 'globalThis',
+    returnByValue: false,
+    awaitPromise: false,
+  });
+  const objectId = globalObject?.result?.objectId;
+  if (!objectId) {
+    throw new Error('Mobile HUD runtime did not expose globalThis');
+  }
+  const result = await client.send('Runtime.callFunctionOn', {
+    objectId,
+    functionDeclaration: APPLY_HUD_UPDATE_FUNCTION,
+    arguments: [{ value: step }],
+    returnByValue: true,
+    awaitPromise: false,
+  });
+  if (result?.exceptionDetails) {
+    throw new Error(
+      result.exceptionDetails.exception?.description ||
+        result.exceptionDetails.text ||
+        'Mobile HUD update failed',
+    );
+  }
+  return result?.result?.value === true;
+}
 
 function parsePerformanceConsoleEvent(params) {
   const markers = ['[PerpsPerf] ', '[HomepagePerf] '];
@@ -97,7 +218,7 @@ async function setInput(client, testId, value, { deviceName } = {}, redact = fal
     throw new Error('Usage: set-input <testId> <value>');
   }
   const expr = `(function() {
-    if (globalThis.__AGENTIC__?.setInput) return globalThis.__AGENTIC__.setInput(${JSON.stringify(testId)}, ${JSON.stringify(value)});
+    if (globalThis.__AGENTIC__?.setInput) return Promise.resolve(globalThis.__AGENTIC__.setInput(${JSON.stringify(testId)}, ${JSON.stringify(value)}));
     var hook = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
     if (!hook) return { ok: false, error: 'No React DevTools hook' };
     var renderers = hook.renderers;
@@ -133,7 +254,7 @@ async function setInput(client, testId, value, { deviceName } = {}, redact = fal
   })()`;
   let result;
   try {
-    result = await cdpEval(client, expr);
+    result = await cdpEvalAsync(client, expr);
   } catch (error) {
     if (redact) {
       throw new Error(`Secret input could not be applied for testID ${testId}.`);
@@ -151,6 +272,26 @@ async function setInput(client, testId, value, { deviceName } = {}, redact = fal
   };
 }
 
+function parseHudStep(args) {
+  const raw = args.join(' ');
+  let step;
+  try {
+    step = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`show-step-json requires a JSON step payload: ${error.message}`);
+  }
+  if (!step || typeof step !== 'object' || Array.isArray(step)) {
+    throw new Error('show-step-json requires a JSON object step payload');
+  }
+  if (typeof step.intent !== 'string' || !step.intent.trim()) {
+    throw new Error('show-step-json requires step.intent');
+  }
+  if (step.id !== undefined && typeof step.id !== 'string') {
+    throw new Error('show-step-json step.id must be a string when provided');
+  }
+  return step;
+}
+
 const COMMANDS = {
   async navigate(client, args, { deviceName, platform } = {}) {
     const routeName = ROUTE_ALIASES[args[0]] || args[0];
@@ -300,14 +441,15 @@ const COMMANDS = {
     return await cdpEval(client, `globalThis.__AGENTIC__?.switchAccount(${JSON.stringify(address)})`);
   },
 
-  async 'press-test-id'(client, args, { deviceName } = {}) {
+  async 'press-test-id'(client, args, { deviceName, platform } = {}) {
     const testId = args[0];
     if (!testId) {
       throw new Error('Usage: press-test-id <testId>');
     }
-    // Try __AGENTIC__ bridge first, fall back to inline fiber walking
+    // Try the app bridge first. Native accessibility remains an iOS fallback
+    // for controls whose React handler cannot be invoked directly.
     const expr = `(function() {
-      if (globalThis.__AGENTIC__?.pressTestId) return globalThis.__AGENTIC__.pressTestId(${JSON.stringify(testId)});
+      if (globalThis.__AGENTIC__?.pressTestId) return Promise.resolve(globalThis.__AGENTIC__.pressTestId(${JSON.stringify(testId)}));
       var hook = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
       if (!hook) return { ok: false, error: 'No React DevTools hook' };
       var renderers = hook.renderers;
@@ -330,10 +472,72 @@ const COMMANDS = {
       }
       return { ok: false, error: 'No component with testID=' + ${JSON.stringify(testId)} + ' found or no onPress' };
     })()`;
-    const result = await cdpEval(client, expr);
+    let result;
+    let bridgeError;
+    try {
+      result = await cdpEvalAsync(client, expr);
+      if (result?.ok !== false) {
+        return { ...result, testId, deviceName };
+      }
+    } catch (error) {
+      bridgeError = error;
+    }
+    const nativeResult = tapVisibleIosAccessibilityTarget(
+      testId,
+      deviceName,
+      platform,
+    );
+    if (nativeResult) return nativeResult;
+    if (bridgeError) throw bridgeError;
     return { ...result, testId, deviceName };
   },
 
+  async 'key-press'(_client, args, { deviceName, platform } = {}) {
+    const requestedKey = String(args[0] || 'Enter').toLowerCase();
+    const isEnter = requestedKey === 'enter' || requestedKey === 'return';
+    const isBack = requestedKey === 'escape' || requestedKey === 'back';
+    if (!isEnter && !isBack) {
+      throw new Error(`Unsupported Mobile key ${JSON.stringify(args[0])}`);
+    }
+    if (platform === 'android') {
+      const serial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL;
+      if (!serial) throw new Error('key-press requires a selected Android device');
+      const keyCode = isEnter ? '66' : '4';
+      execFileSync(
+        mobileToolPath('adb'),
+        ['-s', serial, 'shell', 'input', 'keyevent', keyCode],
+        { encoding: 'utf8' },
+      );
+      return {
+        ok: true,
+        key: args[0] || 'Enter',
+        keyCode,
+        deviceName,
+        provider: 'adb-key',
+      };
+    }
+    if (platform !== 'ios') {
+      throw new Error(`key-press requires a selected Mobile platform`);
+    }
+    const device = bootedIosDevice(deviceName);
+    if (!device) {
+      throw new Error(`No booted simulator named ${JSON.stringify(deviceName)}`);
+    }
+    const keyCode = isEnter ? '40' : '41';
+    execFileSync(
+      mobileToolPath('idb'),
+      ['ui', 'key', keyCode, '--udid', device.udid],
+      { encoding: 'utf8' },
+    );
+    return {
+      ok: true,
+      key: args[0] || 'Enter',
+      keyCode,
+      deviceName,
+      provider: 'idb-key',
+    };
+  },
+
   async 'long-press-test-id'(client, args, { deviceName } = {}) {
     const testId = args[0];
     if (!testId) {
@@ -406,6 +610,9 @@ const COMMANDS = {
       // selector fiber. For into-view requests the scroll container is commonly
       // an ancestor (for example, a Wallet Home section row), so use the
       // ancestor-aware bridge fallback below instead.
+      if (${intoView} && globalThis.__AGENTIC__?.scrollIntoView) {
+        return globalThis.__AGENTIC__.scrollIntoView(${JSON.stringify(testId)}, ${animated});
+      }
       if (!${intoView} && globalThis.__AGENTIC__?.scrollView) return globalThis.__AGENTIC__.scrollView(${optsJson});
       var hook = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
       if (!hook) return { ok: false, error: 'No React DevTools hook' };
@@ -427,14 +634,56 @@ const COMMANDS = {
         }
         return false;
       }
+      function findMeasurable(fiber) {
+        if (!fiber) return null;
+        var sn = fiber.stateNode;
+        if (sn && typeof sn.measureLayout === 'function') return sn;
+        return findMeasurable(fiber.child);
+      }
       function tryScrollNear(anchor) {
         if (!opts.intoView && tryScroll(anchor, false)) return true;
+        var target = opts.intoView ? findMeasurable(anchor) : null;
         var current = anchor ? anchor.return : null;
         while (current) {
           var sn = current.stateNode;
+          var currentProps = current.memoizedProps;
           if (sn) {
-            if (typeof sn.scrollTo === 'function') { sn.scrollTo({ y: opts.offset, animated: opts.animated }); return true; }
-            if (typeof sn.scrollToOffset === 'function') { sn.scrollToOffset({ offset: opts.offset, animated: opts.animated }); return true; }
+            if (typeof sn.scrollTo === 'function' && !(currentProps && currentProps.horizontal === true)) {
+              if (target) {
+                return new Promise(function(resolve) {
+                  target.measureLayout(
+                    sn,
+                    function(x, y) {
+                      sn.scrollTo({ y: y, animated: opts.animated });
+                      resolve({ ok: true, testId: opts.testId, measuredOffset: y, animated: opts.animated });
+                    },
+                    function() {
+                      resolve({ ok: false, error: 'Unable to measure testID=' + opts.testId + ' relative to its scroll container' });
+                    }
+                  );
+                });
+              }
+              sn.scrollTo({ y: opts.offset, animated: opts.animated });
+              return true;
+            }
+            if (typeof sn.scrollToOffset === 'function' && !(currentProps && currentProps.horizontal === true)) {
+              if (target) {
+                return new Promise(function(resolve) {
+                  target.measureLayout(
+                    sn,
+                    function(x, y) {
+                      sn.scrollToOffset({ offset: y, animated: opts.animated });
+                      resolve({ ok: true, testId: opts.testId, measuredOffset: y, animated: opts.animated });
+                    },
+                    function() {
+                      resolve({ ok: false, error: 'Unable to measure testID=' + opts.testId + ' relative to its scroll container' });
+                    }
+                  );
+                });
+              }
+              sn.scrollToOffset({ offset: opts.offset, animated: opts.animated });
+              return true;
+            }
           }
           current = current.return;
         }
@@ -443,7 +692,23 @@ const COMMANDS = {
       function findTestId(fiber) {
         if (!fiber) return null;
         var props = fiber.memoizedProps;
-        if (props && props.testID === opts.testId) return fiber;
+        if (props && props.testID === opts.testId) {
+          var ancestor = fiber;
+          var inactive = false;
+          while (ancestor) {
+            var ancestorProps = ancestor.memoizedProps;
+            var ancestorStyle = ancestorProps && ancestorProps.style;
+            if (
+              (ancestorProps && ancestorProps.activityState === 0) ||
+              (ancestorStyle && ancestorStyle.display === 'none')
+            ) {
+              inactive = true;
+              break;
+            }
+            ancestor = ancestor.return;
+          }
+          if (!inactive) return fiber;
+        }
         return findTestId(fiber.child) || findTestId(fiber.sibling);
       }
       for (var [id] of renderers) {
@@ -459,11 +724,16 @@ const COMMANDS = {
             scrolled = tryScroll(r.current);
           }
         });
-        if (scrolled) return { ok: true, testId: opts.testId, offset: opts.offset, animated: opts.animated };
+        if (scrolled) {
+          if (typeof scrolled.then === 'function') return scrolled;
+          return { ok: true, testId: opts.testId, offset: opts.offset, animated: opts.animated };
+        }
       }
       return { ok: false, error: opts.testId ? 'No scrollable near testID=' + opts.testId : 'No scrollable found' };
     })()`;
-    const result = await cdpEval(client, expr);
+    const result = intoView
+      ? await cdpEvalAsync(client, expr)
+      : await cdpEval(client, expr);
     return { ...result, deviceName };
   },
 
@@ -841,34 +1111,33 @@ const COMMANDS = {
   },
 
   async 'show-step-json'(client, args) {
-    const raw = args.join(' ');
-    let step;
-    try {
-      step = JSON.parse(raw);
-    } catch (error) {
-      throw new Error(`show-step-json requires a JSON step payload: ${error.message}`);
-    }
-    if (!step || typeof step !== 'object' || Array.isArray(step)) {
-      throw new Error('show-step-json requires a JSON object step payload');
-    }
-    if (typeof step.intent !== 'string' || !step.intent.trim()) {
-      throw new Error('show-step-json requires step.intent');
-    }
-    // HUD derives status/progress from step.id when status is omitted; a
-    // non-string id makes statusForStep throw during render. Reject at the boundary.
-    if (step.id !== undefined && typeof step.id !== 'string') {
-      throw new Error('show-step-json step.id must be a string when provided');
-    }
-    const payload = JSON.stringify(step);
-    await cdpEval(client, `globalThis.__AGENTIC__?.showStep && globalThis.__AGENTIC__.showStep(${payload})`);
+    const step = parseHudStep(args);
+    await applyHudUpdate(client, step);
     return { ok: true };
   },
 
+  async 'show-step-json-deferred'(client, args) {
+    const step = parseHudStep(args);
+    if (typeof client.control === 'function') {
+      return client.control('hud-update', { step });
+    }
+    await applyHudUpdate(client, step);
+    return { ok: true, status: 'applied' };
+  },
+
   async 'hide-step'(client) {
-    await cdpEval(client, `globalThis.__AGENTIC__?.hideStep && globalThis.__AGENTIC__.hideStep()`);
+    await applyHudUpdate(client, null);
     return { ok: true };
   },
 
+  async 'hide-step-deferred'(client) {
+    if (typeof client.control === 'function') {
+      return client.control('hud-update', { step: null });
+    }
+    await applyHudUpdate(client, null);
+    return { ok: true, status: 'applied' };
+  },
+
   async 'profiler-start'(client) {
     // Hermes CDP exposes the sampling profiler via the Profiler domain.
     // Output of Profiler.stop is a Chrome-compatible .cpuprofile object.
@@ -1170,8 +1439,9 @@ Environment:
   const client = await clientFor(wsUrl);
 
   try {
-    // Detect platform from the running app (exposed by __AGENTIC__ bridge as Platform.OS)
-    const platform = await cdpEval(client, 'globalThis.__AGENTIC__?.platform') || '';
+    const platform = command.endsWith('-deferred')
+      ? ''
+      : await cdpEval(client, 'globalThis.__AGENTIC__?.platform') || '';
     const result = await handler(client, args.slice(1), { deviceName, platform });
     console.log(JSON.stringify(result, null, 2));
   } finally {

package/adapters/mobile/bridge-runtime/console-forwarder.cjs

@@ -40,6 +40,7 @@ const { resolvePort } = require('./lib/config.cjs');
 // Hermes uses Node's built-in WebSocket client. The local DevTools proxy uses
 // the package's pinned `ws` server implementation.
 const HANDSHAKE_TIMEOUT_MS = 3000;
+const RUNTIME_ENABLE_TIMEOUT_MS = 60_000;
 
 const DISCOVER_ACTIVE_MS = 1000; // a device is unattached — look for it quickly
 const DISCOVER_STEADY_MS = 10000; // all known targets attached — cheap liveness tick
@@ -311,25 +312,36 @@ function connect(target) {
   ws.addEventListener('open', async () => {
     clearTimeout(handshakeTimer);
     session.opened = true;
+    // A live inspector socket is enough for broker commands. Do not keep the
+    // broker unavailable while Runtime.enable replays a large console buffer or
+    // while __AGENTIC__ is being installed after a Hermes context handoff.
+    // Commands such as status already report agenticPresent=false and their
+    // callers retry against the same bounded action deadline.
+    session.brokerReady = true;
+    broker.onSessionOpen(deviceId);
+    devtoolsProxy.onSessionOpen(deviceId, session);
+    process.stderr.write(`console-forwarder: attached ${name}\n`);
     try {
-      await sendCommand(session, 'Runtime.enable');
+      await sendCommand(
+        session,
+        'Runtime.enable',
+        {},
+        RUNTIME_ENABLE_TIMEOUT_MS,
+      );
       const evaluation = await sendCommand(session, 'Runtime.evaluate', {
         expression: "typeof globalThis.__AGENTIC__ === 'object'",
         returnByValue: true,
         awaitPromise: false,
       });
       if (evaluation?.result?.value !== true) {
-        throw new Error('CDP target does not expose __AGENTIC__');
+        process.stderr.write(
+          `console-forwarder: ${name} is waiting for __AGENTIC__\n`,
+        );
       }
-      session.brokerReady = true;
-      broker.onSessionOpen(deviceId);
-      devtoolsProxy.onSessionOpen(deviceId, session);
-      process.stderr.write(`console-forwarder: attached ${name}\n`);
     } catch (error) {
       process.stderr.write(
-        `console-forwarder: rejected ${name}: ${String(error?.message || error).slice(0, 256)}\n`,
+        `console-forwarder: console bootstrap pending for ${name}: ${String(error?.message || error).slice(0, 256)}\n`,
       );
-      ws.close();
     }
   });
   ws.addEventListener('message', (event) => {

package/adapters/mobile/bridge-runtime/lib/cdp-broker.cjs

@@ -14,12 +14,25 @@ const MAX_CAPTURE_BYTES = 4 * 1024 * 1024;
 const MAX_POST_DATA_BYTES = 64 * 1024;
 const MAX_REQUEST_FRAME_BYTES = 8 * 1024 * 1024;
 const MAX_RESPONSE_FRAME_BYTES = 16 * 1024 * 1024;
+const MAX_HUD_STEP_BYTES = 16 * 1024;
+const MAX_HUD_UPDATES = 64;
 const MAX_RETAINED_STRING_LENGTH = 256;
 const MAX_BROKER_TIMEOUT_MS = 60_000;
 const SENSITIVE_FIELD =
   /(?:address|authorization|cookie|key|password|secret|token|user|account)/iu;
 const SENSITIVE_VALUE =
   /(?:0x[a-f0-9]{40,}|[a-f0-9]{64,}|eyJ[a-z0-9_-]{20,}\.[a-z0-9_-]{20,})/iu;
+const APPLY_HUD_UPDATE_FUNCTION = `function(step) {
+  const bridge = this.__AGENTIC__;
+  if (step === null) {
+    if (typeof bridge?.hideStep !== 'function') return false;
+    setTimeout(() => bridge.hideStep(), 0);
+    return true;
+  }
+  if (typeof bridge?.showStep !== 'function') return false;
+  setTimeout(() => bridge.showStep(step), 0);
+  return true;
+}`;
 
 function brokerSocketPath(runtimeDir, endpointIdentity) {
   const runtimePath = path.resolve(
@@ -353,6 +366,9 @@ function createCdpBroker({
 }) {
   const captures = new Map();
   const completedCaptures = new Map();
+  const hudUpdates = new Map();
+  const appliedHudVersions = new Map();
+  const hudApplyChains = new Map();
   const clients = new Set();
   const subscriptions = new Map();
   const knownTargets = new Map(
@@ -482,6 +498,67 @@ function createCdpBroker({
     capturesFor(deviceId).delete(capture.id);
   }
 
+  async function applyHudUpdate(deviceId, timeoutMs, socket) {
+    if (!hudUpdates.has(deviceId)) return { status: 'none' };
+    const budgetMs = boundedTimeout(timeoutMs);
+    const deadline = Date.now() + budgetMs;
+    const session = await waitForSession(deviceId, budgetMs, socket);
+    const update = hudUpdates.get(deviceId);
+    if (!update) return { status: 'none' };
+    if (appliedHudVersions.get(deviceId) === update.version) {
+      return { status: 'applied', version: update.version };
+    }
+    let applied = false;
+    while (Date.now() < deadline) {
+      const globalObject = await sendCommand(
+        session,
+        'Runtime.evaluate',
+        { expression: 'globalThis', returnByValue: false, awaitPromise: false },
+        Math.max(1, deadline - Date.now()),
+      );
+      const objectId = globalObject?.result?.objectId;
+      if (!objectId) {
+        throw new Error('Mobile HUD runtime did not expose globalThis');
+      }
+      const evaluation = await sendCommand(
+        session,
+        'Runtime.callFunctionOn',
+        {
+          objectId,
+          functionDeclaration: APPLY_HUD_UPDATE_FUNCTION,
+          arguments: [{ value: update.step }],
+          returnByValue: true,
+          awaitPromise: false,
+        },
+        Math.max(1, deadline - Date.now()),
+      );
+      if (evaluation?.result?.value === true) {
+        applied = true;
+        break;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    if (!applied) {
+      throw new Error('Mobile HUD bridge was not installed before the update deadline');
+    }
+    if (hudUpdates.get(deviceId)?.version === update.version) {
+      appliedHudVersions.set(deviceId, update.version);
+    }
+    return { status: 'applied', version: update.version };
+  }
+
+  function scheduleHudUpdate(deviceId, timeoutMs, socket) {
+    const previous = hudApplyChains.get(deviceId) || Promise.resolve();
+    const next = previous
+      .catch(() => undefined)
+      .then(() => applyHudUpdate(deviceId, timeoutMs, socket));
+    hudApplyChains.set(deviceId, next);
+    void next.finally(() => {
+      if (hudApplyChains.get(deviceId) === next) hudApplyChains.delete(deviceId);
+    }).catch(() => undefined);
+    return next;
+  }
+
   function expireCapture(deviceId, capture) {
     if (capturesFor(deviceId).get(capture.id) !== capture) return;
     finishCapture(deviceId, capture, true);
@@ -539,6 +616,29 @@ function createCdpBroker({
     if (action === 'resolve-targets') {
       return resolveTargets(params, timeoutMs, socket);
     }
+    if (action === 'hud-update') {
+      const step = params.step ?? null;
+      if (step !== null && (typeof step !== 'object' || Array.isArray(step))) {
+        throw new Error('HUD update requires an object step or null');
+      }
+      if (Buffer.byteLength(JSON.stringify(step)) > MAX_HUD_STEP_BYTES) {
+        throw new Error('HUD update exceeds its bound');
+      }
+      const previousVersion = hudUpdates.get(deviceId)?.version || 0;
+      if (hudUpdates.has(deviceId)) {
+        hudUpdates.delete(deviceId);
+      }
+      while (hudUpdates.size >= MAX_HUD_UPDATES) {
+        const oldestDeviceId = hudUpdates.keys().next().value;
+        hudUpdates.delete(oldestDeviceId);
+        appliedHudVersions.delete(oldestDeviceId);
+      }
+      const version = previousVersion + 1;
+      hudUpdates.set(deviceId, { step, version });
+      requestDiscovery?.(deviceId);
+      void scheduleHudUpdate(deviceId, 10_000).catch(() => undefined);
+      return { status: 'queued', version };
+    }
     if (action === 'capture-start') {
       const capture = normalizeCapture(params);
       const deviceCaptures = capturesFor(deviceId);
@@ -726,11 +826,13 @@ function createCdpBroker({
         if (capture.reconnects > 0) capture.partial = true;
         void enableNetwork(deviceId, capture);
       }
+      void scheduleHudUpdate(deviceId, 10_000).catch(() => undefined);
     },
     onSessionClose(deviceId) {
       const previous = knownTargets.get(deviceId);
       if (previous) knownTargets.set(deviceId, { ...previous, ready: false });
       observedSessions.delete(deviceId);
+      appliedHudVersions.delete(deviceId);
       for (const capture of capturesFor(deviceId).values()) {
         capture.reconnects += 1;
         capture.partial = true;