@deeeed/metamask-harness 0.50.2 → 0.50.3

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 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.
+- Color human recipe help while keeping JSON plain; clarify recipe composition, Extension timing capture, acceptance criteria, and team-library updates.
+- Make architecture topics expandable and correct cheatsheet platform, recording, and recipe examples.
+
 ## 0.50.2 - 2026-09-08
 
 - Remove Mobile receipt actions that require unpublished app/SDK APIs; reject stale receipt-based assertion and cleanup inputs before execution.

package/README.md

@@ -158,6 +158,10 @@ mm-harness run --list
 Shared libraries hold durable actions and composable recipes. Task acceptance
 criteria remain task-local. See [Recipes](docs/RECIPES.md).
 
+Teams maintain their library checkouts. Update them before starting a task;
+the harness records local revisions and recipe digests but does not fetch or
+check for upstream updates. Keep the selected library unchanged during a run.
+
 ## Recover
 
 ```bash

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

@@ -441,6 +441,16 @@ async function decideExtensionReadiness(target, options = {}) {
       reasons: ["Build is fresh and the extension runtime is healthy over CDP."],
       actions: []
     },
+    {
+      when: cdp.errorCode === "EXTENSION_BACKGROUND_UNRESPONSIVE",
+      decision: "blocked",
+      reasonCode: "background-unresponsive",
+      reasons: [
+        "Extension startup failed; inspect the background error before relaunching or resetting wallet state.",
+        ...cdp.findings?.slice(0, 3) ?? []
+      ],
+      actions: []
+    },
     {
       when: cdp.errorCode === "EVM_RPC_EXECUTION_FAILED",
       decision: "blocked",
@@ -492,6 +502,13 @@ async function decideExtensionReadiness(target, options = {}) {
         reasons: [`Release artifact ${releaseArtifact.expectedVersion} is intact and healthy over CDP.`],
         actions: []
       },
+      {
+        when: cdp.errorCode === "EXTENSION_BACKGROUND_UNRESPONSIVE",
+        decision: "blocked",
+        reasonCode: "background-unresponsive",
+        reasons: ["Extension startup failed; inspect the background error before relaunching or resetting wallet state.", ...cdp.findings?.slice(0, 3) ?? []],
+        actions: []
+      },
       {
         when: cdp.errorCode === "EVM_RPC_EXECUTION_FAILED",
         decision: "blocked",

package/dist/adapters/extension/runtime.js

@@ -51,7 +51,7 @@ async function assertHealthyExtensionRuntime(options) {
       pageMode: options.pageMode
     });
     if (lastReport.status === "PASS") return lastReport;
-    if (lastReport.errorCode === "UI_COMPOSITOR_SUSPENDED") {
+    if (lastReport.errorCode === "UI_COMPOSITOR_SUSPENDED" || lastReport.errorCode === "EXTENSION_BACKGROUND_UNRESPONSIVE") {
       throw new Error(formatHealthFailure(lastReport, options.projectRoot));
     }
     await sleep(500);
@@ -151,6 +151,23 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
       };
     }
     const runtime = await evaluateHealth(session, cdpCallTimeoutMs);
+    if (runtime.backgroundUnresponsive === true) {
+      return {
+        status: "FAIL",
+        errorCode: "EXTENSION_BACKGROUND_UNRESPONSIVE",
+        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."],
+        details: {
+          projectRoot,
+          targetUrls: targets.map((entry) => entry.url).filter(Boolean),
+          runtime
+        }
+      };
+    }
     if (runtime.hasSubmitRequest !== true) {
       const providerProbe = await probeUiEthereumProvider(session, cdpCallTimeoutMs);
       runtime.evmRpcProbeOk = providerProbe.ok;
@@ -160,9 +177,6 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
     if (runtime.href && !String(runtime.href).startsWith("chrome-extension://")) {
       findings.push(`Extension page href is not an extension URL: ${runtime.href}`);
     }
-    if (runtime.backgroundUnresponsive === true) {
-      findings.push("Extension UI reports background connection unresponsive.");
-    }
     if (runtime.ethereumConnectionUnavailable === true) {
       findings.push('Extension UI reports "Unable to connect to Ethereum".');
     }

package/dist/commands/help.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { color } from "../cli-color.js";
 import { detectAdapter } from "../harness.js";
 import { optionString, parseArgs, targetPath } from "./parse-args.js";
 const UNSCOPED_NEXT = "cd into a MetaMask checkout or pass --adapter <mobile|extension|core>";
@@ -48,21 +49,22 @@ function recipeHelpPayload(topic, harnessVersion, adapter, target) {
   };
 }
 function renderRecipeHelp(topic, harnessVersion, adapter) {
+  const paint = (style, text) => color(style, text, { stream: process.stdout });
   const lines = [
-    `mm-harness ${harnessVersion} recipe guide`,
-    `Context: Recipe Protocol v${topic.recipeProtocolVersion}, adapter ${adapter}`,
+    paint("bold", `mm-harness ${harnessVersion} recipe guide`),
+    paint("dim", `Context: Recipe Protocol v${topic.recipeProtocolVersion}, adapter ${adapter}`),
     topic.summary,
     topic.capabilities,
-    topic.scopeNotice,
-    "Visual tutorial: mm-harness tutorial"
+    paint("warn", topic.scopeNotice),
+    `Visual tutorial: ${paint("cmd", "mm-harness tutorial")}`
   ];
-  if (adapter === "unscoped") lines.push(`No MetaMask checkout detected. Next: ${UNSCOPED_NEXT}.`);
+  if (adapter === "unscoped") lines.push(paint("warn", `No MetaMask checkout detected. Next: ${UNSCOPED_NEXT}.`));
   for (const [index, section] of scopedSections(topic, adapter).entries()) {
-    lines.push("", `${index + 1}. ${section.title}`, `   ${section.instruction}`);
+    lines.push("", paint("label", `${index + 1}. ${section.title}`), `   ${section.instruction}`);
     for (const detail of section.details) lines.push(`   - ${detail}`);
-    for (const command of section.commands) lines.push(`   $ ${command}`);
+    for (const command of section.commands) lines.push(`   $ ${paint("cmd", command)}`);
   }
-  lines.push("", `Safety: ${topic.safety}`);
+  lines.push("", `${paint("warn", "Safety:")} ${topic.safety}`);
   return `${lines.join("\n")}
 `;
 }

package/dist/commands/launch/index.js

@@ -310,6 +310,16 @@ async function handleLaunchLocked(argv, stream) {
       exitCode: EXIT.infra
     });
   }
+  if (adapter === "extension" && attempt.output.includes("EXTENSION_BACKGROUND_UNRESPONSIVE:")) {
+    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.",
+      recoverable: false,
+      userAction: `mm-harness logs --target ${shellQuote(target)} --full`,
+      exitCode: EXIT.runtime,
+      originalError: attempt.output.trim() || void 0
+    });
+  }
   if (adapter === "extension" && attempt.output.includes("EVM_RPC_EXECUTION_FAILED:")) {
     return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: "EVM_RPC_EXECUTION_FAILED",

package/docs/QA.md

@@ -56,8 +56,8 @@ mm-harness verify
 - [ ] Bad input fails before runtime work with a stable code and one exact next
   action.
 - [ ] `doctor --fix` is idempotent and does not choose a fixture or launch.
-- [ ] With `capture-helper` absent, Extension reports CDP screenshots and Mobile
-  reports `simctl`/ADB screenshots; video is honestly unavailable.
+- [ ] With `capture-helper` absent, Extension reports CDP screenshots and no
+  Extension video; Mobile reports its independent simctl/ADB capture readiness.
 
 Run the bounded multi-platform preflight when all three checkouts are available:
 
@@ -177,8 +177,8 @@ Before release:
   Core scenarios.
 - [ ] Independent review approves the exact final diff.
 - [ ] Known limits are explicit: Extension requires product Infura setup;
-  Mobile requires its normal dev-client/device setup; video requires optional
-  `capture-helper`; the harness never invents funded fixtures.
+  Mobile requires its normal dev-client/device setup; Extension video requires
+  `capture-helper`, while Mobile uses platform recorders; the harness never invents funded fixtures.
 - [ ] Existing [Farmslot](https://farmslot.io) slots remain compatible.
 
 When a slot manager is available, repeat `runner.smoke` in one existing managed

package/docs/RECIPES.md

@@ -96,6 +96,23 @@ detached-DOM check, and idle-control comparison. A one-screen slope does not
 prove those broader claims. Check the suite's reference markers against the
 tested build before running it.
 
+### Extension timing observation
+
+First inspect `app.performance_capture` and `app.network_capture`. When the
+`recipe-performance` skill is installed, its
+`scripts/capture-extension-window.mjs --help` describes capture around a single
+command. Run that wrapper outside the recipe; a command node cannot start a
+second `mm-harness run/call` while its parent owns the checkout sandbox.
+
+For a custom observer blocked by LavaMoat, register a pre-boot script with
+`Page.addScriptToEvaluateOnNewDocument` to retain only the required native API
+reference, such as a bound `requestAnimationFrame`. Initialize it during explicit
+setup, remove the preload after use, and clean up the observer afterward. Do not
+disable scuttling, pause the debugger, or reload inside the measured window.
+Record lifecycle identity and use the application's clock for UI timing; CLI
+duration is a different measurement. Keep endpoint and readiness predicates in
+the team recipe, not a new harness action.
+
 ### Extension Perps release recipes
 
 Discover these identifiers with `run --list --adapter extension --json` and
@@ -189,6 +206,10 @@ export RECIPE_LIBRARY_PATH="perps=/path/to/experimental-metamask-recipe-perps"
 
 `perps.pro-order-setup` preserves existing orders, positions, and strategies by
 default. Its Scale, Chase, and TWAP placement callers inherit that policy.
+All three placement helpers require explicit `account` and `notional` inputs.
+Scale also requires `start_price` and `end_price`; Chase requires `max_distance`.
+Choose values for the current market and approved budget. Preserve JSON quotes
+for string parameters, for example `'notional="15"'`; inspect `--describe` first.
 When a proof requires a clean testnet market, reserve the account/market and
 compose explicit setup with `trading_state=clean_selected_testnet_market`.
 This parameter never authorizes cleanup of another task's trades.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.50.2",
+  "version": "0.50.3",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -24,7 +24,7 @@
     "@farmslot/expo-recipe": "0.9.0",
     "@farmslot/handoff": "^0.3.1",
     "@farmslot/protocol": "0.21.0",
-    "@farmslot/recipe-harness": "0.16.0",
+    "@farmslot/recipe-harness": "0.16.1",
     "agent-device": "0.19.3",
     "commander": "^12.0.0",
     "es-module-lexer": "2.3.1",

package/site/assets/help-recipes.json

@@ -94,6 +94,7 @@
       "instruction": "Use static call references for unchanged sub-journeys. Separate preparation, action, assertions, and evidence; add workflow.teardown when cleanup must run after success or failure.",
       "details": [
         "Starting conditions are ordinary nodes at the beginning of workflow, not a preconditions field. Use idempotent ensure actions and independently assert their postconditions.",
+        "Do not invoke mm-harness run/call from a command node on the same checkout: the outer run owns its sandbox. Compose actions or call child recipes instead. External measurement wrappers may invoke one root run, with preparation outside it; never bypass the lock.",
         "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.",
         "Match history-query ranges to the dates of existing visible records before declaring fixtures missing. Sample only sections needed for change detection; fetch one-time corroborating history once, and count background calls as well as graph nodes.",
         "Actions translate UI, CDP, or controller operations. Recipes compose them. Product code owns business rules. Teams own specialized journeys in their libraries; the harness retains shared capabilities and a small set of composable examples.",
@@ -188,6 +189,10 @@
           ]
         },
         "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"]
+        },
         "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.",