@deeeed/metamask-harness 0.43.0 → 0.44.1

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## Unreleased
 
+## 0.44.1 - 2026-08-27
+
+### Fixed
+
+- Accept retained market context as lifecycle-valid Homepage evidence during account-only switches.
+- Require controller-backed Mobile unlock proof before continuing a recipe after startup or restart.
+
+## 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];
@@ -277,8 +418,15 @@ const COMMANDS = {
       var agenticPresent = typeof globalThis.__AGENTIC__ !== 'undefined';
       var route = globalThis.__AGENTIC__?.getRoute() || null;
       var account = null;
+      var keyringUnlocked = false;
       try { account = globalThis.__AGENTIC__?.getSelectedAccount() || null; } catch(e) {}
-      return { route: route, account: account, agenticPresent: agenticPresent };
+      try { keyringUnlocked = globalThis.Engine?.context?.KeyringController?.isUnlocked?.() === true; } catch(e) {}
+      return {
+        route: route,
+        account: account,
+        agenticPresent: agenticPresent,
+        keyringUnlocked: keyringUnlocked,
+      };
     })()`;
     const snapshot = await cdpEval(client, expr);
     return { ...snapshot, deviceName: deviceName || '', platform: platform || '' };
@@ -300,14 +448,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 +479,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 +617,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 +641,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 +699,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 +731,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 +1118,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 +1446,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) => {