@deeeed/metamask-harness 0.51.7 → 0.51.9

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## Unreleased
+
+## 0.51.9 - 2026-09-16
+
+### Changed
+
+- Recipe guidance states how Perps testnet account state is handled: on an account or market the task owns, the proof converges the positions and orders it needs (team library `perps.ensure-market-state` / `perps.clean-market-testnet`, or Mobile/Core `ensure_positions` / `ensure_orders` with `mode=all` for strays) instead of refusing on a pre-existing position; Extension `ensure_*` stay assertion-only. `help`, `docs/RECIPES.md`, and the Perps mutation action descriptions say so. Mainnet stays read-only.
+
+## 0.51.8 - 2026-09-15
+
+### Fixed
+
+- Mobile launch replaces a Metro process that Metro itself reported unusable (delta-graph corruption after a commit failed mid-way, or its "Detected a change in babel.config.js. Restart the server" advisory) by stopping it before `start-metro`, keeping the transform cache. Previously every "restart Metro" verdict and the `metro.restarted` recovery reused the live listener, so a Metro that outlived a bundler-config change failed every bundle until someone killed it by hand. Plain bundle errors still never restart Metro, and `--clear` stays explicit. `start-metro` now records the content hashes of the bundler config files so an advisory raised by an mtime-only touch is ignored; a Metro started before this release has no record, so its first advisory restarts it once.
+
 ## 0.51.7 - 2026-09-14
 
 ### Added

package/adapters/mobile/start-metro.sh

@@ -257,6 +257,27 @@ printf '(Full log: %s — mm-harness logs | mm-harness logs --full)\n' "$LOG_FIL
 ROTATION_REASON="metro-start"
 [ "$CLEAR" = true ] && ROTATION_REASON="clear-cache-restart"
 node "$METRO_LOG_GENERATION" "$LOG_DIR" "$PORT" "$ROTATION_REASON" >/dev/null || exit 1
+# Record what this process loads from the files Expo's FileNotifier watches, so
+# the readiness decision can tell a real config change from an mtime-only touch
+# when Metro later prints its "Detected a change in <file>" advisory.
+record_metro_config_hashes() {
+  local file hash hashes=""
+  for file in babel.config.js metro.config.js metro.transform.js app.json app.config.js; do
+    [ -f "$TARGET/$file" ] || continue
+    if command -v shasum >/dev/null 2>&1; then
+      hash="$(shasum -a 256 "$TARGET/$file" | cut -d' ' -f1)"
+    else
+      hash="$(sha256sum "$TARGET/$file" | cut -d' ' -f1)"
+    fi
+    # An entry without a hash could never match and would force a restart on
+    # every advisory; leave the file out so the decision fails closed to
+    # "changed" for that file only, visibly.
+    [ -n "$hash" ] || continue
+    hashes+="$hash  $file"$'\n'
+  done
+  printf '%s' "$hashes" > "$LOG_DIR/metro-config.sha256"
+}
+record_metro_config_hashes
 
 write_metro_build_env || {
   printf 'start-metro: could not stage the scoped Metro environment\n' >&2

package/adapters/mobile/stop-metro.sh

@@ -6,7 +6,8 @@
 set -euo pipefail
 
 TARGET="."
-PORT="${WATCHER_PORT:-}"
+# Same fallback order as start-metro so stop and start always agree on the port.
+PORT="${WATCHER_PORT:-${METRO_PORT:-}}"
 while [ $# -gt 0 ]; do
   case "$1" in
     --target) TARGET="$2"; shift 2 ;;
@@ -14,7 +15,7 @@ while [ $# -gt 0 ]; do
     -h|--help)
       printf 'Usage: stop-metro.sh [--target <dir>] [--port <port>]\n'
       printf '  --target  MetaMask Mobile checkout directory\n'
-      printf '  --port    Metro port (default: WATCHER_PORT env, else the slot context, else 8081)\n'
+      printf '  --port    Metro port (default: WATCHER_PORT env, else METRO_PORT, else the slot context, else 8081)\n'
       exit 0
       ;;
     *) printf 'stop-metro: unknown arg: %s\n' "$1" >&2; exit 2 ;;
