@deeeed/metamask-harness 0.47.2 → 0.47.4

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 0.47.4 - 2026-09-05
+
+### Fixed
+
+- Verify Mobile reloads through execution-context replacement when React Native retains its Hermes target ID, and advance broker runtime identity on context reset for lifecycle readiness checks.
+
+## 0.47.3 - 2026-09-05
+
+### Fixed
+
+- Select the requested Mobile Perps mode through the first-entry chooser, verify its detail root, and restore the requested market after mode selection changes the navigation stack.
+- Preserve earlier `call` evidence by assigning each invocation a fresh default artifact directory; approval retries still use the explicit directory in the printed next command.
+
+### Changed
+
+- Teach authors to inspect existing state and limit setup mutations to prerequisites required by their proof.
+
 ## 0.47.2 - 2026-09-05
 
 ### Changed

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

@@ -195,6 +195,7 @@ const NESTED_ROUTE_PARENTS = {
   PerpsPnlHeroCard: 'Perps', PerpsHIP3Debug: 'Perps',
   PerpsSelectModifyAction: 'Perps', PerpsSelectAdjustMarginAction: 'Perps',
   PerpsSelectOrderType: 'Perps', PerpsTradingView: 'Perps',
+  PerpsModeSelection: 'PerpsModals',
   // Predict
   PredictMarketList: 'Predict', PredictMarketDetails: 'Predict',
   PredictActivityDetail: 'Predict',

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

@@ -862,6 +862,10 @@ function createCdpBroker({
       }
     },
     onCdpEvent(deviceId, method, params) {
+      if (method === 'Runtime.executionContextsCleared') {
+        const target = knownTargets.get(deviceId);
+        if (target) knownTargets.set(deviceId, { ...target, generation: target.generation + 1 });
+      }
       for (const socket of clients) {
         if (subscriptions.get(socket)?.has(`${deviceId}\u0000${method}`)) {
           writeMessage(socket, { type: 'event', deviceId, method, params });

package/adapters/mobile/reload-app.mjs

@@ -1,12 +1,54 @@
 #!/usr/bin/env node
 
 import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 import { createRequire } from 'node:module';
 import { resolveMobileToolPath } from '../../library/actions/mobile/platform/tool-paths.mjs';
 
 const require = createRequire(import.meta.url);
 const WebSocket = require('ws');
-const { discoverTarget } = require('./bridge-runtime/lib/target-discovery.cjs');
+const { discoverTarget, rankRuntimeCandidates } = require('./bridge-runtime/lib/target-discovery.cjs');
+const { brokerSocketPath, createBrokerClient, deviceIdFromUrl } = require('./bridge-runtime/lib/cdp-broker.cjs');
+const { createWSClient } = require('./bridge-runtime/lib/ws-client.cjs');
+
+async function observeRuntimeReset(port, target) {
+  const socketPath = brokerSocketPath(
+    process.env.RECIPE_RUNTIME_DIR || path.join(process.cwd(), 'temp/recipe/runtime'),
+    port,
+  );
+  const client = fs.existsSync(socketPath)
+    ? await createBrokerClient(socketPath, deviceIdFromUrl(target.wsUrl), 5000)
+    : await createWSClient(target.wsUrl, 5000);
+  let armed = false;
+  let cleared = false;
+  let recreated = false;
+  client.on('Runtime.executionContextsCleared', () => {
+    if (armed) cleared = true;
+  });
+  client.on('Runtime.executionContextCreated', () => {
+    if (armed && cleared) recreated = true;
+  });
+  try {
+    await client.send('Runtime.enable');
+    // Finish subscription/bootstrap before the reload request can generate events.
+    await client.send('Runtime.evaluate', { expression: 'true', returnByValue: true });
+    armed = true;
+  } catch (error) {
+    client.close();
+    throw error;
+  }
+  return {
+    get recreated() { return recreated; },
+    async responsive(timeoutMs) {
+      const result = await client.send('Runtime.evaluate', {
+        expression: 'true', returnByValue: true,
+      }, timeoutMs);
+      return result?.result?.value === true;
+    },
+    close() { client.close(); },
+  };
+}
 
 function parseArgs(argv) {
   const args = {
@@ -46,30 +88,38 @@ async function reload(port) {
       'The Android Hermes sampling profiler is active, so a runtime reload can abort the app. Use an explicit app.lifecycle restart.',
     );
   }
-  await new Promise((resolve, reject) => {
-    const socket = new WebSocket(`ws://127.0.0.1:${numericPort}/message`);
-    const timeout = setTimeout(() => {
-      socket.close();
-      reject(new Error(`Metro reload timed out on port ${numericPort}`));
-    }, 5000);
-    socket.on('open', () => {
-      socket.send(JSON.stringify({ method: 'reload', version: 2 }));
-      setTimeout(() => {
-        clearTimeout(timeout);
+  const observer = await observeRuntimeReset(numericPort, targetBefore);
+  let verification;
+  try {
+    await new Promise((resolve, reject) => {
+      const socket = new WebSocket(`ws://127.0.0.1:${numericPort}/message`);
+      const timeout = setTimeout(() => {
         socket.close();
-        resolve();
-      }, 50);
-    });
-    socket.on('error', () => {
-      clearTimeout(timeout);
-      reject(new Error(`Metro is not reachable on port ${numericPort}`));
+        reject(new Error(`Metro reload timed out on port ${numericPort}`));
+      }, 5000);
+      socket.on('open', () => {
+        socket.send(JSON.stringify({ method: 'reload', version: 2 }));
+        setTimeout(() => {
+          clearTimeout(timeout);
+          socket.close();
+          resolve();
+        }, 50);
+      });
+      socket.on('error', () => {
+        clearTimeout(timeout);
+        reject(new Error(`Metro is not reachable on port ${numericPort}`));
+      });
     });
-  });
-  const targetAfter = await waitForReload(
-    numericPort,
-    targetBefore.id,
-    processBefore,
-  );
+    verification = await waitForReload(
+      numericPort,
+      targetBefore,
+      processBefore,
+      observer,
+    );
+  } finally {
+    observer.close();
+  }
+  const { target: targetAfter, proof } = verification;
   const processAfter = processBefore ? readAndroidPid() : null;
   if (processBefore && processAfter !== processBefore) {
     throw new Error(
@@ -84,6 +134,7 @@ async function reload(port) {
     port: numericPort,
     targetBefore: targetBefore.id,
     targetAfter: targetAfter.id,
+    verification: proof,
     ...(processBefore
       ? {
           processBefore,
@@ -94,20 +145,33 @@ async function reload(port) {
   };
 }
 
-async function waitForReload(port, targetBefore, processBefore) {
+async function waitForReload(port, targetBefore, processBefore, observer) {
   const deadline = Date.now() + 30_000;
+  let lastError;
   while (Date.now() < deadline) {
     if (processBefore && readAndroidPid() !== processBefore) {
       throw new Error(
         `Android app process ${processBefore} exited during reload. Inspect the native crash before using an explicit app.lifecycle restart.`,
       );
     }
-    const target = await readHermesTarget(port).catch(() => null);
-    if (target && target.id !== targetBefore) return target;
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/json/list`, {
+        signal: AbortSignal.timeout(Math.max(1, Math.min(1000, deadline - Date.now()))),
+      });
+      const targets = rankRuntimeCandidates(await response.json());
+      const target = targets.find((item) => item.deviceName === targetBefore.deviceName);
+      if (target && target.id !== targetBefore.id) return { target, proof: 'target-replaced' };
+      if (target && observer.recreated && await observer.responsive(Math.max(1, Math.min(1000, deadline - Date.now())))) {
+        return { target, proof: 'execution-context-recreated' };
+      }
+    } catch (error) {
+      // A reload temporarily removes the runtime; preserve the last failure if it never returns.
+      lastError = error;
+    }
     await new Promise((resolve) => setTimeout(resolve, 250));
   }
   throw new Error(
-    `React Native did not expose a new Hermes target after reload on port ${port}`,
+    `React Native reload was not verified on port ${port}: no target replacement or responsive new execution context${lastError ? ` (${lastError.message})` : ''}.\nNext: mm-harness status --json`,
   );
 }
 
@@ -155,7 +219,7 @@ const args = parseArgs(process.argv.slice(2));
 reload(args.port)
   .then((result) => {
     if (args.json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-    else console.log(`Reload requested through Metro :${result.port}`);
+    else console.log(`Reload verified through Metro :${result.port} (${result.verification})`);
   })
   .catch((error) => {
     const result = { ok: false, adapter: 'mobile', error: String(error?.message || error) };

package/dist/commands/call.js

@@ -1,5 +1,5 @@
 import fs from "node:fs";
-import { createHash } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { resolveActionManifest } from "../manifest.js";
 import { importRecipeProtocol } from "../paths.js";
@@ -212,7 +212,7 @@ async function handleCall(argv) {
     }
     return EXIT.validation;
   }
-  const artifactsDir = optionString(options, "artifactsDir") ?? defaultCallArtifactsDir(target, resolvedAction, args);
+  const artifactsDir = optionString(options, "artifactsDir") ?? defaultCallArtifactsDir(target, resolvedAction);
   recordCommandEvidence(artifactsDir);
   const requestedRuntimeOptions = runtimeOptionsFromCli(options);
   const inheritedSource = process.env.FARMSLOT_RECIPE_SOURCE_TRUST || process.env.FARMSLOT_RECIPE_SOURCE_KIND || process.env.FARMSLOT_RECIPE_SOURCE_NAME || process.env.FARMSLOT_RECIPE_SOURCE_DIGEST;
@@ -493,10 +493,9 @@ function renderDefaultsUsed(defaults, stream) {
   const values = Object.entries(defaults).map(([name, value]) => `${out("cmd", name)}=${out("accent", JSON.stringify(value) ?? String(value))}`).join(", ");
   return `${out("label", "Defaults used:")} ${values}`;
 }
-function defaultCallArtifactsDir(target, action, args) {
+function defaultCallArtifactsDir(target, action) {
   const actionStem = action.replace(/[^a-zA-Z0-9._-]/gu, "_");
-  const digest = createHash("sha256").update(JSON.stringify({ action, args })).digest("hex").slice(0, 12);
-  return path.join(target, "temp", "recipe", "calls", `${actionStem}-${digest}`);
+  return path.join(target, "temp", "recipe", "calls", `${actionStem}-${randomUUID()}`);
 }
 function readCallOutput(tracePath) {
   try {

package/library/actions/mobile/perps/perps.mjs

@@ -131,7 +131,7 @@ function withRemainingDeadline(input, requestedDeadline, attemptTimeoutMs) {
   };
 }
 
-async function isModePresent(input, mode, deadline) {
+async function queryModeState(input, mode, deadline) {
   const rootTarget = JSON.stringify({
     testId: MODE_ROOT_TEST_IDS[mode],
     visibility: 'viewport',
@@ -140,6 +140,10 @@ async function isModePresent(input, mode, deadline) {
     testId: MODE_TEST_IDS[mode],
     visibility: 'tree',
   });
+  const choiceTarget = JSON.stringify({
+    testId: `perps-mode-selection-${mode}-option`,
+    visibility: 'viewport',
+  });
   const result = await evalAsync(
     withRemainingDeadline(input, deadline, READ_ATTEMPT_TIMEOUT_MS),
     `(function(){
@@ -149,21 +153,25 @@ async function isModePresent(input, mode, deadline) {
       }
       return Promise.all([
         api.queryUiTarget(${rootTarget}),
-        api.queryUiTarget(${controlTarget})
+        api.queryUiTarget(${controlTarget}),
+        api.queryUiTarget(${choiceTarget})
       ]).then(function(values){
-        return JSON.stringify({ root: values[0], control: values[1] });
+        return JSON.stringify({ root: values[0], control: values[1], choice: values[2] });
       });
     })()`,
   );
   if (result?.unsupported) {
     throw new Error('metamask.perps.ensure_mode requires UI target queries.');
   }
-  return result?.root?.visible === true && result?.control?.present === true;
+  return {
+    present: result?.root?.visible === true && result?.control?.present === true,
+    choiceVisible: result?.choice?.visible === true,
+  };
 }
 
-async function readModePresence(input, mode, deadline) {
+async function readModeState(input, mode, deadline) {
   try {
-    return await isModePresent(input, mode, deadline);
+    return await queryModeState(input, mode, deadline);
   } catch (error) {
     if (!isTargetTransition(error)) throw error;
     return null;
@@ -181,14 +189,15 @@ export async function ensureMode(input) {
     Number(input.node?.timeout_ms ?? 30_000),
   );
   let switched = false;
+  let choiceSelected = false;
 
   while (Date.now() < deadline) {
-    const requestedModePresent = await readModePresence(
+    const requestedState = await readModeState(
       input,
       requestedMode,
       deadline,
     );
-    if (requestedModePresent) {
+    if (requestedState?.present && !requestedState.choiceVisible) {
       return {
         action: input.action,
         mode: requestedMode,
@@ -197,13 +206,23 @@ export async function ensureMode(input) {
       };
     }
     if (Date.now() >= deadline) break;
-    if (requestedModePresent !== null && !switched) {
-      const otherModePresent = await readModePresence(
+    if (requestedState?.choiceVisible && !choiceSelected) {
+      const pressed = await bridgeCommand(withRemainingDeadline(input, deadline), [
+        'press-test-id',
+        `perps-mode-selection-${requestedMode}-option`,
+      ]);
+      if (pressed?.ok === false) {
+        throw new Error(String(pressed.error || 'Perps mode choice press failed.'));
+      }
+      choiceSelected = true;
+      switched = true;
+    } else if (requestedState !== null && !switched) {
+      const otherState = await readModeState(
         input,
         otherMode,
         deadline,
       );
-      if (otherModePresent && Date.now() < deadline) {
+      if (otherState?.present && Date.now() < deadline) {
         // The visible control names the mode it will switch to, not the mode
         // currently selected.
         const pressed = await bridgeCommand(withRemainingDeadline(input, deadline), [
@@ -1818,7 +1837,7 @@ export async function startState(input) {
   const navigation = await applyStateNavigation(stateInput(), config);
   const provider = await ensureProvider(stateInput(), config);
   const network = await ensureNetwork(stateInput(), config);
-  const resolvedNavigation = provider.changed || network.changed
+  let resolvedNavigation = provider.changed || network.changed
     ? await applyStateNavigation(stateInput(), config)
     : navigation;
   const modeInput = stateInput();
@@ -1833,6 +1852,9 @@ export async function startState(input) {
         },
       })
     : { skipped: true };
+  if (marketMode.alreadySelected === false) {
+    resolvedNavigation = await applyStateNavigation(stateInput(), config);
+  }
   const tutorial = await applyTutorialState(stateInput(), config);
   const readyToTrade = await assertReadyToTrade(stateInput(), config);
   const balance = await assertBalance(stateInput(), config);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.47.2",
+  "version": "0.47.4",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"

package/site/assets/help-recipes.json

@@ -52,6 +52,7 @@
       "instruction": "Use static call references for unchanged sub-journeys. Keep preparation, action, assertion, evidence, and guaranteed teardown visible as separate nodes with human-facing intent.",
       "details": [
         "Use idempotent ensure actions for required start state and independently assert their postconditions.",
+        "Inspect existing state before creating or cleaning fixtures. Establish only prerequisites required by the claim; a history or display check may already have usable records and need no trade or cleanup. Record the selected records and verify they still satisfy the proof boundary.",
         "Actions translate stable UI, CDP, or controller operations. Recipes compose them. Product code owns business rules."
       ],
       "commands": []