@deeeed/metamask-harness 0.14.7 → 0.15.0

package/library/actions/mobile/perps/perps.mjs

@@ -1,5 +1,6 @@
 import { pathToFileURL } from 'node:url';
 import { evalAsync, navigate, runAdapter } from '../platform/bridge.mjs';
+import { ensureUnlocked } from '../wallet/ensure_unlocked.mjs';
 
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -637,6 +638,17 @@ async function applyTutorialState(input, config) {
 export async function startState(input) {
   const params = paramsForState(input);
   const config = mergeStateConfig(profileDefaults(params.profile), params);
+  // Product edits require an app restart before proof. Mobile relocks on restart,
+  // so a deterministic Perps start state must restore the fixture-backed wallet
+  // prerequisite before it navigates or converges controller state.
+  const wallet = await ensureUnlocked({
+    ...input,
+    action: 'metamask.wallet.ensure_unlocked',
+    node: { ...input.node, action: 'metamask.wallet.ensure_unlocked' },
+  });
+  // Entering Perps initializes the provider client on a freshly launched app.
+  // State reads before this navigation fail with CLIENT_NOT_INITIALIZED.
+  const navigation = await applyStateNavigation(input, config);
   const provider = await ensureProvider(input, config);
   const network = await ensureNetwork(input, config);
   const tutorial = await applyTutorialState(input, config);
@@ -644,11 +656,11 @@ export async function startState(input) {
   const balance = await assertBalance(input, config);
   const orders = await applyOrdersState(input, config.orders);
   const positions = await applyPositionsState(input, config.positions);
-  const navigation = await applyStateNavigation(input, config);
   return {
     action: input.action,
     profile: config.profile ?? params.profile ?? 'clean_market_testnet',
     phase: 'start_state',
+    wallet,
     provider,
     network,
     tutorial,

package/library/actions/mobile/platform/bridge.mjs

@@ -1,4 +1,6 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { constants as fsConstants } from 'node:fs';
+import { mkdir, open, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
 import path from 'node:path';
@@ -405,25 +407,54 @@ export async function simulatorScreenshot(input, relPath) {
   const adbSerial = targetInfo.adbSerial;
   const platform = String(input.node?.platform ?? process.env.PLATFORM ?? '').toLowerCase();
   if (androidTarget || adbSerial || platform === 'android') {
-    return androidScreenshot(input, relPath, adbSerial);
+    return androidScreenshot(input, relPath);
   }
   const target = targetInfo.iosSimulator;
   if (!target) {
+    const { absolute } = resolveArtifactPath(input.context.artifactsDir, relPath || `screenshots/${input.context.nodeId}.png`);
+    await rm(absolute, { force: true });
     throw new Error('iOS screenshot requires node.simulator, node.ios_simulator, or IOS_SIMULATOR so the proof is tied to the same device as the bridge commands.');
   }
   const { relative, absolute } = resolveArtifactPath(input.context.artifactsDir, relPath || `screenshots/${input.context.nodeId}.png`);
   await mkdir(path.dirname(absolute), { recursive: true });
-  const result = await new Promise((resolve, reject) => {
-    const child = spawn('xcrun', ['simctl', 'io', String(target), 'screenshot', absolute], { stdio: ['ignore', 'pipe', 'pipe'] });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { stdout += chunk; });
-    child.stderr.on('data', (chunk) => { stderr += chunk; });
-    child.on('error', reject);
-    child.on('close', (exitCode) => resolve({ exitCode, stdout, stderr }));
-  });
-  if (result.exitCode !== 0) {
-    throw new Error(`simctl screenshot failed for ${target}: ${result.stderr || result.stdout}`);
+  await rm(absolute, { force: true });
+  let temporaryDirectory;
+  try {
+    temporaryDirectory = await createScreenshotTemporaryDirectory(absolute);
+    const captured = path.join(temporaryDirectory, 'captured.png');
+    await createPrivateScreenshotFile(captured);
+    let result;
+    try {
+      result = await runScreenshotProcess('xcrun', ['simctl', 'io', String(target), 'screenshot', captured], false);
+    } catch (error) {
+      throw new Error(
+        `simctl screenshot could not start for ${target}: ${error instanceof Error ? error.message : String(error)}\n` +
+        '  Next: install Xcode Command Line Tools (`xcode-select --install`), then rerun the same mm-harness command.',
+      );
+    }
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `simctl screenshot failed for ${target}: ${result.stderr || result.stdout}\n` +
+        `  Next: mm-harness doctor --adapter mobile --device ${target} --json`,
+      );
+    }
+    const png = await readPrivateScreenshotFile(captured);
+    const invalid = pngStructureError(png);
+    if (invalid) {
+      throw new Error(
+        `simctl screenshot produced invalid PNG bytes for ${target}: ${invalid}\n` +
+        `  Next: mm-harness doctor --adapter mobile --device ${target} --json`,
+      );
+    }
+    await publishPrivateScreenshot(png, temporaryDirectory, absolute);
+    await rm(temporaryDirectory, { recursive: true, force: true });
+  } catch (error) {
+    await removeScreenshotResidue(temporaryDirectory, absolute);
+    if (String(error?.message ?? error).includes('\n  Next:')) throw error;
+    throw new Error(
+      `simctl screenshot could not publish for ${target}: ${error instanceof Error ? error.message : String(error)}\n` +
+      `  Next: mm-harness doctor --adapter mobile --device ${target} --json`,
+    );
   }
   return {
     path: relative,
@@ -431,35 +462,277 @@ export async function simulatorScreenshot(input, relPath) {
     nodeId: input.context.nodeId,
     label: input.node?.description || `${input.action} screenshot`,
     category: 'evidence',
+    mimeType: 'image/png',
+    metadata: {
+      provider: 'simctl',
+      mode: 'xcrun simctl io screenshot',
+      selectedDevice: String(target),
+    },
   };
 }
 
-async function androidScreenshot(input, relPath, androidDevice) {
+async function androidScreenshot(input, relPath) {
   const { relative, absolute } = resolveArtifactPath(input.context.artifactsDir, relPath || `screenshots/${input.context.nodeId}.png`);
   await mkdir(path.dirname(absolute), { recursive: true });
-  const args = [];
-  if (androidDevice) args.push('-s', String(androidDevice));
-  args.push('exec-out', 'screencap', '-p');
-  const result = await new Promise((resolve, reject) => {
-    const child = spawn('adb', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+  await rm(absolute, { force: true });
+  let temporaryDirectory;
+  try {
+    temporaryDirectory = await createScreenshotTemporaryDirectory(absolute);
+    const adbSerial = await resolveAndroidScreenshotSerial(input);
+    let result;
+    try {
+      result = await runScreenshotProcess('adb', ['-s', adbSerial, 'exec-out', 'screencap', '-p'], true);
+    } catch (error) {
+      throw new Error(
+        `adb screenshot could not start for ${adbSerial}: ${error instanceof Error ? error.message : String(error)}\n` +
+        '  Next: install Android SDK Platform-Tools, ensure adb is on PATH, then rerun the same mm-harness command.',
+      );
+    }
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `adb screenshot failed for ${adbSerial}: ${result.stderr}\n` +
+        `  Next: mm-harness doctor --adapter mobile --device ${adbSerial} --json`,
+      );
+    }
+    const invalid = pngStructureError(result.stdout);
+    if (invalid) {
+      throw new Error(
+        `adb screenshot produced invalid PNG bytes for ${adbSerial}: ${invalid}\n` +
+        `  Next: mm-harness doctor --adapter mobile --device ${adbSerial} --json`,
+      );
+    }
+    await publishPrivateScreenshot(result.stdout, temporaryDirectory, absolute);
+    await rm(temporaryDirectory, { recursive: true, force: true });
+    return {
+      path: relative,
+      type: 'screenshot',
+      nodeId: input.context.nodeId,
+      label: input.node?.description || `${input.action} screenshot`,
+      category: 'evidence',
+      mimeType: 'image/png',
+      metadata: {
+        provider: 'adb',
+        mode: 'adb exec-out screencap -p',
+        selectedDevice: adbSerial,
+      },
+    };
+  } catch (error) {
+    await removeScreenshotResidue(temporaryDirectory, absolute);
+    if (String(error?.message ?? error).includes('\n  Next:')) throw error;
+    throw new Error(
+      `adb screenshot could not publish: ${error instanceof Error ? error.message : String(error)}\n` +
+      '  Next: mm-harness doctor --adapter mobile --json',
+    );
+  }
+}
+
+async function resolveAndroidScreenshotSerial(input) {
+  const contextEnv = input.context?.env || {};
+  const explicit = input.node?.adb_serial ??
+    input.node?.android_device ??
+    input.node?.device ??
+    contextEnv.ADB_SERIAL ??
+    contextEnv.ANDROID_SERIAL ??
+    contextEnv.ANDROID_DEVICE ??
+    process.env.ADB_SERIAL ??
+    process.env.ANDROID_SERIAL ??
+    process.env.ANDROID_DEVICE;
+  if (explicit !== undefined && explicit !== null && String(explicit).trim()) return String(explicit).trim();
+
+  let result;
+  try {
+    result = await runScreenshotProcess('adb', ['devices'], false);
+  } catch (error) {
+    throw new Error(
+      `Android screenshot could not resolve an adb serial: ${error instanceof Error ? error.message : String(error)}\n` +
+      '  Next: install Android SDK Platform-Tools, ensure adb is on PATH, then rerun with --device <adb-serial>.',
+    );
+  }
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `Android screenshot could not resolve an adb serial: ${result.stderr || result.stdout}\n` +
+      '  Next: mm-harness doctor --adapter mobile --json',
+    );
+  }
+  const serials = result.stdout
+    .split(/\r?\n/u)
+    .map((line) => line.trim().split(/\s+/u))
+    .filter((fields) => fields.length >= 2 && fields[1] === 'device')
+    .map(([serial]) => serial);
+  if (serials.length === 1) return serials[0];
+  throw new Error(
+    `Android screenshot requires one exact adb serial, but ${serials.length} ready devices were discovered.\n` +
+    '  Next: mm-harness doctor --adapter mobile --json   # choose devices[].id and rerun with --device <id>',
+  );
+}
+
+function runScreenshotProcess(command, args, binaryOutput) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
     const stdout = [];
     let stderr = '';
     child.stdout.on('data', (chunk) => { stdout.push(Buffer.from(chunk)); });
     child.stderr.on('data', (chunk) => { stderr += chunk; });
     child.on('error', reject);
-    child.on('close', (exitCode) => resolve({ exitCode, stdout: Buffer.concat(stdout), stderr }));
+    child.on('close', (exitCode) => resolve({
+      exitCode,
+      stdout: binaryOutput ? Buffer.concat(stdout) : Buffer.concat(stdout).toString('utf8'),
+      stderr,
+    }));
   });
-  if (result.exitCode !== 0) {
-    throw new Error(`adb screenshot failed${androidDevice ? ` for ${androidDevice}` : ''}: ${result.stderr}`);
+}
+
+function pngStructureError(bytes) {
+  const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  if (!Buffer.isBuffer(bytes) || bytes.length < signature.length || !bytes.subarray(0, signature.length).equals(signature)) {
+    return `bad signature (${Buffer.isBuffer(bytes) ? bytes.length : 0} bytes)`;
   }
-  await writeFile(absolute, result.stdout);
-  return {
-    path: relative,
-    type: 'screenshot',
-    nodeId: input.context.nodeId,
-    label: input.node?.description || `${input.action} screenshot`,
-    category: 'evidence',
+  let offset = signature.length;
+  let sawHeader = false;
+  let sawPalette = false;
+  let sawImageData = false;
+  let imageDataClosed = false;
+  let colorType;
+  let bitDepth;
+  while (offset < bytes.length) {
+    if (bytes.length - offset < 12) return `truncated chunk at byte ${offset}`;
+    const length = bytes.readUInt32BE(offset);
+    const typeBytes = bytes.subarray(offset + 4, offset + 8);
+    const type = typeBytes.toString('ascii');
+    const end = offset + 12 + length;
+    if (end > bytes.length) return `truncated ${type || 'unknown'} chunk at byte ${offset}`;
+    if (![...typeBytes].every((byte) => (byte >= 65 && byte <= 90) || (byte >= 97 && byte <= 122))) {
+      return `invalid chunk type at byte ${offset}`;
+    }
+    const expectedCrc = bytes.readUInt32BE(offset + 8 + length);
+    const actualCrc = pngCrc32(bytes, offset + 4, offset + 8 + length);
+    if (actualCrc !== expectedCrc) return `CRC mismatch for ${type} chunk at byte ${offset}`;
+    if (!sawHeader && (type !== 'IHDR' || length !== 13)) return `first chunk must be IHDR length 13 (got ${type} length ${length})`;
+    if (type === 'IHDR') {
+      if (sawHeader) return 'duplicate IHDR chunk';
+      const invalidHeader = pngHeaderError(bytes.subarray(offset + 8, offset + 8 + length));
+      if (invalidHeader) return invalidHeader;
+      sawHeader = true;
+      bitDepth = bytes[offset + 16];
+      colorType = bytes[offset + 17];
+    } else if (type === 'PLTE') {
+      if (sawPalette) return 'duplicate PLTE chunk';
+      if (sawImageData) return 'PLTE chunk must precede IDAT';
+      if (colorType === 0 || colorType === 4) return `PLTE chunk is forbidden for color type ${colorType}`;
+      if (length === 0 || length % 3 !== 0 || length > 768) return `invalid PLTE length ${length}`;
+      if (colorType === 3 && length / 3 > 2 ** bitDepth) return `PLTE has too many entries for bit depth ${bitDepth}`;
+      sawPalette = true;
+    } else if (type === 'IDAT') {
+      if (imageDataClosed) return 'IDAT chunks must be consecutive';
+      if (colorType === 3 && !sawPalette) return 'indexed-color PNG requires PLTE before IDAT';
+      sawImageData = true;
+    } else {
+      if (sawImageData) imageDataClosed = true;
+      if (type[0] === type[0].toUpperCase() && type !== 'IEND') return `unknown critical chunk ${type}`;
+    }
+    if (type === 'IEND') {
+      if (length !== 0) return `IEND length must be 0 (got ${length})`;
+      if (!sawImageData) return 'missing IDAT chunk';
+      if (end !== bytes.length) return `trailing bytes after IEND (${bytes.length - end})`;
+      return null;
+    }
+    offset = end;
+  }
+  return sawHeader ? 'missing IEND chunk' : 'missing IHDR chunk';
+}
+
+function pngHeaderError(header) {
+  const width = header.readUInt32BE(0);
+  const height = header.readUInt32BE(4);
+  const bitDepth = header[8];
+  const colorType = header[9];
+  const allowedDepths = {
+    0: [1, 2, 4, 8, 16],
+    2: [8, 16],
+    3: [1, 2, 4, 8],
+    4: [8, 16],
+    6: [8, 16],
   };
+  if (width === 0 || width > 0x7fffffff || height === 0 || height > 0x7fffffff) {
+    return `invalid IHDR dimensions ${width}x${height}`;
+  }
+  if (!allowedDepths[colorType]) return `invalid IHDR color type ${colorType}`;
+  if (!allowedDepths[colorType].includes(bitDepth)) return `invalid IHDR bit depth ${bitDepth} for color type ${colorType}`;
+  if (header[10] !== 0) return `invalid IHDR compression method ${header[10]}`;
+  if (header[11] !== 0) return `invalid IHDR filter method ${header[11]}`;
+  if (header[12] !== 0 && header[12] !== 1) return `invalid IHDR interlace method ${header[12]}`;
+  return null;
+}
+
+const PNG_CRC_TABLE = Uint32Array.from({ length: 256 }, (_, value) => {
+  let crc = value;
+  for (let bit = 0; bit < 8; bit += 1) crc = (crc & 1) === 1 ? 0xedb88320 ^ (crc >>> 1) : crc >>> 1;
+  return crc >>> 0;
+});
+
+function pngCrc32(bytes, start, end) {
+  let crc = 0xffffffff;
+  for (let index = start; index < end; index += 1) crc = PNG_CRC_TABLE[(crc ^ bytes[index]) & 0xff] ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+async function createScreenshotTemporaryDirectory(absolute) {
+  const temporary = path.join(path.dirname(absolute), `.${path.basename(absolute)}.${process.pid}.${randomUUID()}.tmp`);
+  await mkdir(temporary, { mode: 0o700 });
+  return temporary;
+}
+
+async function createPrivateScreenshotFile(file) {
+  const handle = await open(
+    file,
+    fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW,
+    0o600,
+  );
+  try {
+    const stats = await handle.stat();
+    if (!stats.isFile() || stats.nlink !== 1) throw new Error('temporary screenshot is not a private regular file');
+  } finally {
+    await handle.close();
+  }
+}
+
+async function readPrivateScreenshotFile(file) {
+  let handle;
+  try {
+    handle = await open(file, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK);
+    const stats = await handle.stat();
+    if (!stats.isFile() || stats.nlink !== 1) throw new Error('captured screenshot is not a private regular file');
+    return await handle.readFile();
+  } catch (error) {
+    throw new Error(`captured screenshot is not a safe regular file: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    await handle?.close();
+  }
+}
+
+async function publishPrivateScreenshot(png, temporaryDirectory, absolute) {
+  const publication = path.join(temporaryDirectory, 'validated.png');
+  const handle = await open(
+    publication,
+    fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW,
+    0o600,
+  );
+  try {
+    const stats = await handle.stat();
+    if (!stats.isFile() || stats.nlink !== 1) throw new Error('validated screenshot is not a private regular file');
+    await handle.writeFile(png);
+    await handle.sync();
+    await rename(publication, absolute);
+  } finally {
+    await handle.close();
+  }
+}
+
+async function removeScreenshotResidue(temporaryDirectory, absolute) {
+  await Promise.all([
+    temporaryDirectory ? rm(temporaryDirectory, { recursive: true, force: true }) : Promise.resolve(),
+    rm(absolute, { force: true }),
+  ]);
 }
 
 function resolveArtifactPath(artifactsDir, relativePath) {

package/library/actions/mobile/wallet/ensure_unlocked.mjs

@@ -1,4 +1,5 @@
 import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
 import { bridgeCommand, runAdapter, selectBridgeStatusEntry } from '../platform/bridge.mjs';
 import { walletFixturePath } from '../../harness-exports.mjs';
 
@@ -108,7 +109,7 @@ async function waitForStableUnlocked(input, initialStatus, stableMs = 750) {
   return last;
 }
 
-runAdapter(async (input) => {
+export async function ensureUnlocked(input) {
   const before = await waitForTargetStatus(input, Number(input.node?.target_timeout_ms ?? 20000));
   if (!selectedAccount(before, input) && routeName(before, input) !== 'Login') {
     throw new Error(
@@ -153,4 +154,8 @@ runAdapter(async (input) => {
       proofPath: 'agentic-wallet-status-after-missing-login-input',
     };
   }
-});
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runAdapter(ensureUnlocked);
+}

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

@@ -118,7 +118,7 @@
           },
           "hash": {
             "type": "string",
-            "description": "Raw extension hash, e.g. #/?tab=perps."
+            "description": "Raw extension hash, e.g. #/perps-home."
           },
           "path": {
             "type": "string",
@@ -148,7 +148,7 @@
           "description": "Fallback to a raw extension hash when no alias exists",
           "node": {
             "action": "ui.navigate",
-            "hash": "#/?tab=perps",
+            "hash": "#/perps-home",
             "intent": "Open a raw extension route"
           }
         }
@@ -190,6 +190,24 @@
     },
     "ui.wait_for": {
       "description": "Wait for a UI condition through the Extension CDP adapter.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "action": { "const": "ui.wait_for" },
+          "selector": { "type": "string" },
+          "text": { "type": "string" },
+          "expected": {
+            "type": "string",
+            "enum": ["present", "absent", "visible", "hidden", "not_present"]
+          },
+          "visible": {
+            "type": "boolean",
+            "description": "Convenience alias: true means expected=visible; false means expected=absent."
+          },
+          "timeout_ms": { "type": "number" }
+        },
+        "required": ["action"]
+      },
       "examples": [
         {
           "node": {
@@ -197,11 +215,20 @@
             "text": "Perps",
             "intent": "Wait for visible Extension text"
           }
+        },
+        {
+          "node": {
+            "action": "ui.wait_for",
+            "selector": "[data-testid=example]",
+            "visible": false,
+            "timeout_ms": 2000,
+            "intent": "Prove an Extension element is absent"
+          }
         }
       ]
     },
     "ui.screenshot": {
-      "description": "Capture visual evidence through capture-helper snapshot; the runner registers the screenshot artifact automatically. CDP/DOM-raster fallback is not valid Extension evidence.",
+      "description": "Capture registered visual evidence through capture-helper, bounded Chrome-native capture, or an explicitly labeled computed-style DOM raster fallback. Always read the resulting PNG; artifact metadata records the provider.",
       "examples": [
         {
           "node": {
@@ -1717,15 +1744,8 @@
             }
           },
           "page": {
-            "oneOf": [
-              {
-                "type": "string"
-              },
-              {
-                "const": false
-              }
-            ],
-            "description": "Final page target; false skips navigation for teardown."
+            "type": "string",
+            "description": "Initial Perps page target; omit it to use the profile or market default. Extension start_state always enters Perps before convergence."
           },
           "positions": {
             "oneOf": [

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

@@ -191,6 +191,20 @@
     },
     "ui.wait_for": {
       "description": "Wait for a mounted React Native testID/test_id. Optional text validates text returned by that testID; text alone is not supported on Mobile.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "action": { "const": "ui.wait_for" },
+          "test_id": { "type": "string" },
+          "text": { "type": "string" },
+          "expected": {
+            "type": "string",
+            "enum": ["present", "absent", "hidden", "not_present"]
+          },
+          "timeout_ms": { "type": "number" }
+        },
+        "required": ["action", "test_id"]
+      },
       "examples": [
         {
           "node": {
@@ -199,11 +213,19 @@
             "expected": "present",
             "intent": "Wait for a React Native testID to be mounted"
           }
+        },
+        {
+          "node": {
+            "action": "ui.wait_for",
+            "test_id": "conditional-banner",
+            "expected": "absent",
+            "intent": "Prove a React Native testID is not mounted"
+          }
         }
       ]
     },
     "ui.screenshot": {
-      "description": "Capture visual evidence through the platform adapter; the runner registers the screenshot artifact automatically.",
+      "description": "Capture registered PNG evidence with xcrun simctl on iOS or adb screencap on Android. Artifact metadata records the native provider, command mode, and selected device; invalid or empty PNG output fails before registration.",
       "examples": [
         {
           "node": {
@@ -676,7 +698,7 @@
       ]
     },
     "metamask.perps.start_state": {
-      "description": "Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Recommended configurable Perps start state that composes reusable domain operations before the proof window.",
+      "description": "Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Recommended configurable Perps start state that first restores the fixture-backed unlocked wallet, then composes reusable domain operations before the proof window.",
       "examples": [
         {
           "description": "Clean BTC testnet market state",
@@ -1689,7 +1711,7 @@
     {
       "name": "metamask.perps.start_state",
       "owner": "metamask",
-      "description": "mobile Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Recommended configurable Perps start state that composes reusable domain operations before the proof window.",
+      "description": "mobile Default to testnet for Perps mutations; mainnet is read-only unless explicitly requested. Recommended configurable Perps start state that first restores the fixture-backed unlocked wallet, then composes reusable domain operations before the proof window.",
       "schema": {
         "type": "object",
         "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.14.7",
+  "version": "0.15.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -16,9 +16,9 @@
     "check:syntax": "find . -name '*.mjs' -print0 | xargs -0 -n1 node --check"
   },
   "dependencies": {
-    "@farmslot/agent-runtime": "^0.1.1",
-    "@farmslot/protocol": "^0.7.6",
-    "@farmslot/recipe-harness": "^0.4.3",
+    "@farmslot/agent-runtime": "^0.2.0",
+    "@farmslot/protocol": "^0.8.0",
+    "@farmslot/recipe-harness": "^0.5.0",
     "commander": "^12.0.0",
     "viem": "^2.54.3",
     "ws": "8.21.0"
@@ -70,4 +70,4 @@
     "url": "https://github.com/MetaMask/experimental-metamask-harness/issues"
   },
   "homepage": "https://github.com/MetaMask/experimental-metamask-harness#readme"
-}
+}

package/scripts/completions.sh

@@ -29,7 +29,7 @@ _mmh_bin() {
   return 1
 }
 
-_mmh_commands="launch stop logs debug fixtures actions call flows run doctor install verify cleanup completions"
+_mmh_commands="launch stop logs debug fixtures actions call flows run doctor check checklist recipe-quality install verify cleanup completions"
 
 # Per-command flags (static, from the mm-harness surface).
 _mmh_flags_for() {
@@ -38,7 +38,8 @@ _mmh_flags_for() {
     stop)     printf '%s' "--port --target --json" ;;
     logs)     printf '%s' "--full --events --source --adapter --target --json" ;;
     debug)    printf '%s' "--worker --dev-menu --adapter --target --json" ;;
-    fixtures) printf '%s' "--fixture --adapter --target --json" ;;
+    fixtures) printf '%s' "--from --dev --force --fixture --adapter --target --json" ;;
+    checklist) printf '%s' "" ;;
     actions)  printf '%s' "--adapter --action --kind --raw --action-manifest --target --json" ;;
     call)     printf '%s' "--arg --adapter --target --artifacts-dir --action-manifest --heal --json" ;;
     flows)    printf '%s' "--library --json" ;;
@@ -76,7 +77,8 @@ if [ -n "${BASH_VERSION:-}" ]; then
 
     case "$cmd" in
       launch)      [ "$cword" -eq 2 ] && COMPREPLY=($(compgen -W "ios android" -- "$cur")) ;;
-      fixtures)    [ "$cword" -eq 2 ] && COMPREPLY=($(compgen -W "sync set" -- "$cur")) ;;
+      fixtures)    [ "$cword" -eq 2 ] && COMPREPLY=($(compgen -W "init sync set generate finalize" -- "$cur")) ;;
+      checklist)   [ "$cword" -eq 2 ] && COMPREPLY=($(compgen -W "mark" -- "$cur")) ;;
       completions) [ "$cword" -eq 2 ] && COMPREPLY=($(compgen -W "install bash zsh status" -- "$cur")) ;;
       flows)       [ "$cword" -eq 2 ] && COMPREPLY=($(compgen -W "list promote" -- "$cur")) ;;
       call)        [ "$cword" -eq 2 ] && COMPREPLY=($(compgen -W "$(_mmh_actions)" -- "$cur")) ;;
@@ -110,7 +112,8 @@ if [ -n "${ZSH_VERSION:-}" ]; then
 
     case "$cmd" in
       launch)      (( CURRENT == 3 )) && { candidates=(ios android); compadd -a candidates; } ;;
-      fixtures)    (( CURRENT == 3 )) && { candidates=(sync set); compadd -a candidates; } ;;
+      fixtures)    (( CURRENT == 3 )) && { candidates=(init sync set generate finalize); compadd -a candidates; } ;;
+      checklist)   (( CURRENT == 3 )) && { candidates=(mark); compadd -a candidates; } ;;
       completions) (( CURRENT == 3 )) && { candidates=(install bash zsh status); compadd -a candidates; } ;;
       flows)       (( CURRENT == 3 )) && { candidates=(list promote); compadd -a candidates; } ;;
       call)        (( CURRENT == 3 )) && { candidates=("${(@f)$(_mmh_actions)}"); compadd -a candidates; } ;;