@deeeed/metamask-harness 0.50.3 → 0.50.4

package/CHANGELOG.md

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