@deeeed/metamask-harness 0.50.3 → 0.50.5

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 0.50.5 - 2026-09-10
+
+### Fixed
+
+- Avoid disabling and re-enabling the Extension after a fresh browser launch, which could cause `No SW` storage errors in reused wallet profiles. Keep build handoff for updates in an already-running browser.
+- Keep the previously focused macOS app in front while Chrome starts, instead of restoring only after CDP is up. Do not let caffeinate declare user activity during that launch.
+
+## 0.50.4 - 2026-09-10
+
+- Distinguish Extension startup/provider absence from attempted RPC failures and preserve diagnosed failed tabs during verification.
+- Bind Mobile native Perps observations to a stable development navigation route when available, and include route/screen context in surface errors.
+- Add an interactive workflow map and sourced template previews to the human tutorial, connecting tasks, skills, checklists, recipes, evidence, and optional Farmslot coordination.
+
 ## 0.50.3 - 2026-09-09
 
 - Recognize enabled form controls through recipe-harness 0.16.1; report Extension startup crashes without reload-based RPC probes or automatic relaunch recovery.

package/adapters/extension/ensure-browser.sh

@@ -301,7 +301,7 @@ const {
   runtimeIdentityArgs,
   writeRuntimeIdentity,
 } = require(path.join('${SCRIPT_DIR}', 'lib/chrome-args.cjs'));
-const { captureMacFrontmostProcess, restoreMacFrontmostProcess } = require(path.join('${SCRIPT_DIR}', 'lib/macos-focus.cjs'));
+const { captureMacFrontmostProcess, preserveMacFrontmostProcess } = require(path.join('${SCRIPT_DIR}', 'lib/macos-focus.cjs'));
 
 const SLOT_ID = '${SLOT_ID}';
 const AGENT_DIR = '${AGENT_DIR}';
