@deeeed/metamask-harness 0.66.3 → 0.67.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 0.67.0 - 2026-09-28
+
+### Fixed
+
+- Wait for asynchronous debug-page consent state updates without accepting missing values; retain immediate validation of authoritative background state.
+- Clarify fixture lifetime and consistent evidence-package handling in the version-matched recipe guide.
+
+### Added
+
+- Prefer capture-helper recording and concurrent screenshots for physical Android through an owned mirror; retain native frame/proof timing for Android and framed Extension, with explicit fallback provenance. Keep finalized footage when optional timing is unavailable, and reject unsafe timing sidecars.
+
+### Changed
+
+- Pin protocol 0.32.0, recipe-harness 0.20.0, agent-runtime 0.15.0 and expo-recipe 0.12.1 from npm for recording timelines and one HTML QA report.
+
 ## 0.66.3 - 2026-09-27
 
 ### Changed

package/dist/adapters/mobile/video-recorder.js

@@ -1,6 +1,7 @@
 import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { optionalVideoTiming } from "@farmslot/recipe-harness";
 import {
   ANDROID_RECORDING_TARGET_PREFIX,
   IOS_SIMULATOR_RECORDING_TARGET_PREFIX
@@ -146,6 +147,7 @@ async function startAndroidRecording(serial, request) {
     );
   }
   const remotePath = `/sdcard/Download/mm-harness-recipe-${Date.now()}-${process.pid}.mp4`;
