@deeeed/metamask-harness 0.44.1 → 0.44.3

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 0.44.3 - 2026-08-28
+
+### Fixed
+
+- Reuse one native UI provider session owner across recipe nodes on iOS so sequential gestures do not conflict with the retained XCTest runner, while each node still closes its logical session without shutting down the simulator.
+- Update `@farmslot/recipe-harness` from 0.15.0 to 0.15.1 so unresolved relative Metro imports remain source bundle failures instead of triggering dependency installation during Mobile launch preflight.
+
+## 0.44.2 - 2026-08-27
+
+### Fixed
+
+- Wait for a new React Native runtime after an authored Mobile restart, and avoid a second Android foreground launch when that runtime is already ready.
+- Hold Mobile restart recovery inside one readiness deadline: the foreground relaunch and its subprocesses inherit the remaining budget, and an expired deadline fails the lifecycle action instead of starting another launch or readiness probe.
+- Read the selected Mobile target identity and its broker generation for `status-selected` without attaching to CDP.
+
 ## 0.44.1 - 2026-08-27
 
 ### Fixed

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

@@ -30,9 +30,11 @@ const {
   deviceIdFromUrl,
 } = require('./lib/cdp-broker.cjs');
 const {
+  BRIDGE_ERROR_CODES,
   EXIT_CODE_BY_ERROR_CODE,
   TEACHING_BY_ERROR_CODE,
   classifyBridgeErrorMessage,
+  coded,
   formatErrorMarker,
 } = require('./lib/bridge-errors.cjs');
 const { cdpEval, cdpEvalAsync } = require('./lib/cdp-eval.cjs');
