@deeeed/metamask-harness 0.16.0 → 0.17.1

package/dist/run-diagnostics.js

@@ -1,26 +1,54 @@
 import fs from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
-import { spawn, spawnSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import { getAdapterSurface } from "./adapters/surface.js";
 import { runnerDir } from "./paths.js";
+import { ensureExtensionConsoleCapture } from "./adapters/extension/console-capture.js";
 const MAX_CAPTURE_BYTES = 512 * 1024;
 const MAX_FINDINGS = 20;
 const MAX_PREVIEW_CHARS = 320;
+function readRunDiagnosticsDocument(diagnosticsPath) {
+  if (typeof diagnosticsPath !== "string" || diagnosticsPath.length === 0) return null;
+  try {
+    const document = JSON.parse(fs.readFileSync(diagnosticsPath, "utf8"));
+    return isRunDiagnosticsDocument(document) ? document : null;
+  } catch {
+    return null;
+  }
+}
+function formatRunDiagnosticsForHuman(diagnostics, adapter) {
+  if (!diagnostics) {
+    return [adapter === "core" ? "N/A \u2014 Core is headless and has no application log source." : "UNAVAILABLE \u2014 application diagnostics could not be collected for this run."];
+  }
+  const status = diagnostics.status === "clean" ? "CLEAN" : diagnostics.status === "review" ? "REVIEW" : "UNAVAILABLE";
+  const lines = [`${status} \u2014 ${diagnostics.note}`];
+  for (const finding of diagnostics.findings) {
+    const count = finding.count > 1 ? ` \xD7${finding.count}` : "";
+    lines.push(`${finding.level.toUpperCase()}${count} \u2014 ${finding.preview}`);
+  }
+  return lines;
+}
 async function beginRunDiagnostics(adapter, projectRoot) {
   const source = getAdapterSurface(adapter).appLogSource(projectRoot);
   if (!source) return null;
   const mobileIssueBuffer = adapter === "mobile" && armMobileIssueBuffer(projectRoot) ? { projectRoot } : void 0;
-  const extensionConsoleCapture = adapter === "extension" ? await startExtensionConsoleCapture(source, projectRoot) : void 0;
+  if (adapter === "extension") {
+    await ensureExtensionConsoleCapture(projectRoot).catch(() => void 0);
+  }
   const stat = safeStat(source.path);
   return {
     source,
     offset: stat?.size ?? 0,
     ...stat ? { inode: stat.ino } : {},
-    ...mobileIssueBuffer ? { mobileIssueBuffer } : {},
-    ...extensionConsoleCapture ? { extensionConsoleCapture } : {}
+    ...mobileIssueBuffer ? { mobileIssueBuffer } : {}
   };
 }
+function isRunDiagnosticsDocument(value) {
+  if (!isRecord(value) || value.schemaVersion !== 1 || value.scope !== "recipe-run-application") return false;
+  if (value.status !== "clean" && value.status !== "review" && value.status !== "unavailable") return false;
+  return typeof value.note === "string" && Array.isArray(value.findings);
+}
 function finishRunDiagnostics(baseline, result) {
   if (!baseline) return result;
   try {
@@ -56,9 +84,7 @@ function finishRunDiagnostics(baseline, result) {
   }
 }
 function stopRunDiagnostics(baseline) {
-  const capture = baseline?.extensionConsoleCapture;
-  if (!capture || capture.exitCode !== null || capture.signalCode !== null) return;
-  capture.kill("SIGTERM");
+  void baseline;
 }
 function collectRunDiagnostics(baseline, bufferedIssues) {
   const stat = safeStat(baseline.source.path);
@@ -157,39 +183,6 @@ function runMobileIssueCommand(projectRoot, command) {
     return null;
   }
 }
-async function startExtensionConsoleCapture(source, projectRoot) {
-  const cdpPort = process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
-  if (!cdpPort) return void 0;
-  fs.mkdirSync(path.dirname(source.path), { recursive: true });
-  const before = safeStat(source.path)?.size ?? 0;
-  const script = path.join(runnerDir, "adapters", "extension", "console-tail.mjs");
-  const child = spawn(process.execPath, [script, "--cdp-port", cdpPort, "--log", source.path], {
-    cwd: projectRoot,
-    stdio: "ignore"
-  });
-  const attached = await waitForExtensionAttachment(source.path, before, child, 3e3);
-  if (attached) {
-    await delay(50);
-    return child;
-  }
-  if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM");
-  return void 0;
-}
-async function waitForExtensionAttachment(logPath, offset, child, timeoutMs) {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline && child.exitCode === null && child.signalCode === null) {
-    const stat = safeStat(logPath);
-    if (stat && stat.size > offset) {
-      const appended = readSlice(logPath, offset, Math.min(stat.size - offset, 64 * 1024));
-      if (appended.includes("[attached]")) return true;
-    }
-    await delay(50);
-  }
-  return false;
-}
-function delay(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
 function redactPreview(value) {
   return value.replace(/\b(Bearer)\s+\S+/giu, "$1 [REDACTED]").replace(/\b(password|passphrase|mnemonic|seed(?:Phrase)?|privateKey|secret|token|authorization)\b\s*[:=]\s*(?:"[^"]*"|'[^']*'|\S+)/giu, "$1=[REDACTED]").replace(/\b(?:0x)?[a-f0-9]{64,}\b/giu, "[REDACTED_HEX]").replace(/(https?:\/\/[^\s?]+)\?\S+/giu, "$1?[REDACTED_QUERY]").slice(0, MAX_PREVIEW_CHARS);
 }
@@ -267,5 +260,7 @@ export {
   beginRunDiagnostics,
   collectRunDiagnostics,
   finishRunDiagnostics,
+  formatRunDiagnosticsForHuman,
+  readRunDiagnosticsDocument,
   stopRunDiagnostics
 };

package/dist/runner.js

@@ -58,7 +58,7 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
   const logger = options.quietStdout ? new console.Console(process.stderr) : console;
   return createRecipeRunner({
     actionManifest,
-    adapters: [...core, ...ui, ...lifecycle, ...custom],
+    adapters: withActionProgress([...core, ...ui, ...lifecycle, ...custom], options.onActionEvent),
     logger,
     recording: {
       targetProvider: createMetaMaskRecordingTargetProvider(adapter)
@@ -76,6 +76,36 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
     }
   });
 }
+function withActionProgress(adapters, onActionEvent) {
+  if (!onActionEvent) return adapters;
+  return adapters.map((entry) => ({
+    ...entry,
+    async execute(node, context) {
+      const event = { nodeId: context.nodeId, action: entry.action };
+      const reportProgress = !isAutomaticHudProgress(entry.action, node, context.nodeId);
+      if (reportProgress) onActionEvent({ ...event, status: "running" });
+      try {
+        const result = await entry.execute(node, context);
+        if (reportProgress) {
+          onActionEvent({ ...event, status: result.status === "fail" ? "failed" : "passed" });
+        }
+        return result;
+      } catch (error) {
+        if (reportProgress) onActionEvent({ ...event, status: "failed" });
+        throw error;
+      }
+    }
+  }));
+}
+function isAutomaticHudProgress(action, node, nodeId) {
+  if (action !== "app.hud" || node === null || typeof node !== "object" || Array.isArray(node)) {
+    return false;
+  }
+  const payload = node;
+  if (typeof payload.action_name === "string") return true;
+  const progress = payload.progress;
+  return nodeId === "recipe-complete" && progress !== null && typeof progress === "object" && !Array.isArray(progress) && progress.complete === true;
+}
 function mobileSourceAwareLifecycleAdapters(adapter, lifecycle) {
   if (adapter !== "mobile") return lifecycle;
   return lifecycle.map((entry) => ({
@@ -120,5 +150,6 @@ export {
   createMetaMaskExtensionRunner,
   createMetaMaskMobileRunner,
   createMetaMaskRunner,
+  isAutomaticHudProgress,
   mobileSourceAwareLifecycleAdapters
 };

package/dist/runtime-context.js

@@ -53,6 +53,32 @@ function readExistingContext(contextPath, repoRoot, runtimeDir, adapter) {
   return { context, existed: true };
 }
 function validExistingContext(context, repoRoot, runtimeDir, adapter) {
+  const allowedFields = /* @__PURE__ */ new Set([
+    "schemaVersion",
+    "repoRoot",
+    "project",
+    "slotId",
+    "machine",
+    "runtimeOwner",
+    "strict",
+    "platform",
+    "runtimeDir",
+    "gitDirty",
+    "simulator",
+    "adbSerial",
+    "distDir",
+    "extensionId",
+    "gitHead",
+    "gitBranch",
+    "gitCommit",
+    "createdAt",
+    "session",
+    "cdpPort",
+    "watcherPort",
+    "metroPort",
+    "devServerPort"
+  ]);
+  if (Object.keys(context).some((field) => !allowedFields.has(field))) return false;
   if (context.schemaVersion !== void 0 && context.schemaVersion !== 1) return false;
   if (context.repoRoot !== void 0 && (typeof context.repoRoot !== "string" || path.resolve(context.repoRoot) !== repoRoot)) return false;
   if (context.platform !== void 0 && context.platform !== adapter) return false;
@@ -82,14 +108,6 @@ function validExistingContext(context, repoRoot, runtimeDir, adapter) {
     const value = context[field];
     if (value !== void 0 && (!Number.isInteger(value) || Number(value) < 1 || Number(value) > 65535)) return false;
   }
-  if (context.runtimeStart !== void 0) {
-    if (!context.runtimeStart || typeof context.runtimeStart !== "object" || Array.isArray(context.runtimeStart)) return false;
-    const runtimeStart = context.runtimeStart;
-    if (runtimeStart.approved !== void 0 && typeof runtimeStart.approved !== "boolean") return false;
-    for (const field of ["command", "readyUrl"]) {
-      if (runtimeStart[field] !== void 0 && (typeof runtimeStart[field] !== "string" || runtimeStart[field].length === 0)) return false;
-    }
-  }
   const forbiddenResources = adapter === "core" ? ["cdpPort", "watcherPort", "metroPort", "devServerPort", "simulator", "adbSerial", "extensionId"] : adapter === "extension" ? ["metroPort", "simulator", "adbSerial"] : ["cdpPort", "extensionId"];
   if (forbiddenResources.some((field) => context[field] !== void 0)) return false;
   return true;

package/docs/CHEATSHEET.md

@@ -1,61 +1,48 @@
-# mm-harness — user cheatsheet
+# mm-harness cheatsheet
 
-`mm-harness <command> [target] [flags]` · Run from inside any MetaMask checkout · Platform auto-detected
+Run inside a MetaMask checkout. Product, slot, ports, and runtime paths are
+auto-detected.
 
----
+## Operate
 
-## Daily loop
-
-| Situation | Command |
+| Need | Command |
 |---|---|
-| Start / relaunch iOS | `mm-harness launch ios` |
-| Start / relaunch Android | `mm-harness launch android` |
-| Launch extension (fullscreen) | `mm-harness launch` |
-| Launch extension in sidepanel | `mm-harness launch --sidepanel` |
-| Native code changed — rebuild first | `mm-harness launch ios --build` |
-| Tail Metro / webpack logs | `mm-harness logs` |
-| Open DevTools / RN inspector | `mm-harness debug` |
-| Seed wallet from fixture — no typing | `mm-harness fixtures set` |
-| Refresh wallet fixture files on slot | `mm-harness fixtures sync` |
-
-`launch` auto-installs the overlay on first use.
-`fixtures set` reads the password **from** the fixture — never typed.
-
----
-
-## Proof loop
-
-```
-actions  →  call <action>  →  flows  →  run recipe.json --plan  →  run recipe.json
+| Extension | `mm-harness launch` |
+| Extension sidepanel | `mm-harness launch --sidepanel` |
+| iOS / Android | `mm-harness launch ios` / `mm-harness launch android` |
+| Clean rebuild | `mm-harness launch --build` |
+| Runtime status | `mm-harness status` |
+| Logs | `mm-harness logs` |
+| Debugger | `mm-harness debug` |
+| Apply wallet fixture | `mm-harness fixtures set` |
+
+Extension log sources: `extension`, `dapp`, `webpack`, `watcher`, `rebuild`.
+Mobile log sources: `app`, `metro`.
+
+## Discover and prove
+
+```bash
+mm-harness actions positions
+mm-harness actions --action metamask.wallet.ensure_unlocked
+mm-harness call metamask.wallet.ensure_unlocked
+mm-harness flows
+mm-harness run recipe.json --plan
+mm-harness run recipe.json --artifacts-dir temp/recipe-proof
 ```
 
-| Command | What it does |
-|---|---|
-| `mm-harness actions` | Action vocabulary for this adapter |
-| `mm-harness call unlock` | One action through the real engine (fuzzy name ok) |
-| `mm-harness flows` | Reusable flows (personal > team > canonical) |
-| `mm-harness run recipe.json --plan` | Validate + print plan, no device touched; exit 5 if invalid |
-| `mm-harness run recipe.json` | Execute + write evidence (summary / trace / artifacts) |
-
----
+The run result prints diagnostics plus absolute evidence paths. Resume safely with
+`mm-harness last --json`.
 
-## Health
+## Recover
 
-| Command | What it does |
-|---|---|
-| `mm-harness doctor` | Full readiness check — fixture, runtime context, overlay. No launch. |
-| `mm-harness doctor --fix` | Repair overlay + runtime context without launching the app. |
-| `mm-harness verify` | Check overlay/runtime is present and healthy. No launch. |
-| `mm-harness cleanup` | Remove the overlay and restore the checkout. |
-
----
-
-## For agents and scripts
-
-**`--json`** — machine-readable output on every command; includes `recovered[]`, `mutations[]`, `schemaVersion`.
-
-**`--heal`** — `off` (fail fast, repro-preserving) · `infra-only` (heal transport, never wallet; `run`/`call` default) · `auto` (auto-ensure overlay + heal; `launch` default).
-
-**Exit codes** — `0` success · `1` recipe/action failed · `2` bad args / missing target · `5` validation failure (fix recipe).
+```bash
+mm-harness doctor
+mm-harness doctor --fix
+mm-harness verify
+mm-harness cleanup
+mm-harness update
+```
 
-**Tab completion** — `mm-harness completions install` prints the lines to add to `~/.zshrc` / `~/.bashrc`.
+For automation, add `--json`. Use `--json-stream` for line-delimited run progress.
+Bad input exits `2`; recipe/action failure exits `1`; recipe validation failure
+exits `5`.

package/docs/CLI-ERGONOMICS-AUDIT.md

@@ -0,0 +1,32 @@
+<!-- Generated by scripts/generate-cli-ergonomics-audit.mjs. Do not edit by hand. -->
+# CLI ergonomics audit
+
+This matrix tracks the public command surface. “Covered” means the shared preflight contract and
+`tests/contract/cli-teaching-errors.test.sh` exercise the behavior without dispatching runtime work.
+Runtime recovery is claimed only where command-specific failures return a stable `userAction`.
+Success hints are intentionally limited to lifecycle transitions with one truthful next command;
+discovery, read-only, and terminal evidence commands do not invent one. ID prefix support is N/A
+unless a command displays a shortened ID that another command accepts.
+
+| Command | Bad flag | First feedback | `--json` recovery | Success next step | Displayed ID prefix |
+|---|---|---|---|---|---|
+| `status` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | structured `next` | N/A: command displays no shortened ID |
+| `checklist` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage errors covered; no runtime recovery claim | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `actions` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `stop` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | launch `next` when the adapter has one unambiguous launch | N/A: command displays no shortened ID |
+| `call` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `flows` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage errors covered; no runtime recovery claim | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `run` | covered: `CLI_UNKNOWN_OPTION` | TTY intent before slow work; machine output clean | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `last` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `doctor` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `check` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `recipe-quality` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `provision` | covered: `CLI_UNKNOWN_OPTION` | TTY intent before slow work; machine output clean | usage + runtime `error.code/message/userAction` | launch `next` after install | N/A: command displays no shortened ID |
+| `install` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | verify `next` | N/A: command displays no shortened ID |
+| `verify` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | status `next` | N/A: command displays no shortened ID |
+| `cleanup` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | install `next` | N/A: command displays no shortened ID |
+| `launch` | covered: `CLI_UNKNOWN_OPTION` | TTY intent before slow work; machine output clean | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `logs` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `debug` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage errors covered; no runtime recovery claim | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `update` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |
+| `fixtures` | covered: `CLI_UNKNOWN_OPTION` | N/A: no newly introduced slow path | usage + runtime `error.code/message/userAction` | N/A: discovery, read-only, or terminal result | N/A: command displays no shortened ID |

package/docs/CLI-ERGONOMICS-HUMAN-QA.md

@@ -0,0 +1,48 @@
+# Human QA
+
+Run this from each product checkout before a release. Verify the visible outcome,
+not only the exit code.
+
+## Common
+
+- [ ] `mm-harness --version` prints the candidate version.
+- [ ] `mm-harness doctor` detects the correct product and reports only current
+      configuration.
+- [ ] A misspelled flag explains the error and gives a runnable next command.
+- [ ] `mm-harness actions` and `mm-harness flows` return useful, bounded discovery.
+- [ ] `mm-harness fixtures set` either applies the fixture or names the missing
+      file and exact recovery action.
+- [ ] `mm-harness run <safe-recipe> --artifacts-dir temp/qa-proof` prints findings,
+      diagnostics, and absolute evidence paths.
+- [ ] `mm-harness last --json` identifies that run without rerunning it.
+- [ ] `mm-harness doctor --json` is one parseable document with no human decoration.
+
+## Extension
+
+- [ ] `mm-harness launch` opens/reuses the checkout's named Chrome profile.
+- [ ] `mm-harness launch --sidepanel` opens the MetaMask sidepanel without extra
+      Extension tabs.
+- [ ] `mm-harness debug` opens connected DevTools for the active MetaMask target.
+- [ ] `mm-harness logs --source extension` shows Extension console events.
+- [ ] `mm-harness logs --source dapp` shows dapp console events separately.
+- [ ] Edit a visible source string twice, waiting for successful incremental
+      compilation after each edit; refresh the browser and confirm both changes.
+- [ ] Revert the edit, confirm a third incremental compilation, and verify the
+      same watcher and Chrome process were reused.
+
+## Mobile
+
+- [ ] `mm-harness launch ios` boots/reuses the intended simulator and opens the app.
+- [ ] `mm-harness launch android` targets the intended emulator/device.
+- [ ] `mm-harness logs --source metro` and `--source app` show distinct streams.
+- [ ] `mm-harness debug` opens the usable React Native developer surface.
+- [ ] Change a visible JS string, confirm Metro rebuilds, reload the app, and see
+      the change without a native rebuild.
+
+## Core
+
+- [ ] `mm-harness status`, `doctor`, `actions`, `flows`, and a safe recipe run work
+      without browser/device assumptions.
+
+Record the command, version, checkout SHA, visible mismatch, exit code, and JSON
+error envelope for any failure.

package/docs/CODE-MAP.md

@@ -11,7 +11,7 @@ bin/mm-harness                 bash front door: MM_HARNESS_BIN dev/prod switch,
   │                            stale-dist warning), deps ensure
   ▼
 src/mm-harness-cli.ts          commander surface: grouped colored help, per-command
-  │                            --help, retired-name teaching; delegates in-process
+  │                            --help and usage errors; delegates in-process
   ▼
 src/cli.ts                     parse + dispatch ONLY — no verb logic lives here
   │

package/docs/UX-PRINCIPLES.md

@@ -27,6 +27,8 @@ The CLI answers relative to the checkout it is standing in.
 Long operations show intent immediately and progress continuously.
 - First line within milliseconds: what is being done, where (device/port), and
   where the full log lives.
+- Add an explicit first line only when work can block before existing output. Fast
+  commands use their result as acknowledgement; they do not print a redundant banner.
 - Leaf output streams live to stderr — `--json` reserves stdout for the envelope,
   it never buys silence. Quiet stretches get heartbeats with elapsed time.
 - Each dev server a command starts gets its tmux log-tail window at launch time

package/docs/VIDEO-DEMO-VALIDATION.md

@@ -0,0 +1,62 @@
+# Video demo validation
+
+Candidate: local packed `@deeeed/metamask-harness` 0.17.1 installed globally.
+Run commands from the named checkout; product/ports are auto-detected.
+
+## Common
+
+- [x] `mm-harness --version` prints `0.17.1` from the global npm install.
+- [x] `yarn check` passes.
+- [x] No `package-lock.json`; Yarn state is valid.
+- [x] Current source/docs contain no compatibility or removed-command paths.
+- [x] `doctor` reports current runtime fields only.
+- [x] Recipe results print diagnostics and absolute artifact paths inline.
+
+## Extension (`mme-2`)
+
+- [x] `mm-harness doctor` reports healthy CDP and active webpack watcher.
+- [x] `mm-harness run runner.smoke --artifacts-dir temp/final-demo-smoke` passes.
+- [x] Smoke prints six absolute evidence paths and `diagnostics: CLEAN`.
+- [x] `mm-harness debug` connects native DevTools to the active slot target.
+- [x] Fullscreen and sidepanel targets are selectable.
+- [x] Two source edits plus revert compiled incrementally with the same watcher;
+      browser refresh showed each change without relaunch.
+
+## Mobile (`mm-1`, iOS)
+
+- [x] `mm-harness install` writes metadata only; product checkout remains clean.
+- [x] `mm-harness fixtures set` reads the canonical fixture and unlocks `dev1`.
+- [x] `mm-harness call metamask.wallet.ensure_unlocked` passes from the global package.
+- [x] `mm-harness verify` passes after fixture setup.
+- [x] `mm-harness status` reports `WalletView`, unlocked wallet, selected account,
+      and fixture `READY`.
+- [ ] During the recording, visually confirm the expected simulator is foregrounded.
+
+## Core (`core-1`)
+
+- [x] `mm-harness doctor` reports the headless controller ready.
+- [x] Canonical wallet fixture is present.
+- [x] `mm-harness run perps.smoke --artifacts-dir temp/final-demo-smoke` passes.
+- [x] Positions, orders, and account state are read through the controller.
+- [x] Evidence prints absolute paths; diagnostics correctly reports `N/A` for headless Core.
+
+## Recording sequence
+
+```bash
+# Extension
+cd /Users/deeeed/farmslot/repos/mme-2
+mm-harness doctor
+mm-harness actions positions
+mm-harness flows
+mm-harness run runner.smoke --artifacts-dir temp/demo
+
+# Mobile
+cd /Users/deeeed/farmslot/repos/mm-1
+mm-harness launch ios
+mm-harness fixtures set
+mm-harness call metamask.wallet.ensure_unlocked
+
+# Core
+cd /Users/deeeed/farmslot/repos/core-1
+mm-harness run perps.smoke --artifacts-dir temp/demo
+```