+  const startedAtUnixMs = Date.now();
   const child = spawn(
     "adb",
     ["-s", serial, ...androidScreenrecordArgs(remotePath)],
@@ -170,6 +172,7 @@ async function startAndroidRecording(serial, request) {
           RECORDING_STOP_TIMEOUT_MS,
           "Android screenrecord"
         );
+        const stoppedAtUnixMs = Date.now();
         fs.mkdirSync(path.dirname(request.outputPath), { recursive: true });
         const pull = runAdb(serial, ["pull", remotePath, request.outputPath]);
         if (pull.status !== 0) {
@@ -182,6 +185,7 @@ async function startAndroidRecording(serial, request) {
           throw new Error(`Android recording output is empty: ${request.outputPath}`);
         }
         return {
+          ...await optionalVideoTiming(request.outputPath, { startedAtUnixMs, stoppedAtUnixMs }),
           recorder: {
             name: "adb-screenrecord",
             platform: "android",
@@ -195,6 +199,7 @@ async function startAndroidRecording(serial, request) {
   };
 }
 function androidTargetSerial(request) {
+  if (request.target.kind === "android-device") return request.target.serial;
   if (request.target.kind !== "window-id") return void 0;
   if (!request.target.windowId.startsWith(ANDROID_RECORDING_TARGET_PREFIX)) return void 0;
   return request.target.windowId.slice(ANDROID_RECORDING_TARGET_PREFIX.length) || void 0;

package/dist/recording-target.js

@@ -29,8 +29,8 @@ function createMetaMaskRecordingTargetProvider(adapter) {
             );
           }
           return {
-            kind: "window-id",
-            windowId: `${ANDROID_RECORDING_TARGET_PREFIX}${androidSerial}`
+            kind: "android-device",
+            serial: androidSerial
           };
         }
         const simulator = resolveMobileIosSimulatorName(context.env);
@@ -52,6 +52,9 @@ function resolveAndroidDeviceSerial(env = process.env) {
   return env.ADB_SERIAL?.trim() || process.env.ADB_SERIAL?.trim() || void 0;
 }
 function captureHelperSupportsRecordSessionSnapshots(projectRoot) {
+  return captureHelperSupportsCapability(projectRoot, "record_session_snapshot");
+}
+function captureHelperSupportsCapability(projectRoot, capability) {
   const result = spawnSync(captureHelperPath(), ["version", "--json"], {
     cwd: projectRoot,
     encoding: "utf8"
@@ -59,7 +62,7 @@ function captureHelperSupportsRecordSessionSnapshots(projectRoot) {
   if (result.status !== 0) return false;
   try {
     const parsed = JSON.parse(result.stdout);
-    return Array.isArray(parsed.capabilities) && parsed.capabilities.includes("record_session_snapshot");
+    return Array.isArray(parsed.capabilities) && parsed.capabilities.includes(capability);
   } catch {
     return false;
   }
@@ -142,6 +145,7 @@ function readTextFile(file) {
 export {
   ANDROID_RECORDING_TARGET_PREFIX,
   IOS_SIMULATOR_RECORDING_TARGET_PREFIX,
+  captureHelperSupportsCapability,
   captureHelperSupportsRecordSessionSnapshots,
   createMetaMaskRecordingTargetProvider,
   resolveAndroidDeviceSerial,

package/dist/run-recording.js

@@ -1,8 +1,10 @@
 import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { optionalVideoTiming, readCaptureHelperTiming, writeRecordingTimeline } from "@farmslot/recipe-harness";
 import {
   captureHelperSupportsRecordSessionSnapshots,
+  captureHelperSupportsCapability,
   resolveExtensionBrowserPid
 } from "./recording-target.js";
 const activeRecordingsByPid = /* @__PURE__ */ new Map();
@@ -38,6 +40,7 @@ async function startRecipeRecording(adapter, projectRoot, artifactsDir, options)
     outputPath
   );
   let child;
+  const startedAtUnixMs = Date.now();
   try {
     child = spawn(captureHelperPath(), [...recordArgs, "--output", stagedPath], {
       cwd: projectRoot,
@@ -50,6 +53,8 @@ async function startRecipeRecording(adapter, projectRoot, artifactsDir, options)
   }
   const recording = {
     child,
+    startedAtUnixMs,
+    nativeTiming: captureHelperSupportsCapability(projectRoot, "record_session_timing_v1"),
     outputPath,
     stagingDir,
     stagedPath,
@@ -78,6 +83,7 @@ async function startRecipeRecording(adapter, projectRoot, artifactsDir, options)
     recording.exited = true;
   });
   child.on("close", (exitCode) => {
+    recording.stoppedAtUnixMs = Date.now();
     recording.exited = true;
     recording.exitCode = exitCode;
     activeRecordingsByPid.delete(recording.pid);
@@ -131,14 +137,14 @@ async function stopRecipeRecording(recording, result) {
   recording.finalized = true;
   try {
     await stopRecordingProcess(recording);
-    const validation = validateRecordingArtifact(recording);
+    const validation = await validateRecordingArtifact(recording);
     if (validation.ok === false) {
       throw new Error(
         `capture-helper recording did not produce a usable video artifact: ${validation.reason}`
       );
     }
     publishRecordingArtifact(recording);
-    if (result) addRecordingArtifactToManifest(result, recording);
+    if (result) await addRecordingArtifactToManifest(result, recording);
   } catch (error) {
     if (result) removeRecordingArtifactFromManifest(result, recording.relativePath);
     throw error;
@@ -210,6 +216,10 @@ function handleRecordingEventLine(recording, line) {
   if (event.type === "info" && typeof event.msg === "string" && /^record frames=[1-9]\d*$/.test(event.msg)) {
     recording.frameReady = true;
   }
+  if (event.type === "record_complete" && event.output === recording.stagedPath) {
+    recording.completedVideo = typeof event.frames === "number" && event.frames > 0;
+    if (typeof event.recording_id === "string") recording.completedRecordingId = event.recording_id;
+  }
   const output = typeof event.output === "string" ? event.output : void 0;
   if (!output) return;
   const pending = recording.pendingSnapshots.get(output);
@@ -233,7 +243,7 @@ function rejectPendingSnapshots(recording, error) {
   }
   recording.pendingSnapshots.clear();
 }
-function validateRecordingArtifact(recording) {
+async function validateRecordingArtifact(recording) {
   if (!fs.existsSync(recording.stagedPath)) {
     return { ok: false, reason: `missing output ${recording.stagedPath}` };
   }
@@ -247,6 +257,11 @@ function validateRecordingArtifact(recording) {
   }
   const recorderOutput = `${recording.stdout}
 ${recording.stderr}`;
+  if (recording.nativeTiming) {
+    if (!recording.completedVideo) return { ok: false, reason: "Missing finalized video completion" };
+    recording.nativeTimingEvidence = await readNativeRecordingTiming(recording);
+    return { ok: true };
+  }
   if (!recorderOutput.includes("record_complete")) {
     return {
       ok: false,
@@ -276,6 +291,19 @@ ${recording.stderr}`;
   }
   return { ok: true };
 }
+async function readNativeRecordingTiming(recording) {
+  try {
+    if (!recording.completedRecordingId) throw new Error("Missing native recording completion identity");
+    const sidecar = recording.stagedPath + ".timing.json";
+    const entry = fs.lstatSync(sidecar);
+    if (!entry.isFile() || entry.isSymbolicLink()) throw new Error("Native timing must be a regular file");
+    const native = JSON.parse(fs.readFileSync(sidecar, "utf8"));
+    if (native.recording_id !== recording.completedRecordingId) throw new Error("Native recording identity mismatch");
+    return await readCaptureHelperTiming(recording.stagedPath);
+  } catch (error) {
+    return { timingUnavailableReason: error instanceof Error ? error.message : String(error) };
+  }
+}
 function preparePrivateRecordingDestination(artifactsDir, outputPath) {
   const outputDir = path.dirname(outputPath);
   ensureRecordingDirectory(path.resolve(artifactsDir), outputDir);
@@ -311,26 +339,36 @@ Next: replace ${JSON.stringify(directory)} with a regular directory and retry th
   );
 }
 function publishRecordingArtifact(recording) {
+  publishPrivateRecordingFile(recording.stagedPath, recording.outputPath);
+  if (recording.nativeTimingEvidence?.timing) {
+    try {
+      publishPrivateRecordingFile(recording.stagedPath + ".timing.json", recording.outputPath + ".timing.json");
+    } catch (error) {
+      recording.nativeTimingEvidence = { timingUnavailableReason: error instanceof Error ? error.message : String(error) };
+    }
+  }
+}
+function publishPrivateRecordingFile(sourcePath, outputPath) {
   const noFollow = fs.constants.O_NOFOLLOW ?? 0;
   let descriptor;
   try {
-    descriptor = fs.openSync(recording.stagedPath, fs.constants.O_RDONLY | noFollow);
+    descriptor = fs.openSync(sourcePath, fs.constants.O_RDONLY | noFollow);
     const stagedStat = fs.fstatSync(descriptor);
     if (!stagedStat.isFile()) {
-      throw unsafeRecordingArtifactError(recording.stagedPath);
+      throw unsafeRecordingArtifactError(sourcePath);
     }
     fs.fchmodSync(descriptor, 384);
   } catch (error) {
     if (error instanceof Error && error.message.includes("Next:")) throw error;
     throw unsafeRecordingArtifactError(
-      recording.stagedPath,
+      sourcePath,
       error instanceof Error ? error.message : String(error)
     );
   } finally {
     if (descriptor !== void 0) fs.closeSync(descriptor);
   }
-  refuseRecordingDestinationSymlink(recording.outputPath);
-  fs.renameSync(recording.stagedPath, recording.outputPath);
+  refuseRecordingDestinationSymlink(outputPath);
+  fs.renameSync(sourcePath, outputPath);
 }
 function refuseRecordingDestinationSymlink(outputPath) {
   try {
@@ -375,7 +413,7 @@ function restoreActiveRecordingEnvironment(recording) {
   }
   process.env[ACTIVE_EXTENSION_RECORDING_PID] = recording.previousActiveRecordingPid;
 }
-function addRecordingArtifactToManifest(result, recording) {
+async function addRecordingArtifactToManifest(result, recording) {
   const manifestPath = result.artifactManifestPath;
   if (!manifestPath || !fs.existsSync(manifestPath)) {
     console.error(`WARN: cannot add video artifact to missing artifact manifest: ${manifestPath ?? "<unset>"}`);
@@ -384,6 +422,23 @@ function addRecordingArtifactToManifest(result, recording) {
   const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
   if (!Array.isArray(manifest.artifacts)) manifest.artifacts = [];
   manifest.artifacts = manifest.artifacts.filter((artifact) => artifact.path !== recording.relativePath);
+  const timing = recording.nativeTiming ? recording.nativeTimingEvidence ?? { timingUnavailableReason: "Native recording timing unavailable" } : await optionalVideoTiming(recording.outputPath, {
+    startedAtUnixMs: recording.startedAtUnixMs,
+    stoppedAtUnixMs: recording.stoppedAtUnixMs ?? Date.now()
+  });
+  if (recording.nativeTimingEvidence?.timing) manifest.artifacts.push({ path: recording.relativePath + ".timing.json", type: "json", category: "system", label: "Native recording and screenshot timing" });
+  let timelinePath;
+  let timelineUnavailableReason = timing.timingUnavailableReason;
+  if (timing.timing) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(result.tracePath, "utf8"));
+      const trace = Array.isArray(raw) ? raw : raw.entries;
+      timelinePath = await writeRecordingTimeline(path.dirname(manifestPath), recording.relativePath, timing.timing, trace);
+      manifest.artifacts.push({ path: timelinePath, type: "json", label: "Recording frames and action markers", category: "system" });
+    } catch (error) {
+      timelineUnavailableReason = error instanceof Error ? error.message : String(error);
+    }
+  }
   manifest.artifacts.push({
     path: recording.relativePath,
     type: "video",
@@ -391,6 +446,7 @@ function addRecordingArtifactToManifest(result, recording) {
     category: "evidence",
     mimeType: "video/mp4",
     record: "full_run",
+    ...timelinePath ? { timelinePath } : { timelineUnavailableReason },
     metadata: {
       provider: "capture-helper",
       mode: "full_run",

package/dist/runner.js

@@ -1,5 +1,6 @@
 import { execFileSync, execSync } from "node:child_process";
 import { OFFICIAL_RECIPE_ACTIONS } from "@farmslot/protocol";
+import { createAndroidMirrorVideoRecorder } from "@farmslot/recipe-harness";
 import { createMetaMaskAdapters, createMetaMaskUiTransport } from "./adapters.js";
 import {
   bridgeCommand,
@@ -138,7 +139,7 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     logger,
     recording: {
       targetProvider: createMetaMaskRecordingTargetProvider(adapter),
-      ...androidRecordingSerial ? { videoRecorder: createAndroidVideoRecorder(androidRecordingSerial) } : iosRecordingSimulator ? {
+      ...androidRecordingSerial ? { videoRecorder: createAndroidMirrorVideoRecorder({ serial: androidRecordingSerial, fallback: createAndroidVideoRecorder(androidRecordingSerial) }) } : iosRecordingSimulator ? {
         videoRecorder: createIosSimulatorVideoRecorder(iosRecordingSimulator)
       } : {}
     },

package/library/actions/extension/analytics/consent.mjs

@@ -85,10 +85,12 @@ export function consentControllerExpression({
         throw new Error('Extension consent state is unavailable.');
       }
       const metamask = root?.metamask ?? root ?? {};
-      if (
+      // Debug UI state can lag an acknowledged setter until the next UI sync.
+      // Background/snapshot reads have no such subscription to wait for.
+      if ((capturedChrome || !storeState) && (
         typeof metamask.optedIn !== 'boolean' ||
         typeof metamask.dataCollectionForMarketing !== 'boolean'
-      ) {
+      )) {
         throw new Error('Extension consent state did not contain boolean consent fields.');
       }
       return {
@@ -118,6 +120,10 @@ export function consentControllerExpression({
         }
         await new Promise((resolve) => setTimeout(resolve, 100));
       } while (Date.now() < deadline);
+      if (typeof result?.state.optedIn !== 'boolean' ||
+          typeof result?.state.dataCollectionForMarketing !== 'boolean') {
+        throw new Error('Extension consent state did not contain boolean consent fields before the deadline.');
+      }
       throw new Error(
         'Consent state did not settle to ' + JSON.stringify(expected) +
         '; got ' + JSON.stringify(result?.state) + '.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.66.3",
+  "version": "0.67.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -20,11 +20,11 @@
     "check:syntax": "find . -name '*.mjs' -print0 | xargs -0 -n1 node --check"
   },
   "dependencies": {
-    "@farmslot/agent-runtime": "0.14.0",
-    "@farmslot/expo-recipe": "0.12.0",
+    "@farmslot/agent-runtime": "0.15.0",
+    "@farmslot/expo-recipe": "0.12.1",
     "@farmslot/handoff": "^0.3.1",
-    "@farmslot/protocol": "0.31.0",
-    "@farmslot/recipe-harness": "0.19.0",
+    "@farmslot/protocol": "0.32.0",
+    "@farmslot/recipe-harness": "0.20.0",
     "agent-device": "0.19.3",
     "commander": "^12.0.0",
     "es-module-lexer": "2.3.1",

package/site/assets/help-recipes.json

@@ -95,7 +95,7 @@
       "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.",
+        "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. Record fixture identity and lifetime: terminal records cannot prove active behavior, and restarting can erase in-memory history. Re-establish expired prerequisites explicitly before the proof window.",
         "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.",
         "Put identical cross-adapter graphs in recipes/shared/<domain>/ and platform variants in recipes/<adapter>/<domain>/. Both keep the same domain.recipe name; an adapter variant takes precedence. Keep platform differences in actions when the journey is identical. Verify discovery, execution, and callers before removing duplicates.",
@@ -232,7 +232,8 @@
           "adapters": [
             "core"
           ]
-        }
+        },
+        "Use fixtures that make the intended and incorrect outcomes differ. For changing geometry or values, declare the observation window and compare the same entity and inputs; do not select only favorable samples. Promote trace, screenshots, video and provenance as one immutable package, and inspect replacement image bytes again."
       ],
       "commands": [
         "mm-harness run ./proof.recipe.json --artifacts-dir temp/recipe-proof --json",