@@ -345,7 +345,9 @@ const resumeWebpack = () => {
 
   const chromiumApp = path.dirname(path.dirname(path.dirname(chromium.executablePath())));
   const previousFrontmostPid = captureMacFrontmostProcess();
+  const holdOperatorFocus = () => preserveMacFrontmostProcess(previousFrontmostPid);
   execFileSync('open', ['-g', '-n', '-a', chromiumApp, '--args', ...args], { stdio: 'ignore' });
+  holdOperatorFocus();
   for (let i = 0; i < 60; i++) {
     try {
       const version = await new Promise((resolve, reject) => {
@@ -358,6 +360,7 @@ const resumeWebpack = () => {
       });
       if (version) break;
     } catch {}
+    holdOperatorFocus();
     await new Promise(r => setTimeout(r, 1000));
   }
   const browser = await chromium.connectOverCDP('http://127.0.0.1:' + CDP_PORT);
@@ -498,7 +501,7 @@ const resumeWebpack = () => {
   if (process.env.MM_HARNESS_FOCUS_BROWSER === '1') {
     await page.bringToFront().catch(() => {});
   } else {
-    restoreMacFrontmostProcess(previousFrontmostPid);
+    holdOperatorFocus();
   }
 
   fs.writeFileSync(path.join(AGENT_DIR, 'extension.id'), extId);

package/adapters/extension/launch-browser.cjs

@@ -42,7 +42,7 @@ const {
   validationLaunchQuarantineError,
   writeRuntimeIdentity,
 } = require('./lib/chrome-args.cjs');
-const { captureMacFrontmostProcess, restoreMacFrontmostProcess } = require('./lib/macos-focus.cjs');
+const { captureMacFrontmostProcess, preserveMacFrontmostProcess } = require('./lib/macos-focus.cjs');
 
 if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log(
@@ -165,6 +165,7 @@ const chromeArgs = [
 ];
 const logFd = fs.openSync(args['chrome-log'], 'a');
 const previousFrontmostPid = captureMacFrontmostProcess();
+const holdOperatorFocus = () => preserveMacFrontmostProcess(previousFrontmostPid);
 let browserPid;
 try {
   const application = process.platform === 'darwin' ? macApplicationForExecutable(args['chrome-bin']) : null;
@@ -174,7 +175,8 @@ try {
       env: sanitizedChildEnv(),
       stdio: ['ignore', logFd, logFd],
     });
-    browserPid = waitForOwnedCdpPid(cdpPort, args.profile, args['extension-dir']);
+    holdOperatorFocus();
+    browserPid = waitForOwnedCdpPid(cdpPort, args.profile, args['extension-dir'], holdOperatorFocus);
     if (browserPid === null) {
       throw new Error(`Chrome launched but did not expose CDP on 127.0.0.1:${cdpPort}`);
     }
@@ -186,7 +188,8 @@ try {
       stdio: ['ignore', logFd, logFd],
     });
     child.unref();
-    browserPid = waitForOwnedCdpPid(cdpPort, args.profile, args['extension-dir']);
+    holdOperatorFocus();
+    browserPid = waitForOwnedCdpPid(cdpPort, args.profile, args['extension-dir'], holdOperatorFocus);
     if (browserPid === null) {
       if (child.pid) terminatePids([child.pid]);
       throw new Error(
@@ -220,15 +223,13 @@ try {
   );
 }
 if (process.platform === 'darwin') {
-  const wake = spawn('caffeinate', ['-dimsu', '-w', String(browserPid)], {
+  const wake = spawn('caffeinate', ['-dims', '-w', String(browserPid)], {
     detached: true,
     stdio: 'ignore',
   });
   wake.unref();
 }
-if (process.env.MM_HARNESS_FOCUS_BROWSER !== '1') {
-  restoreMacFrontmostProcess(previousFrontmostPid);
-}
+holdOperatorFocus();
 
 function sanitizedChildEnv() {
   return {
@@ -264,12 +265,13 @@ function macApplicationForExecutable(executable) {
   return null;
 }
 
-function waitForOwnedCdpPid(port, profile, extensionDir) {
+function waitForOwnedCdpPid(port, profile, extensionDir, onWait) {
   for (let i = 0; i < 300; i += 1) {
     const pid = cdpListenerPids(port).find((candidate) =>
       processIsOwnedHarnessBrowser(candidate, profile, extensionDir),
     );
     if (pid !== undefined) return pid;
+    if (typeof onWait === 'function' && i % 10 === 0) onWait();
     spawnSync('sleep', ['0.1']);
   }
   return null;

package/adapters/extension/lib/macos-focus.cjs

@@ -29,4 +29,13 @@ function restoreMacFrontmostProcess(pid) {
   }
 }
 
-module.exports = { captureMacFrontmostProcess, restoreMacFrontmostProcess };
+function preserveMacFrontmostProcess(pid) {
+  if (process.env.MM_HARNESS_FOCUS_BROWSER === '1') return false;
+  return restoreMacFrontmostProcess(pid);
+}
+
+module.exports = {
+  captureMacFrontmostProcess,
+  preserveMacFrontmostProcess,
+  restoreMacFrontmostProcess,
+};

package/adapters/extension/live.sh

@@ -228,7 +228,6 @@ NODE
   quoted_check_infura="$(printf '%q' "$SCRIPT_DIR/check-infura-readiness.cjs")"
   quoted_stamp_title="$(printf '%q' "$SCRIPT_DIR/stamp-runtime-title.cjs")"
   quoted_chrome_launcher="$(printf '%q' "$SCRIPT_DIR/launch-browser.cjs")"
-  quoted_build_handoff="$(printf '%q' "$SCRIPT_DIR/build-handoff.cjs")"
   quoted_artifact_state="$(printf '%q' "$SCRIPT_DIR/artifact-runtime-state.cjs")"
   quoted_fixture_state="$(printf '%q' "$FIXTURE_STATE_ABS")"
   quoted_fixture_validation="$(printf '%q' "$FIXTURE_VALIDATION_ABS")"
@@ -353,7 +352,6 @@ NODE
   fi
   prepare_parts+=("$chrome_launch_cmd")
   prepare_parts+=("for i in {1..60}; do curl -fsS --max-time 1 http://127.0.0.1:${CDP_PORT}/json/version >/dev/null 2>&1 && break; sleep 1; done; curl -fsS --max-time 1 http://127.0.0.1:${CDP_PORT}/json/version >/dev/null")
-  prepare_parts+=("node ${quoted_build_handoff} --target ${quoted_target} --runtime-dist ${quoted_runtime_dist} --cdp-port ${CDP_PORT}")
   if [ -n "$WALLET_FIXTURE_ABS" ]; then
     prepare_parts+=("bash ${quoted_seed_fixture} seed-cdp --target ${quoted_target} --fixture ${quoted_wallet_fixture} --state ${quoted_fixture_state} --cdp-port ${CDP_PORT} --extension-dir ${quoted_runtime_dist} --extension-id-file ${quoted_extension_id_file} --out ${quoted_fixture_validation}")
   fi

package/dist/adapters/extension/ensure-ready.js

@@ -148,7 +148,7 @@ async function ensureExtensionReady(target, options) {
     }
   };
   let health = await checkHealth();
-  if (action === "pruned" && (health.status !== "PASS" || after !== 1)) {
+  if (action === "pruned" && !health.errorCode && (health.status !== "PASS" || after !== 1)) {
     const listing = await jsonList(cdpPort);
     if (listing.ok) {
       const existingHomeIds = new Set(

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

@@ -442,7 +442,7 @@ async function decideExtensionReadiness(target, options = {}) {
       actions: []
     },
     {
-      when: cdp.errorCode === "EXTENSION_BACKGROUND_UNRESPONSIVE",
+      when: cdp.errorCode === "EXTENSION_BACKGROUND_UNRESPONSIVE" || cdp.errorCode === "EXTENSION_STARTUP_UNVERIFIED",
       decision: "blocked",
       reasonCode: "background-unresponsive",
       reasons: [
@@ -503,7 +503,7 @@ async function decideExtensionReadiness(target, options = {}) {
         actions: []
       },
       {
-        when: cdp.errorCode === "EXTENSION_BACKGROUND_UNRESPONSIVE",
+        when: cdp.errorCode === "EXTENSION_BACKGROUND_UNRESPONSIVE" || cdp.errorCode === "EXTENSION_STARTUP_UNVERIFIED",
         decision: "blocked",
         reasonCode: "background-unresponsive",
         reasons: ["Extension startup failed; inspect the background error before relaunching or resetting wallet state.", ...cdp.findings?.slice(0, 3) ?? []],

package/dist/adapters/extension/runtime.js

@@ -151,16 +151,17 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
       };
     }
     const runtime = await evaluateHealth(session, cdpCallTimeoutMs);
-    if (runtime.backgroundUnresponsive === true) {
+    if (runtime.backgroundUnresponsive === true || runtime.hasPageContent === false) {
+      const code = runtime.backgroundUnresponsive === true ? "EXTENSION_BACKGROUND_UNRESPONSIVE" : "EXTENSION_STARTUP_UNVERIFIED";
       return {
         status: "FAIL",
-        errorCode: "EXTENSION_BACKGROUND_UNRESPONSIVE",
+        errorCode: code,
         userAction: `mm-harness logs --target ${shellQuote(projectRoot)} --full  # inspect the startup error before restarting or resetting an authorized dev fixture`,
         cdpPort,
         targetUrl: target.url,
         extensionId: safeExtensionId(target),
         extensionPageTargets: extensionTargets.length,
-        findings: ["EXTENSION_BACKGROUND_UNRESPONSIVE: Extension UI reports a startup failure or unresponsive background; RPC readiness cannot be established."],
+        findings: [`${code}: ${runtime.backgroundUnresponsive === true ? "Extension UI reports a startup failure or unresponsive background" : "Extension page has not rendered its UI"}; RPC readiness cannot be established.`],
         details: {
           projectRoot,
           targetUrls: targets.map((entry) => entry.url).filter(Boolean),
@@ -173,6 +174,7 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
       runtime.evmRpcProbeOk = providerProbe.ok;
       runtime.evmRpcProbeError = providerProbe.error;
       runtime.evmRpcProbeSource = providerProbe.source;
+      runtime.evmRpcProbeAttempted = providerProbe.requestAttempted;
     }
     if (runtime.href && !String(runtime.href).startsWith("chrome-extension://")) {
       findings.push(`Extension page href is not an extension URL: ${runtime.href}`);
@@ -181,10 +183,11 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
       findings.push('Extension UI reports "Unable to connect to Ethereum".');
     }
     const rpcExecutionFailed = runtime.evmRpcProbeOk !== true && /Failed to execute 'fetch' on 'WorkerGlobalScope': Illegal invocation/u.test(String(runtime.evmRpcProbeError));
+    const startupUnverified = runtime.evmRpcProbeOk !== true && runtime.evmRpcProbeAttempted === false;
     if (runtime.evmRpcProbeOk !== true) {
       const probeError = String(runtime.evmRpcProbeError ?? "unknown error").replace(/[.\s]+$/u, "");
       findings.push(
-        rpcExecutionFailed ? `EVM_RPC_EXECUTION_FAILED: background RPC fetch threw before an HTTP response: ${probeError}.` : `EVM RPC readiness probe failed: ${probeError}. Infura configured \u2260 RPC reachable.`
+        startupUnverified ? `EXTENSION_STARTUP_UNVERIFIED: no completed provider probe established RPC readiness: ${probeError}.` : rpcExecutionFailed ? `EVM_RPC_EXECUTION_FAILED: background RPC fetch threw before an HTTP response: ${probeError}.` : `EVM RPC readiness probe failed: ${probeError}. Infura configured \u2260 RPC reachable.`
       );
     }
     if (runtime.hasSubmitRequest === true && runtime.backgroundProbeOk !== true) {
@@ -195,8 +198,8 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
     return {
       status: findings.length === 0 ? "PASS" : "FAIL",
       ...evmRpcUnreachable ? {
-        errorCode: rpcExecutionFailed ? "EVM_RPC_EXECUTION_FAILED" : "EVM_RPC_UNREACHABLE",
-        userAction: rpcExecutionFailed ? `mm-harness logs --target ${shellQuote(projectRoot)} --full  # inspect the background fetch stack; credential resync is not indicated by this error` : evmRpcRecoveryAction(projectRoot)
+        errorCode: startupUnverified ? "EXTENSION_STARTUP_UNVERIFIED" : rpcExecutionFailed ? "EVM_RPC_EXECUTION_FAILED" : "EVM_RPC_UNREACHABLE",
+        userAction: startupUnverified ? `mm-harness logs --target ${shellQuote(projectRoot)} --full  # inspect Extension startup; upstream RPC failure has not been established` : rpcExecutionFailed ? `mm-harness logs --target ${shellQuote(projectRoot)} --full  # inspect the background fetch stack; credential resync is not indicated by this error` : evmRpcRecoveryAction(projectRoot)
       } : {},
       warnings,
       cdpPort,
@@ -332,6 +335,7 @@ async function evaluateHealth(session, timeoutMs) {
           return {
             href: location.href,
             title: document.title,
+            hasPageContent: bodyText.trim().length > 0,
             hookKeys: Object.keys(hooks),
             hasSubmitRequest: typeof hooks.submitRequestToBackground === 'function',
             hasStore: Boolean(hooks.store),
@@ -353,6 +357,7 @@ async function evaluateHealth(session, timeoutMs) {
         new Promise((resolve) => setTimeout(() => resolve({
           href: location.href,
           title: document.title,
+          hasPageContent: bodyText.trim().length > 0,
           hookKeys: Object.keys(hooks),
           hasSubmitRequest: typeof hooks.submitRequestToBackground === 'function',
           hasStore: Boolean(hooks.store),
@@ -395,7 +400,7 @@ async function probeUiEthereumProvider(session, timeoutMs) {
           value: {
             async probe() {
               if (!provider || typeof provider.request !== 'function') {
-                return { ok: false, error: 'Ethereum provider is unavailable' };
+                return { ok: false, error: 'Ethereum provider is unavailable', requestAttempted: false };
               }
               try {
                 const code = await provider.request({
@@ -405,10 +410,11 @@ async function probeUiEthereumProvider(session, timeoutMs) {
                 const ok = typeof code === 'string' && /^0x[0-9a-f]*$/iu.test(code);
                 return {
                   ok,
+                  requestAttempted: true,
                   error: ok ? null : 'Ethereum provider returned invalid contract code',
                 };
               } catch (error) {
-                return { ok: false, error: String(error?.message || error) };
+                return { ok: false, error: String(error?.message || error), requestAttempted: true };
               }
             },
             cleanup() {
@@ -432,13 +438,15 @@ async function probeUiEthereumProvider(session, timeoutMs) {
     return {
       ok: false,
       error: "Ethereum provider preload was not installed",
-      source: "ui-ethereum-provider"
+      source: "ui-ethereum-provider",
+      requestAttempted: false
     };
   }
   let outcome = {
     ok: false,
     error: "Ethereum provider is unavailable",
-    source: "ui-ethereum-provider"
+    source: "ui-ethereum-provider",
+    requestAttempted: false
   };
   const cleanupErrors = [];
   try {
@@ -453,10 +461,11 @@ async function probeUiEthereumProvider(session, timeoutMs) {
         }, Math.max(1, deadline - Date.now()));
         const value = result.result?.value;
         if (value?.ok === true) {
-          outcome = { ok: true, error: null, source: "ui-ethereum-provider" };
+          outcome = { ok: true, error: null, source: "ui-ethereum-provider", requestAttempted: true };
           break;
         }
         if (typeof value?.error === "string") outcome.error = value.error;
+        outcome.requestAttempted ||= value?.requestAttempted === true;
       } catch (error) {
         outcome.error = messageOf(error);
       }
@@ -464,7 +473,7 @@ async function probeUiEthereumProvider(session, timeoutMs) {
       await sleep(100);
     }
   } catch (error) {
-    outcome = { ok: false, error: messageOf(error), source: "ui-ethereum-provider" };
+    outcome = { ...outcome, ok: false, error: messageOf(error) };
   } finally {
     try {
       const cleanup = await boundedCdpCall(session, "Runtime.evaluate", {
@@ -494,7 +503,8 @@ async function probeUiEthereumProvider(session, timeoutMs) {
   return cleanupErrors.length > 0 ? {
     ok: false,
     error: `Ethereum provider probe cleanup failed: ${cleanupErrors.join("; ")}`,
-    source: "ui-ethereum-provider"
+    source: "ui-ethereum-provider",
+    requestAttempted: outcome.requestAttempted
   } : outcome;
 }
 function extensionBackgroundProbeTimeoutMs(cdpCallTimeoutMs) {

package/dist/commands/launch/index.js

@@ -310,10 +310,10 @@ async function handleLaunchLocked(argv, stream) {
       exitCode: EXIT.infra
     });
   }
-  if (adapter === "extension" && attempt.output.includes("EXTENSION_BACKGROUND_UNRESPONSIVE:")) {
+  if (adapter === "extension" && (attempt.output.includes("EXTENSION_BACKGROUND_UNRESPONSIVE:") || attempt.output.includes("EXTENSION_STARTUP_UNVERIFIED:"))) {
     return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
-      code: "EXTENSION_BACKGROUND_UNRESPONSIVE",
-      message: "Extension startup failed; inspect the background error before restarting or resetting wallet state.",
+      code: attempt.output.includes("EXTENSION_BACKGROUND_UNRESPONSIVE:") ? "EXTENSION_BACKGROUND_UNRESPONSIVE" : "EXTENSION_STARTUP_UNVERIFIED",
+      message: "Extension startup is not healthy; inspect the background error before restarting or resetting wallet state.",
       recoverable: false,
       userAction: `mm-harness logs --target ${shellQuote(target)} --full`,
       exitCode: EXIT.runtime,

package/library/actions/mobile/perps/read-visible-state-loop.mjs

@@ -43,7 +43,7 @@ export async function readVisiblePerpsState(
           action: input.action,
           ...normalizeVisiblePerpsState({
             route: screen.route,
-            title: screen.title,
+            title: screen.name,
             items: visible.items,
             offscreenItems: visible.hidden_or_offscreen,
             truncated: visible.truncated,

package/library/actions/mobile/platform/observe-ui.mjs

@@ -27,7 +27,24 @@ export async function observeNativeUi(payload, context) {
   if (supported.length === 0) return warnings.length ? { warnings } : {};
 
   try {
+    const env = { ...process.env, ...record(context?.env) };
+    const routeInput = { action: 'ui.observe', node: { ...record(payload?.node), bridge_timeout_ms: 2_000, cdp_timeout_ms: 2_000 }, context };
+    let routeBefore;
+    if (supported.includes('ui.screen') && !isOpaqueRuntime(env) && (env.METRO_PORT || env.WATCHER_PORT)) {
+      try {
+        routeBefore = await bridgeCommand(routeInput, ['get-route']);
+      } catch (error) {
+        warnings.push({ ref: 'ui.screen', message: `Navigation route unavailable: ${error.message}` });
+      }
+    }
     const hierarchy = await readNativeHierarchy(payload, context);
+    if (routeBefore?.name) {
+      const routeAfter = await bridgeCommand(routeInput, ['get-route']);
+      if (routeAfter?.name !== routeBefore.name || routeAfter?.key !== routeBefore.key) {
+        throw new Error('Navigation changed during native UI observation; the snapshot cannot be bound to one route.');
+      }
+      hierarchy.screen.route = routeAfter.name;
+    }
     const observations = {};
     for (const ref of supported) {
       observations[ref] = ref === 'ui.screen' ? hierarchy.screen : hierarchy.visible;

package/library/actions/shared/perps/visible-state.mjs

@@ -144,7 +144,15 @@ function marketFromTestId(testId) {
   return undefined;
 }
 
-function classifySurface(route, testIds) {
+function classifySurface(route, testIds, platform) {
+  if (platform === 'mobile') {
+    const routes = {
+      PerpsMarketListView: 'home',
+      PerpsTrendingView: 'market-list',
+      PerpsMarketDetails: 'market-details',
+    };
+    if (Object.hasOwn(routes, route)) return routes[route];
+  }
   const joined = [...testIds].join('\n');
   if (/confirm-transaction\/.*[?&]goBackTo=%2Fperps-home(?:&|$)/u.test(route)) {
     return 'funds';
@@ -213,7 +221,7 @@ export function normalizeVisiblePerpsState(raw, options, platform) {
     ? /^remove from /iu.test(favoriteLabel) : null;
   const testIds = new Set(unique.map((item) => item.testId));
   const route = text(raw.route) ?? '';
-  const surface = classifySurface(route, testIds);
+  const surface = classifySurface(route, testIds, platform);
   const marketItems = selected(
     unique,
     (item) => Boolean(marketFromTestId(item.testId)),
@@ -316,7 +324,7 @@ function assertVisibleState(state, options) {
   }
   if (options.surface !== 'auto' && state.surface !== options.surface) {
     throw new Error(
-      `Expected visible Perps surface ${options.surface}, but observed ${state.surface}.`,
+      `Expected visible Perps surface ${options.surface}, but observed ${state.surface} (route: ${state.route ?? 'unavailable'}; title: ${state.title ?? 'unavailable'}).`,
     );
   }
   if (state.markets.length < options.minimumMarketCount) {

package/package.json

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