@@ -293,6 +295,9 @@ function parseHudStep(args) {
 }
 
 const COMMANDS = {
+  async 'target-identity-selected'() {
+    throw new Error('target-identity-selected is resolved before CDP attachment');
+  },
   async navigate(client, args, { deviceName, platform } = {}) {
     const routeName = ROUTE_ALIASES[args[0]] || args[0];
     if (!routeName) {
@@ -413,7 +418,11 @@ const COMMANDS = {
     return { currentRoute: route ?? null, deviceName, platform };
   },
 
-  async status(client, _args, { deviceName, platform } = {}) {
+  async status(
+    client,
+    _args,
+    { deviceName, platform, runtimeIdentity } = {},
+  ) {
     const expr = `(function() {
       var agenticPresent = typeof globalThis.__AGENTIC__ !== 'undefined';
       var route = globalThis.__AGENTIC__?.getRoute() || null;
@@ -429,7 +438,12 @@ const COMMANDS = {
       };
     })()`;
     const snapshot = await cdpEval(client, expr);
-    return { ...snapshot, deviceName: deviceName || '', platform: platform || '' };
+    return {
+      ...snapshot,
+      ...(runtimeIdentity ? { runtimeIdentity } : {}),
+      deviceName: deviceName || '',
+      platform: platform || '',
+    };
   },
 
   async 'list-accounts'(client) {
@@ -1359,7 +1373,10 @@ Environment:
     ).trim();
   }
 
-  async function brokerTargets({ retainIdentity = false } = {}) {
+  async function brokerTargets({
+    retainIdentity = false,
+    includeGeneration = false,
+  } = {}) {
     const discoveryClient = await createBrokerClient(
       brokerSocketFile,
       '',
@@ -1367,14 +1384,22 @@ Environment:
     );
     try {
       const targets = await discoveryClient.control(
-        retainIdentity ? 'resolve-targets' : 'list-targets',
+        retainIdentity
+          ? 'resolve-targets'
+          : includeGeneration
+            ? 'list-target-identities'
+            : 'list-targets',
         retainIdentity ? { nameIncludes: selectedTargetPin() } : {},
         timeout,
       );
       return (Array.isArray(targets) ? targets : []).flatMap((target) => {
         const deviceId = String(target?.deviceId || '');
         return deviceId
-          ? [{ wsUrl: deviceId, deviceName: String(target?.name || '') }]
+          ? [{
+              wsUrl: deviceId,
+              deviceName: String(target?.name || ''),
+              generation: Number(target?.generation) || 0,
+            }]
           : [];
       });
     } finally {
@@ -1390,13 +1415,31 @@ Environment:
         )
       : targets;
     if (candidates.length !== 1) {
-      throw new Error(
+      const error = new Error(
         `Mobile CDP broker target selection requires one target; found ${candidates.length}${pin ? ` for ${JSON.stringify(pin)}` : ''}.`,
       );
+      throw candidates.length === 0
+        ? coded(error, BRIDGE_ERROR_CODES.NO_TARGET)
+        : error;
     }
     return candidates[0];
   }
 
+  if (command === 'target-identity-selected') {
+    const target = brokerAvailable
+      ? selectBrokerTarget(await brokerTargets({ includeGeneration: true }))
+      : await discoverTarget(port, { probe: true });
+    const generation = Number(target.generation) || 0;
+    console.log(
+      JSON.stringify({
+        runtimeIdentity: generation
+          ? `${target.wsUrl}:${generation}`
+          : target.wsUrl,
+      }),
+    );
+    return;
+  }
+
   async function clientFor(wsUrl) {
     if (brokerAvailable) {
       return createBrokerClient(
@@ -1439,9 +1482,10 @@ Environment:
     return;
   }
 
-  const { wsUrl, deviceName } = brokerAvailable
+  const selectedTarget = brokerAvailable
     ? selectBrokerTarget(await brokerTargets({ retainIdentity: true }))
     : await discoverTarget(port, { probe: true });
+  const { wsUrl, deviceName, generation } = selectedTarget;
   if (!wsUrl) throw new Error('No broker-owned Hermes target is available');
   const client = await clientFor(wsUrl);
 
@@ -1449,7 +1493,28 @@ Environment:
     const platform = command.endsWith('-deferred')
       ? ''
       : await cdpEval(client, 'globalThis.__AGENTIC__?.platform') || '';
-    const result = await handler(client, args.slice(1), { deviceName, platform });
+    const runtimeIdentity =
+      command === 'status-selected'
+        ? generation
+          ? `${wsUrl}:${generation}`
+          : wsUrl
+        : undefined;
+    const result = await handler(client, args.slice(1), {
+      deviceName,
+      platform,
+      runtimeIdentity,
+    });
+    if (brokerAvailable && command === 'status-selected') {
+      const currentTarget = selectBrokerTarget(
+        await brokerTargets({ includeGeneration: true }),
+      );
+      if (
+        currentTarget.wsUrl !== wsUrl ||
+        currentTarget.generation !== generation
+      ) {
+        throw new Error('Hermes runtime rotated during status-selected');
+      }
+    }
     console.log(JSON.stringify(result, null, 2));
   } finally {
     client.close();

package/adapters/mobile/bridge-runtime/lib/bridge-errors.cjs

@@ -59,6 +59,7 @@ const NEEDLE_CODES = [
   ['did not match any metro target', BRIDGE_ERROR_CODES.NO_TARGET],
   ['pinned android device', BRIDGE_ERROR_CODES.NO_TARGET],
   ['no react native bridge target', BRIDGE_ERROR_CODES.NO_TARGET],
+  ['cdp broker target unavailable', BRIDGE_ERROR_CODES.NO_TARGET],
   ['websocket closed', BRIDGE_ERROR_CODES.WS_CLOSED],
   ['websocket error', BRIDGE_ERROR_CODES.WS_CLOSED],
   ['cdp connection timeout', BRIDGE_ERROR_CODES.CDP_TIMEOUT],

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

@@ -613,6 +613,11 @@ function createCdpBroker({
         name,
       }));
     }
+    if (action === 'list-target-identities') {
+      return targetList({ readyOnly: true }).map(
+        ({ deviceId, generation, name }) => ({ deviceId, generation, name }),
+      );
+    }
     if (action === 'resolve-targets') {
       return resolveTargets(params, timeoutMs, socket);
     }

package/dist/adapters.js

@@ -955,7 +955,7 @@ async function executeNativeProviderAction(action, node, context, createTranspor
     return executeAndroidCoordinateSwipe(node, String(device));
   }
   const app = platform === "android" ? context.env.ANDROID_PACKAGE_ID ?? process.env.ANDROID_PACKAGE_ID ?? "io.metamask" : context.env.IOS_BUNDLE_ID ?? process.env.IOS_BUNDLE_ID ?? "io.metamask.MetaMask";
-  const session = `mm-harness-${process.pid}-${context.nodeId}`.replace(/[^a-zA-Z0-9._-]/gu, "-");
+  const session = (platform === "ios" ? `mm-harness-${process.pid}-${device}` : `mm-harness-${process.pid}-${context.nodeId}`).replace(/[^a-zA-Z0-9._-]/gu, "-");
   const stateDir = nativeAgentDeviceStateDir(context.env ?? {}, context.projectRoot, String(device));
   let transport;
   try {

package/dist/app-lifecycle.js

@@ -1,3 +1,56 @@
+import { execFile } from "node:child_process";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { promisify } from "node:util";
+const MOBILE_LIFECYCLE_DEADLINE_FIELD = "_mobile_lifecycle_deadline_epoch_ms";
+const lifecycleDeadline = new AsyncLocalStorage();
+const execFileAsync = promisify(execFile);
+function bindMetaMaskMobileLifecycleDeadline(adapters) {
+  return adapters.map((adapter) => ({
+    ...adapter,
+    execute(node, context) {
+      const deadline = Number(node[MOBILE_LIFECYCLE_DEADLINE_FIELD]);
+      if (!Number.isFinite(deadline)) return adapter.execute(node, context);
+      return lifecycleDeadline.run(deadline, () => adapter.execute(node, context));
+    }
+  }));
+}
+function createMetaMaskMobileLifecycleCommandRunner(base = defaultLifecycleCommandRunner()) {
+  return {
+    execFile(file, args, options) {
+      const deadline = lifecycleDeadline.getStore();
+      if (deadline === void 0) return base.execFile(file, args, options);
+      const remainingMs = deadline - Date.now();
+      if (remainingMs <= 0) {
+        throw new Error(
+          `Mobile lifecycle deadline expired before ${file} could start.`
+        );
+      }
+      const configuredTimeoutMs = options?.timeoutMs;
+      return base.execFile(file, args, {
+        timeoutMs: configuredTimeoutMs === void 0 ? remainingMs : Math.min(configuredTimeoutMs, remainingMs)
+      });
+    }
+  };
+}
+function defaultLifecycleCommandRunner() {
+  return {
+    async execFile(file, args, options) {
+      try {
+        return await execFileAsync(file, args, {
+          timeout: options?.timeoutMs,
+          encoding: "utf8"
+        });
+      } catch (error) {
+        if (error instanceof Error) {
+          const output = error;
+          const details = [output.message, output.stderr, output.stdout].filter(Boolean).join("\n");
+          throw new Error(`${file} ${args.join(" ")} failed: ${details}`);
+        }
+        throw error;
+      }
+    }
+  };
+}
 function resolveMetaMaskMobileLifecycleTarget(node, rawContext) {
   const context = rawContext;
   const platform = resolveMobilePlatform(node, context);
@@ -69,5 +122,8 @@ function scalar(value, label) {
   throw new Error(`${label} must be a string, number, or boolean.`);
 }
 export {
+  MOBILE_LIFECYCLE_DEADLINE_FIELD,
+  bindMetaMaskMobileLifecycleDeadline,
+  createMetaMaskMobileLifecycleCommandRunner,
   resolveMetaMaskMobileLifecycleTarget
 };

package/dist/runner.js

@@ -1,7 +1,10 @@
 import { execFileSync, execSync } from "node:child_process";
 import { OFFICIAL_RECIPE_ACTIONS } from "@farmslot/protocol";
 import { createMetaMaskAdapters, createMetaMaskUiTransport } from "./adapters.js";
-import { bridgeCommand } from "../library/actions/mobile/platform/bridge.mjs";
+import {
+  bridgeCommand,
+  MOBILE_BRIDGE_ERROR_CODES
+} from "../library/actions/mobile/platform/bridge.mjs";
 import { resolveMobileToolPath } from "../library/actions/mobile/platform/tool-paths.mjs";
 import {
   mobileSourceFingerprint,
@@ -13,7 +16,12 @@ import {
   createAndroidVideoRecorder,
   createIosSimulatorVideoRecorder
 } from "./adapters/mobile/video-recorder.js";
-import { resolveMetaMaskMobileLifecycleTarget } from "./app-lifecycle.js";
+import {
+  bindMetaMaskMobileLifecycleDeadline,
+  createMetaMaskMobileLifecycleCommandRunner,
+  MOBILE_LIFECYCLE_DEADLINE_FIELD,
+  resolveMetaMaskMobileLifecycleTarget
+} from "./app-lifecycle.js";
 import { loadMetaMaskExtensionActionManifest, loadMetaMaskMobileActionManifest } from "./manifest.js";
 import { metaMaskActionExecutionCapabilities } from "./recipe-security.js";
 import {
@@ -84,10 +92,13 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
   const existing = new Set([...core, ...ui].map((entry) => entry.action));
   const lifecycle = mobileSourceAwareLifecycleAdapters(
     adapter,
-    createAppLifecycleAdapters({
-      actions,
-      targetProvider: { resolveTarget: resolveMetaMaskMobileLifecycleTarget }
-    })
+    bindMetaMaskMobileLifecycleDeadline(
+      createAppLifecycleAdapters({
+        actions,
+        commandRunner: createMetaMaskMobileLifecycleCommandRunner(),
+        targetProvider: { resolveTarget: resolveMetaMaskMobileLifecycleTarget }
+      })
+    )
   );
   const custom = createMetaMaskAdapters(
     adapter,
@@ -337,7 +348,7 @@ function mobileSourceAwareLifecycleAdapters(adapter, lifecycle, readinessProbe =
 }, processIdentity = {
   readIosPid: readIosAppPid,
   readAndroidPid: readAndroidAppPid
-}) {
+}, runtimeMarker = readMobileLifecycleRuntimeIdentity) {
   if (adapter !== "mobile") return lifecycle;
   return lifecycle.map((entry) => ({
     ...entry,
@@ -357,19 +368,62 @@ function mobileSourceAwareLifecycleAdapters(adapter, lifecycle, readinessProbe =
       const readProcessId = androidLifecycle ? processIdentity.readAndroidPid ?? readAndroidAppPid : processIdentity.readIosPid;
       const processBefore = recordsProcessIdentity ? readProcessId(node, context) : void 0;
       const fingerprint = recordsSource ? sourceFreshness.fingerprint(context.projectRoot) : void 0;
+      const previousRuntimeIdentity = recordsSource ? await runtimeMarker(node, context) : void 0;
       const androidRestart = command === "restart" && androidLifecycle;
-      const initialNode = androidRestart ? { ...node, settle_ms: 0 } : node;
-      const initialResult = await entry.execute(initialNode, context);
+      const initialResult = await entry.execute(node, context);
+      const readinessDeadline = reloadsSource ? mobileLifecycleReadinessDeadline(command, node) : void 0;
       let result = initialResult;
+      let runtimeReady = false;
       if (androidRestart) {
-        const foregroundResult = await entry.execute(
-          { ...node, command: "foreground" },
-          context
-        );
-        result = mergeAndroidRestartResults(initialResult, foregroundResult);
+        try {
+          const remainingMs = Math.max(
+            1,
+            (readinessDeadline ?? Date.now()) - Date.now()
+          );
+          const handoffDeadline = Math.min(
+            readinessDeadline ?? Number.POSITIVE_INFINITY,
+            Date.now() + Math.min(1e4, Math.max(1, remainingMs / 2))
+          );
+          await readinessProbe(
+            node,
+            context,
+            previousRuntimeIdentity,
+            handoffDeadline
+          );
+          runtimeReady = true;
+        } catch (error) {
+          if (readinessDeadline !== void 0 && Date.now() >= readinessDeadline) {
+            throw error;
+          }
+          const foregroundTimeoutMs = Math.max(
+            1,
+            (readinessDeadline ?? Date.now() + 1) - Date.now()
+          );
+          const foregroundResult = await entry.execute(
+            {
+              ...node,
+              command: "foreground",
+              settle_ms: 0,
+              timeout_ms: foregroundTimeoutMs,
+              [MOBILE_LIFECYCLE_DEADLINE_FIELD]: readinessDeadline
+            },
+            context
+          );
+          result = mergeAndroidRestartResults(initialResult, foregroundResult);
+        }
       }
-      if (reloadsSource) {
-        await readinessProbe(node, context);
+      if (reloadsSource && !runtimeReady) {
+        if (readinessDeadline !== void 0 && Date.now() >= readinessDeadline) {
+          throw new Error(
+            `Mobile lifecycle ${String(command)} exhausted its runtime readiness deadline before recovery completed.`
+          );
+        }
+        await readinessProbe(
+          node,
+          context,
+          previousRuntimeIdentity,
+          readinessDeadline
+        );
       }
       if (recordsProcessIdentity) {
         const processAfter = readProcessId(node, context);
@@ -468,35 +522,92 @@ function mergeAndroidRestartResults(initialResult, foregroundResult) {
     }
   };
 }
-async function probeMobileLifecycleRuntime(node, context) {
+async function probeMobileLifecycleRuntime(node, context, previousRuntimeIdentity, deadlineMs) {
   const command = node.command ?? node.event ?? node.state;
   const timeoutMs = resolveMobileLifecycleReadinessTimeout(
     command,
     node.runtime_ready_timeout_ms
   );
-  const deadline = Date.now() + timeoutMs;
+  const startedAt = Date.now();
+  const deadline = deadlineMs ?? startedAt + timeoutMs;
   let lastError;
   while (Date.now() < deadline) {
     try {
-      return await bridgeCommand(
+      const status = await bridgeCommand(
         {
           action: "app.lifecycle",
           node: {
             ...node,
-            cdp_timeout_ms: Math.min(8e3, Math.max(1e3, deadline - Date.now()))
+            cdp_timeout_ms: Math.min(8e3, Math.max(1, deadline - Date.now()))
           },
           context
         },
-        ["get-route"]
+        ["status-selected"]
+      );
+      if (status?.agenticPresent === true && status.route && (!previousRuntimeIdentity || status.runtimeIdentity !== previousRuntimeIdentity)) {
+        return status;
+      }
+      lastError = new Error(
+        previousRuntimeIdentity && status?.runtimeIdentity === previousRuntimeIdentity ? "retiring Mobile runtime is still selected" : "selected Mobile runtime is not ready"
       );
     } catch (error) {
       lastError = error;
-      await new Promise((resolve) => setTimeout(resolve, 1e3));
+    }
+    const remainingMs = deadline - Date.now();
+    if (remainingMs > 0) {
+      await new Promise(
+        (resolve) => setTimeout(resolve, Math.min(1e3, remainingMs))
+      );
     }
   }
   throw new Error(
-    `Mobile lifecycle ${String(command)} did not expose a usable pinned __AGENTIC__ runtime within ${timeoutMs}ms: ${lastError instanceof Error ? lastError.message : String(lastError)}`
+    `Mobile lifecycle ${String(command)} did not expose a usable pinned __AGENTIC__ runtime within ${Math.max(0, deadline - startedAt)}ms: ${lastError instanceof Error ? lastError.message : String(lastError)}`
+  );
+}
+async function readMobileLifecycleRuntimeIdentity(node, context) {
+  const deadline = Date.now() + 5e3;
+  let lastError;
+  do {
+    try {
+      const status = await bridgeCommand(
+        {
+          action: "app.lifecycle",
+          node: {
+            ...node,
+            cdp_timeout_ms: Math.min(1e3, Math.max(1, deadline - Date.now()))
+          },
+          context
+        },
+        ["target-identity-selected"]
+      );
+      if (typeof status?.runtimeIdentity === "string") {
+        return status.runtimeIdentity;
+      }
+      lastError = new Error("selected Mobile runtime has no stable identity");
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === MOBILE_BRIDGE_ERROR_CODES.NO_TARGET) {
+        return void 0;
+      }
+      lastError = error;
+    }
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0) {
+      break;
+    }
+    await new Promise(
+      (resolve) => setTimeout(resolve, Math.min(250, remainingMs))
+    );
+  } while (Date.now() < deadline);
+  throw new Error(
+    `Mobile lifecycle restart could not identify the retiring runtime: ${lastError instanceof Error ? lastError.message : String(lastError)}`
+  );
+}
+function mobileLifecycleReadinessDeadline(command, node) {
+  const timeoutMs = resolveMobileLifecycleReadinessTimeout(
+    command,
+    node.runtime_ready_timeout_ms
   );
+  return Date.now() + timeoutMs;
 }
 function resolveMobileLifecycleReadinessTimeout(command, value) {
   if (value === void 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.44.1",
+  "version": "0.44.3",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -24,7 +24,7 @@
     "@farmslot/expo-recipe": "0.8.1",
     "@farmslot/handoff": "^0.3.1",
     "@farmslot/protocol": "0.21.0",
-    "@farmslot/recipe-harness": "0.15.0",
+    "@farmslot/recipe-harness": "0.15.1",
     "agent-device": "0.19.3",
     "commander": "^12.0.0",
     "es-module-lexer": "2.3.1",