@deeeed/metamask-harness 0.44.1 → 0.44.2

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 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/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.2",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"