@@ -63,6 +64,7 @@ set +e
 rm -f "$PID_FILE"
 rm -f "$LOG_DIR/metro-launch.json"
 rm -f "$LOG_DIR/metro-build-env.sh"
+rm -f "$LOG_DIR/metro-config.sha256"
 
 # start-metro runs a per-checkout console-forwarder holding the device debugger
 # slot; Metro going down must take it too, or the orphan keeps polling and later

package/dist/adapters/mobile/prepare.js

@@ -386,6 +386,11 @@ async function dispatchAction(action, target, platform, json, preflightMode = "f
       const leaf = path.join(runnerDir, "adapters/mobile/yarn-setup.sh");
       return spawnScriptStreaming(leaf, ["--target", cwd], target, POD_PROBE_ENV);
     }
+    case "stop-metro": {
+      const leaf = path.join(runnerDir, "adapters/mobile/stop-metro.sh");
+      const port = watcherPort ?? Number(process.env.WATCHER_PORT || process.env.METRO_PORT || 8081);
+      return spawnScriptStreaming(leaf, ["--target", cwd, "--port", String(port)], target);
+    }
     case "start-metro": {
       const leaf = path.join(runnerDir, "adapters/mobile/start-metro.sh");
       const extra = action.argv ?? [];

package/dist/adapters/mobile/runtime-decision.js

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import {
@@ -16,6 +17,12 @@ import { mobileProductMarkers } from "./deps-markers.js";
 import { mobileMetroEnvCheck } from "./metro-env.js";
 const BUNDLE_ERR = /Bundling failed|Unable to resolve /u;
 const BUNDLE_OK = /Bundled \d+ms|iOS Bundled|Android Bundled|Finished bundling/u;
+const METRO_GRAPH_ROLLBACK = /attempted to roll back a graph commit but there were still changes/u;
+const METRO_GRAPH_COMMIT_THROW = /Got unexpected undefined/u;
+const METRO_GRAPH_FRAME = /DeltaBundler\/Graph\.js/u;
+const METRO_RESTART_ADVISORY = /Detected a change in ([\w.-]+)\. Restart the server/u;
+const METRO_REASON_MAX = 200;
+const METRO_CONFIG_HASHES_FILE = "metro-config.sha256";
 const NATIVE_MODULE_STALE = /\[runtime not ready\].*HybridObject "([^"]+)" - It has not yet been registered in the Nitro Modules HybridObjectRegistry/u;
 function resolveMetroLog(target, metroLog) {
   const abs = metroLog ? path.isAbsolute(metroLog) ? metroLog : path.join(target, metroLog) : recipeRuntimePath(target, "metro.log");
@@ -87,6 +94,46 @@ function appRunningOnDevice(platform) {
     return false;
   }
 }
+function metroConfigUnchangedSinceStart(target, relative) {
+  let recorded;
+  try {
+    recorded = fs.readFileSync(recipeRuntimePath(target, METRO_CONFIG_HASHES_FILE), "utf8");
+  } catch {
+    return false;
+  }
+  const entry = recorded.split("\n").find((line) => line.endsWith(`  ${relative}`));
+  if (!entry) return false;
+  try {
+    const current = createHash("sha256").update(fs.readFileSync(path.join(target, relative))).digest("hex");
+    return entry.startsWith(current);
+  } catch {
+    return false;
+  }
+}
+function metroProcessUnusable(target, logText) {
+  const lines = logText.split("\n");
+  let lastOk = -1;
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    if (BUNDLE_OK.test(lines[i])) {
+      lastOk = i;
+      break;
+    }
+  }
+  for (let i = lines.length - 1; i > lastOk; i -= 1) {
+    if (METRO_GRAPH_ROLLBACK.test(lines[i])) return lines[i].trim().slice(0, METRO_REASON_MAX);
+    if (METRO_GRAPH_COMMIT_THROW.test(lines[i]) && lines.slice(i + 1, i + 4).some((frame) => METRO_GRAPH_FRAME.test(frame))) {
+      return lines[i].trim().slice(0, METRO_REASON_MAX);
+    }
+  }
+  const advised = /* @__PURE__ */ new Set();
+  for (const line of lines) {
+    const advisory = METRO_RESTART_ADVISORY.exec(line);
+    if (!advisory || advised.has(advisory[1])) continue;
+    advised.add(advisory[1]);
+    if (!metroConfigUnchangedSinceStart(target, advisory[1])) return advisory[0];
+  }
+  return null;
+}
 const launchActions = (target, clearMetro = false) => {
   const actions = [];
   actions.push({
@@ -218,6 +265,21 @@ async function computeMobileReadiness(resolved, options, fast) {
       ]
     };
   }
+  const unusable = metro.status !== "down" && metroLog.reason !== "unresolved-module" ? metroProcessUnusable(resolved, metroLogText) : null;
+  if (unusable) {
+    return {
+      schemaVersion: 1,
+      adapter: "mobile",
+      target: resolved,
+      decision: "launch",
+      reasonCode: "metro-restart-required",
+      reasons: [
+        `Metro reported its process unusable ("${unusable}"); restarting Metro and keeping its transform cache. Pass --clear-metro only if the same failure returns in the new process.`
+      ],
+      checks,
+      actions: [{ id: "stop-metro", cwd: resolved }, ...launchActions(resolved)]
+    };
+  }
   if (metroLog.status === "errors") {
     const depsSatisfied = deps.status === "current";
     if (depsSatisfied && (metroLog.reason === "stale-bundle-error" || metroLog.reason === "bundle-error")) {

package/docs/RECIPES.md

@@ -192,10 +192,26 @@ transitions must use an explicitly funded leaf action.
 The Perps team library owns `perps.clean-market-testnet` for Mobile and Core,
 not Extension. Register that library before discovery or execution.
 They require explicit `account`, `market` and `exclusive_testnet_market=true`.
-That confirmation does not reserve the market or authorize deleting someone
-else's trades. Plan first and execute only with actual task ownership.
+That confirmation does not reserve the market. Plan first and execute with
+actual task ownership; on an account or market the task owns, converge the
+state the proof needs (see Testnet account state) instead of refusing.
 Planning or calling a recipe never weakens those gates.
 
+### Testnet account state
+
+On a testnet account or market the task owns for its run (the slot's fixture
+account, or one reserved with `exclusive_testnet_market=true`), converging is an
+explicit, ownership-scoped setup choice, not a violation. Use the team library's
+`perps.ensure-market-state` or `perps.clean-market-testnet`, or on Mobile and
+Core `metamask.perps.ensure_positions` / `metamask.perps.ensure_orders`
+(`mode=all` for strays), record what was closed in the trace, then prove. A
+pre-existing position or order on an account the task owns is never a reason to
+block, skip, or refuse; a fixture that demands an empty account must converge
+rather than refuse. Extension `ensure_*` and `teardown_state` only assert, so
+converge there through an explicitly funded leaf action. Never broaden cleanup
+onto an account or market the task does not own; obtain an owned one instead
+of blocking. Mainnet is read-only.
+
 ### Mobile advanced-order setup
 
 These recipes belong to the Perps team library. Register it once:
@@ -389,9 +405,11 @@ The Perps team library's `perps.trading-lifecycle` combines the Core long market
 and limit examples. The harness retains read-only `perps.smoke` and
 `perps.snapshot` examples; trading policy belongs to the team library.
 It requires an explicit fixture account, market, and confirmation of exclusive
-testnet ownership. Initial assertions refuse non-flat state rather than clearing
-it. Failure-path cleanup is guarded by completed initial assertions and remains
-market-scoped, so it cannot safely share that account/market with another task.
+testnet ownership. Its initial assertions refuse non-flat state rather than
+clearing it, so a task proof converges its owned account first (see Testnet
+account state). Failure-path cleanup is guarded by completed
+initial assertions and remains market-scoped, so it cannot safely share that
+account/market with another task.
 The limit branch uses the original 30%-below-mid offset; it must prove the order
 rests rather than assume it cannot fill. These trading paths still require live
 validation with a reserved funded testnet account.

package/library/manifests/core.action-manifest.json

@@ -1157,7 +1157,7 @@
       ]
     },
     "metamask.perps.close_positions": {
-      "description": "core Close selected live Perps positions on HyperLiquid testnet by driving the headless perps controller closePosition() through the full signing/provider path. Testnet only.",
+      "description": "core Close selected live Perps positions on HyperLiquid testnet by driving the headless perps controller closePosition() through the full signing/provider path. Testnet only. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {
@@ -1427,7 +1427,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.ensure_positions": {
-      "description": "core Higher-level wrapper that reads selected positions, places or closes via the headless controller as needed, then asserts the final position state. Testnet only.",
+      "description": "core Higher-level wrapper that reads selected positions, places or closes via the headless controller as needed, then asserts the final position state. Testnet only. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {
@@ -1580,7 +1580,7 @@
       ]
     },
     "metamask.perps.close_orders": {
-      "description": "Core Perps cancellation selects current orders by market/side or mode=all, then dispatches and verifies those exact order IDs. Missing or duplicate selected IDs fail before dispatch. Requires authorized signing and task-owned selection; defaults to testnet.",
+      "description": "Core Perps cancellation selects current orders by market/side or mode=all, then dispatches and verifies those exact order IDs. Missing or duplicate selected IDs fail before dispatch. Requires authorized signing and task-owned selection; defaults to testnet. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {
@@ -1914,7 +1914,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.ensure_orders": {
-      "description": "core Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested.Higher-level wrapper that reads selected orders, cancels when needed, then asserts final order state.",
+      "description": "core Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested.Higher-level wrapper that reads selected orders, cancels when needed, then asserts final order state. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {

package/library/manifests/extension.action-manifest.json

@@ -4018,7 +4018,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.close_orders": {
-      "description": "extension Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Cancel selected live Perps open orders. Use selector/mode params to cancel matching symbols or all orders.",
+      "description": "extension Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Cancel selected live Perps open orders. Use selector/mode params to cancel matching symbols or all orders. Extension ensure_* only assert existing state; converge an owned testnet account through an explicitly funded leaf action. Mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {
@@ -4595,7 +4595,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.ensure_positions": {
-      "description": "Read and assert the selected Extension Perps position state without creating or closing a position. Use an explicitly funded leaf action for any transition.",
+      "description": "Read and assert the selected Extension Perps position state without creating or closing a position. Use an explicitly funded leaf action for any transition. Extension ensure_* only assert existing state; converge an owned testnet account through an explicitly funded leaf action. Mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {
@@ -4724,7 +4724,7 @@
       ]
     },
     "metamask.perps.ensure_orders": {
-      "description": "Read and assert the selected Extension Perps order state without creating or canceling an order. Use an explicitly funded leaf action for any transition.",
+      "description": "Read and assert the selected Extension Perps order state without creating or canceling an order. Use an explicitly funded leaf action for any transition. Extension ensure_* only assert existing state; converge an owned testnet account through an explicitly funded leaf action. Mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {

package/library/manifests/mobile.action-manifest.json

@@ -2395,7 +2395,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.close_positions": {
-      "description": "mobile Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Close selected live Perps positions. Use selector/mode params to close matching symbols or all positions.",
+      "description": "mobile Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Close selected live Perps positions. Use selector/mode params to close matching symbols or all positions. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {
@@ -2486,7 +2486,7 @@
       "execution_capabilities": ["app-mutation", "external-mutation"]
     },
     "metamask.perps.close_orders": {
-      "description": "mobile Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Cancel selected live Perps open orders. Use selector/mode params to cancel matching symbols or all orders.",
+      "description": "mobile Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Cancel selected live Perps open orders. Use selector/mode params to cancel matching symbols or all orders. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {
@@ -2886,7 +2886,7 @@
       "execution_capabilities": []
     },
     "metamask.perps.ensure_positions": {
-      "description": "mobile Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Higher-level wrapper that reads selected positions, closes or places when needed, then asserts final position state.",
+      "description": "mobile Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Higher-level wrapper that reads selected positions, closes or places when needed, then asserts final position state. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {
@@ -3002,7 +3002,7 @@
       "execution_capabilities": ["app-mutation", "external-mutation"]
     },
     "metamask.perps.ensure_orders": {
-      "description": "mobile Converge selected testnet orders to open or absent, then independently assert the final state. Creating an open state uses a resting limit order.",
+      "description": "mobile Converge selected testnet orders to open or absent, then independently assert the final state. Creating an open state uses a resting limit order. Pre-existing testnet state on an account the task owns is converged, not refused; mainnet is never mutated.",
       "schema": {
         "type": "object",
         "properties": {

package/package.json

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

package/site/assets/help-recipes.json

@@ -191,12 +191,15 @@
         "Performance: define a measured window, exclude setup, and compare equivalent builds, devices, and lifecycle conditions; action duration alone is not app latency.",
         {
           "text": "For Extension timing, inspect app.performance_capture/app.network_capture and the installed recipe-performance capture-extension-window.mjs helper before writing a collector. If LavaMoat blocks an observation API, capture its reference before initialization via Page.addScriptToEvaluateOnNewDocument during explicit setup, not inside the measured window. Keep domain predicates in the team recipe; see docs/RECIPES.md#extension-timing-observation.",
-          "adapters": ["extension"]
+          "adapters": [
+            "extension"
+          ]
         },
         "Retain samples and declared limits when a measurement fails. For memory growth, compare an equal-duration idle control before attributing it to navigation; do not raise the budget to make the run pass.",
         "Analytics: verify the collection destination and existing consent before capture. Changing participation or marketing consent requires operator approval and restoration of the prior settings; a recipe's hardcoded opt-in is not permission. Missing collection prerequisites are not missing product events.",
         "Flake risk: wait on observable state instead of sleeping, keep device and runtime identity explicit, and never overwrite a prior run's artifacts.",
-        "Mutation: require an independent state assertion and identity-bound receipt. Bind activity to that operation's accepted ID; an old row or nonzero count is insufficient. Opening and closing orders have different IDs. Schedule authorized cleanup in teardown, verify its result, and report any residue. Testnet cleanup must not cancel another task's orders or close its positions.",
+        "Mutation: require an independent state assertion and identity-bound receipt. Bind activity to that operation's accepted ID; an old row or nonzero count is insufficient. Opening and closing orders have different IDs. Schedule authorized cleanup in teardown, verify its result, and report any residue. Testnet cleanup closes what the task opened and never silently undoes another task's live proof on a reserved account or market.",
+        "Testnet account state: on a testnet account or market the task owns for its run (the slot's fixture account, or one reserved with exclusive_testnet_market=true), converging is an explicit, ownership-scoped setup choice, not a violation. Use the team library's perps.ensure-market-state or perps.clean-market-testnet, or on Mobile and Core metamask.perps.ensure_positions / metamask.perps.ensure_orders (mode=all for strays), record what was closed in the trace, then prove. A pre-existing position or order on an account the task owns is never a reason to block, skip, or refuse, and a fixture that demands an empty account must converge rather than refuse. Extension ensure_* and teardown_state only assert; converge there through an explicitly funded leaf action. Never broaden cleanup onto an account or market the task does not own; obtain an owned one instead of blocking. Mainnet is read-only.",
         {
           "text": "An accepted order can fill before the UI updates. Preserve its receipt even when the expected resting-order assertion fails; one empty read does not prove cleanup. Check the read API's cache and freshness options before adding polling. Reconcile returned margin against the pre-placement balance. A successful close does not turn the original failed proof into a pass.",
           "adapters": [