@deeeed/metamask-harness 0.70.1 → 0.72.0

package/dist/run-diagnostics.js

@@ -3,8 +3,27 @@ import path from "node:path";
 import { createHash } from "node:crypto";
 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";
+import { recipeRuntimePath, runnerDir } from "./paths.js";
+import { ensureExtensionConsoleCapture, extensionCaptureFiles, extensionCdpPort } from "./adapters/extension/console-capture.js";
+import {
+  ensureTerminalConsoleCapture,
+  terminalCaptureFiles,
+  terminalCdpPort,
+  terminalRuntimeFile
+} from "./adapters/terminal/console-capture.js";
+import {
+  collectorOwnerMarker,
+  collectorStatus,
+  verifyCapture
+} from "../library/actions/shared/console-collector.mjs";
+import {
+  allowlistMatch,
+  classifyConsoleRecord,
+  consoleRecords,
+  libraryRootsFromEnv,
+  loadConsoleAllowlist,
+  messageSignature
+} from "../library/actions/shared/console-findings.mjs";
 const MAX_CAPTURE_BYTES = 512 * 1024;
 const MAX_FINDINGS = 20;
 const MAX_PREVIEW_CHARS = 320;
@@ -26,7 +45,9 @@ function formatRunDiagnosticsForHuman(diagnostics, adapter) {
   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}`);
+    const source = finding.source ? ` [${finding.source}]` : "";
+    const allowed = finding.allowlisted ? ` (allowlisted: ${finding.allowlisted.reason})` : "";
+    lines.push(`${finding.level.toUpperCase()}${count}${source} \u2014 ${finding.preview}${allowed}`);
   }
   return lines;
 }
@@ -34,27 +55,64 @@ async function beginRunDiagnostics(adapter, projectRoot) {
   const source = getAdapterSurface(adapter).appLogSource(projectRoot);
   if (!source) return null;
   const mobileIssueBuffer = adapter === "mobile" && process.env.METAMASK_RECIPE_MOBILE_OPAQUE_RUNTIME !== "1" && armMobileIssueBuffer(projectRoot) ? { projectRoot } : void 0;
-  if (adapter === "extension") {
-    await ensureExtensionConsoleCapture(projectRoot).catch(() => void 0);
+  let capture;
+  if (adapter === "extension" || adapter === "terminal") {
+    const start = adapter === "extension" ? ensureExtensionConsoleCapture : ensureTerminalConsoleCapture;
+    const startError = await start(projectRoot).then(() => void 0, (error) => error instanceof Error ? error.message : String(error));
+    const { extensionLog, pageLog, pidFile } = adapter === "extension" ? extensionCaptureFiles(projectRoot) : terminalCaptureFiles(projectRoot);
+    const cdpPort = adapter === "extension" ? extensionCdpPort() : terminalCdpPort();
+    capture = { adapter, projectRoot, extensionLog, pageLog, pidFile, ...cdpPort ? { cdpPort } : {}, ...startError ? { startError } : {} };
   }
+  const walletLogPath = adapter === "terminal" ? terminalRuntimeFile(projectRoot, "wallet-requests.jsonl") : null;
+  const walletStat = walletLogPath ? safeStat(walletLogPath) : null;
   const stat = safeStat(source.path);
   return {
     source,
     offset: stat?.size ?? 0,
     ...stat ? { inode: stat.ino } : {},
-    ...mobileIssueBuffer ? { mobileIssueBuffer } : {}
+    ...mobileIssueBuffer ? { mobileIssueBuffer } : {},
+    ...capture ? { capture } : {},
+    ...walletLogPath ? { walletLog: { path: walletLogPath, offset: walletStat?.size ?? 0, ...walletStat ? { inode: walletStat.ino } : {} } } : {}
   };
 }
+async function verifyConsoleCapture(capture) {
+  if (capture.startError) return { verified: false, detail: `the console collector did not start: ${capture.startError}` };
+  if (!capture.cdpPort) return { verified: false, detail: "no CDP port for the console collector" };
+  const status = collectorStatus({
+    pidFile: capture.pidFile,
+    extensionLog: capture.extensionLog,
+    marker: collectorOwnerMarker(path.dirname(capture.pidFile)),
+    cdpPort: capture.cdpPort
+  });
+  if (!status.ok) return { verified: false, detail: status.detail };
+  let control;
+  if (capture.adapter === "extension") {
+    let extensionId = null;
+    try {
+      extensionId = fs.readFileSync(recipeRuntimePath(capture.projectRoot, "extension.id"), "utf8").trim();
+    } catch {
+      extensionId = null;
+    }
+    control = await verifyCapture({ cdpPort: capture.cdpPort, log: capture.extensionLog, target: "extension", extensionId });
+  } else {
+    const browser = readJsonRecord(terminalRuntimeFile(capture.projectRoot, "browser.json"));
+    if (typeof browser?.appOrigin !== "string") return { verified: false, detail: "no slot browser state (browser.json) to verify the page console capture against" };
+    control = await verifyCapture({ cdpPort: capture.cdpPort, log: capture.pageLog, target: "page", appOrigin: browser.appOrigin });
+  }
+  return { verified: control.ok, detail: control.ok ? `${status.detail}; ${control.detail}` : control.detail };
+}
 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) {
+async function finishRunDiagnostics(baseline, result) {
   if (!baseline) return result;
   try {
     const bufferedIssues = baseline.mobileIssueBuffer ? collectMobileIssueBuffer(baseline.mobileIssueBuffer.projectRoot) : void 0;
-    const { diagnostics, rawAppLog } = collectRunDiagnosticsCapture(baseline, bufferedIssues);
+    const allowlist = loadConsoleAllowlist(recipeLibraryRoots(result.summaryPath));
+    const capture = baseline.capture ? await verifyConsoleCapture(baseline.capture) : void 0;
+    const { diagnostics, rawAppLog } = collectRunDiagnosticsCapture(baseline, bufferedIssues, allowlist, capture);
     const artifactsDir = path.dirname(result.summaryPath);
     const diagnosticsPath = path.join(artifactsDir, "diagnostics.json");
     fs.writeFileSync(diagnosticsPath, `${JSON.stringify(diagnostics, null, 2)}
@@ -87,16 +145,17 @@ function finishRunDiagnostics(baseline, result) {
     };
   }
 }
-function collectRunDiagnostics(baseline, bufferedIssues) {
-  return collectRunDiagnosticsCapture(baseline, bufferedIssues).diagnostics;
+function collectRunDiagnostics(baseline, bufferedIssues, allowlist = null, capture) {
+  return collectRunDiagnosticsCapture(baseline, bufferedIssues, allowlist, capture).diagnostics;
 }
-function collectRunDiagnosticsCapture(baseline, bufferedIssues) {
+function collectRunDiagnosticsCapture(baseline, bufferedIssues, allowlist = null, capture) {
   const stat = safeStat(baseline.source.path);
   const source = {
     label: baseline.source.label,
     path: baseline.source.path,
     startOffset: baseline.offset,
     endOffset: stat?.size ?? baseline.offset,
+    inode: void 0,
     bytesRead: 0,
     truncated: false,
     inAppBuffer: bufferedIssues === void 0 ? "n/a" : bufferedIssues === null ? "unavailable" : "collected",
@@ -111,22 +170,31 @@ function collectRunDiagnosticsCapture(baseline, bufferedIssues) {
     const bytesToRead = Math.min(available, MAX_CAPTURE_BYTES);
     source.startOffset = startOffset;
     source.endOffset = stat.size;
+    source.inode = stat.ino;
     source.bytesRead = bytesToRead;
     source.truncated = available > MAX_CAPTURE_BYTES;
     if (bytesToRead > 0) rawAppLog = readSlice(baseline.source.path, startOffset, bytesToRead);
+    if (source.truncated) rawAppLog = rawAppLog.subarray(0, rawAppLog.lastIndexOf(10) + 1);
   }
   const text = rawAppLog.toString("utf8");
+  const lineFindings = consoleRecords(text).map(classifyRecord).filter((finding) => finding !== null);
+  applyConsoleAllowlist(lineFindings, allowlist);
   const allFindings = dedupeFindings(
     [
-      ...text.split(/\r?\n/u).map(classifyLine).filter((finding) => finding !== null),
-      ...(bufferedIssues ?? []).map(classifyBufferedIssue).filter((finding) => finding !== null)
+      ...lineFindings,
+      ...(bufferedIssues ?? []).map(classifyBufferedIssue).filter((finding) => finding !== null),
+      ...baseline.walletLog ? walletLogFindings(baseline.walletLog) : []
     ]
   );
-  const findings = allFindings.slice(0, MAX_FINDINGS);
+  const applied = allFindings.filter((finding) => finding.level === "info").length;
+  allFindings.sort((a, b) => Number(a.level === "info") - Number(b.level === "info"));
+  const findings = allFindings.slice(0, MAX_FINDINGS).map(stripInternal);
   const counts = countFindings(allFindings);
   const omittedFindingCount = Math.max(0, allFindings.length - findings.length);
-  const status = counts.total > 0 ? "review" : stat || bufferedIssues !== void 0 && bufferedIssues !== null ? "clean" : "unavailable";
-  const note = counts.total > 0 ? `Observed ${counts.total} distinct application warning/error event(s) during the recipe run; showing ${findings.length} preview(s) and omitting ${omittedFindingCount}. Relation to the task is not determined.` : status === "clean" ? "No application warnings or errors were emitted during the recipe run." : "Application diagnostics were unavailable for this run.";
+  const captureFailed = capture !== void 0 && !capture.verified;
+  const status = counts.total > 0 ? "review" : !captureFailed && !source.truncated && (stat || bufferedIssues !== void 0 && bufferedIssues !== null) ? "clean" : "unavailable";
+  const captureNote = (captureFailed ? ` Console capture was not verified: ${capture.detail}.` : "") + (source.truncated ? ` The run's log exceeded ${MAX_CAPTURE_BYTES} bytes; only its start was checked.` : "");
+  const note = (counts.total > 0 ? `Observed ${counts.total} distinct application warning/error event(s) during the recipe run; showing ${findings.length} preview(s) and omitting ${omittedFindingCount}. Relation to the task is not determined.` : status === "clean" ? "No application warnings or errors were emitted during the recipe run." : "Application diagnostics were unavailable for this run.") + captureNote;
   return { diagnostics: {
     schemaVersion: 1,
     scope: "recipe-run-application",
@@ -135,24 +203,47 @@ function collectRunDiagnosticsCapture(baseline, bufferedIssues) {
     note,
     source,
     counts,
+    ...allowlist ? { allowlist: { entries: allowlist.entries.length, applied, problems: allowlist.problems } } : {},
+    ...capture ? { capture } : {},
     displayedFindingCount: findings.length,
     omittedFindingCount,
     findings
   }, rawAppLog };
 }
-function classifyLine(line) {
-  const trimmed = line.trim();
-  if (!trimmed) return null;
-  let level = null;
-  if (/\bEXCEPTION\s{2,}|\b(?:Uncaught|UnhandledPromiseRejection|FATAL EXCEPTION)\b/iu.test(trimmed)) {
-    level = "exception";
-  } else if (/^(?:ERROR\s{2,}|\[error\]\s*)/iu.test(trimmed) || /\]\s+ERROR\s{2,}/u.test(trimmed)) {
-    level = "error";
-  } else if (/^(?:WARN(?:ING)?\s{2,}|\[warn(?:ing)?\]\s*)/iu.test(trimmed) || /\]\s+WARN(?:ING)?\s{2,}/u.test(trimmed)) {
-    level = "warning";
+function classifyRecord(record) {
+  const classified = classifyConsoleRecord(record);
+  if (!classified) return null;
+  const line = record.line;
+  const signature = messageSignature(redactDiagnosticText(classified.message));
+  return {
+    ...makeFinding(classified.level, line.trim(), `${classified.source}|${signature}`),
+    source: classified.source,
+    signature: redactPreview(signature),
+    firstFrame: classified.firstFrame ? redactPreview(classified.firstFrame) : null,
+    event: classified.key
+  };
+}
+function walletLogFindings(walletLog) {
+  const stat = safeStat(walletLog.path);
+  if (!stat) return [];
+  const sameFile = walletLog.inode === void 0 || walletLog.inode === stat.ino;
+  const start = sameFile && stat.size >= walletLog.offset ? walletLog.offset : 0;
+  const findings = [];
+  for (const line of readSlice(walletLog.path, start, stat.size - start).toString("utf8").split("\n")) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!isRecord(entry)) continue;
+    let text = null;
+    if (entry.kind === "blocked-mainnet" && entry.probe !== true) text = `blocked-mainnet: ${String(entry.transport ?? "request")} to ${String(entry.url ?? "?")}`;
+    else if (entry.kind === "refused-mainnet") text = `refused-mainnet: ${String(entry.method ?? "?")} (${String(entry.reason ?? "?")})`;
+    else if (entry.kind === "unattributed") text = `unattributed wallet ${entry.binding === "request" ? "request" : "log entry"}${typeof entry.method === "string" ? ` (${entry.method})` : ""}`;
+    if (text) findings.push({ ...makeFinding("error", text, `wallet|${text}`), source: "wallet", signature: text, firstFrame: null });
   }
-  if (!level) return null;
-  return makeFinding(level, trimmed);
+  return findings;
 }
 function classifyBufferedIssue(value) {
   if (!isRecord(value) || typeof value.text !== "string") return null;
@@ -160,15 +251,26 @@ function classifyBufferedIssue(value) {
   const level = rawLevel === "warn" || rawLevel === "warning" ? "warning" : rawLevel === "error" ? "error" : rawLevel === "exception" ? "exception" : null;
   return level ? makeFinding(level, value.text) : null;
 }
-function makeFinding(level, text) {
+function makeFinding(level, text, groupKey) {
   const preview = redactPreview(text.trim());
-  const identity = preview.replace(/\b\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?\b/gu, "[TIME]").replace(/\[(?:sw|page:[^\]]+|console:[^\]]+)\]/gu, "[APP]").replace(/^(?:(?:WARN(?:ING)?|ERROR|EXCEPTION|\[TIME\]|\[APP\])\s*)+/u, "");
+  const identity = groupKey ?? preview.replace(/\b\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?\b/gu, "[TIME]").replace(/\[(?:sw|page:[^\]]+|console:[^\]]+)\]/gu, "[APP]").replace(/^(?:(?:WARN(?:ING)?|ERROR|EXCEPTION|\[TIME\]|\[APP\])\s*)+/u, "");
   return {
     level,
     fingerprint: createHash("sha256").update(`${level}|${identity}`).digest("hex").slice(0, 12),
     preview
   };
 }
+function applyConsoleAllowlist(findings, allowlist) {
+  if (!allowlist) return;
+  for (const finding of findings) {
+    if (!finding.event) continue;
+    const match = allowlistMatch({ source: finding.source, key: finding.event }, allowlist);
+    if (!match) continue;
+    finding.allowlisted = { reason: match.reason, entry: match.index, file: match.file, ...match.temporary ? { temporary: true } : {} };
+    finding.level = "info";
+    finding.fingerprint = createHash("sha256").update(`${finding.fingerprint}|info|${match.file}#${match.index}`).digest("hex").slice(0, 12);
+  }
+}
 function armMobileIssueBuffer(projectRoot) {
   const armed = runMobileIssueCommand(projectRoot, "issues-arm");
   if (!armed) return false;
@@ -209,10 +311,17 @@ function dedupeFindings(findings) {
   return [...byFingerprint.values()];
 }
 function countFindings(findings) {
-  const counts = { total: findings.length, warning: 0, error: 0, exception: 0 };
-  for (const finding of findings) counts[finding.level] += 1;
+  const counts = { total: 0, warning: 0, error: 0, exception: 0, info: 0 };
+  for (const finding of findings) {
+    counts[finding.level] += 1;
+    if (finding.level !== "info") counts.total += 1;
+  }
   return counts;
 }
+function stripInternal(finding) {
+  const { event: _event, ...rest } = finding;
+  return rest;
+}
 function readSlice(filePath, offset, length) {
   const fd = fs.openSync(filePath, "r");
   try {
@@ -266,6 +375,13 @@ function indexDiagnosticSummary(summaryPath, diagnostics) {
   fs.writeFileSync(summaryPath, `${JSON.stringify(summary, null, 2)}
 `);
 }
+function recipeLibraryRoots(summaryPath) {
+  const summary = readJsonRecord(summaryPath);
+  const libraries = isRecord(summary?.recipeLibraries) ? summary.recipeLibraries : null;
+  const sources = Array.isArray(libraries?.sources) ? libraries.sources : [];
+  const roots = sources.map((source) => isRecord(source) && typeof source.root === "string" ? source.root : null).filter((root) => Boolean(root));
+  return roots.length ? roots : libraryRootsFromEnv();
+}
 function readJsonRecord(filePath) {
   try {
     const value = JSON.parse(fs.readFileSync(filePath, "utf8"));
@@ -282,5 +398,6 @@ export {
   collectRunDiagnostics,
   finishRunDiagnostics,
   formatRunDiagnosticsForHuman,
-  readRunDiagnosticsDocument
+  readRunDiagnosticsDocument,
+  verifyConsoleCapture
 };

package/dist/runner.js

@@ -89,7 +89,7 @@ async function createMetaMaskRunner(adapter, actionManifest, options = {}) {
         const { createAgentDeviceUiTransport } = await importMetaMaskNativeUiProvider();
         return createAgentDeviceUiTransport(options2);
       }
-    }, preparedLiveAdapters)
+    }, preparedLiveAdapters, { hudPolicy: options.autoHud === true ? "show" : "auto" })
   });
   const existing = new Set([...core, ...ui].map((entry) => entry.action));
   const lifecycle = mobileSourceAwareLifecycleAdapters(

package/dist/runtime-context.js

@@ -91,7 +91,7 @@ function validExistingContext(context, repoRoot, runtimeDir, adapter) {
       if (runtimeStart[field] !== void 0 && (typeof runtimeStart[field] !== "string" || runtimeStart[field].length === 0)) return false;
     }
   }
-  const forbiddenResources = adapter === "core" ? ["cdpPort", "watcherPort", "metroPort", "devServerPort", "simulator", "simulatorUdid", "adbSerial", "extensionId"] : adapter === "extension" ? ["metroPort", "simulator", "simulatorUdid", "adbSerial"] : ["cdpPort", "extensionId"];
+  const forbiddenResources = adapter === "core" ? ["cdpPort", "watcherPort", "metroPort", "devServerPort", "simulator", "simulatorUdid", "adbSerial", "extensionId"] : adapter === "extension" ? ["metroPort", "simulator", "simulatorUdid", "adbSerial"] : adapter === "terminal" ? ["metroPort", "simulator", "simulatorUdid", "adbSerial", "extensionId"] : ["cdpPort", "extensionId"];
   if (forbiddenResources.some((field) => context[field] !== void 0)) return false;
   return true;
 }
@@ -107,7 +107,7 @@ function localDefaults(repoRoot, adapter, existing) {
   if (adapter === "extension" && !numericEnv("RECIPE_CDP_PORT", "CDP_PORT") && !existing.cdpPort) {
     defaults.cdpPort = claimLocalPort(repoRoot, "cdp", 2e4 + offset);
   }
-  if (adapter !== "core" && !numericEnv("WATCHER_PORT", "METRO_PORT", "RECIPE_WATCHER_PORT") && !existing.watcherPort && !existing.metroPort && !existing.devServerPort) {
+  if (adapter !== "core" && adapter !== "terminal" && !numericEnv("WATCHER_PORT", "METRO_PORT", "RECIPE_WATCHER_PORT") && !existing.watcherPort && !existing.metroPort && !existing.devServerPort) {
     defaults.watcherPort = claimLocalPort(repoRoot, "watcher", (adapter === "extension" ? 3e4 : 4e4) + offset);
   }
   return defaults;
@@ -164,7 +164,7 @@ function runtimeResources(adapter, existing, defaults) {
     watcherPort,
     devServerPort: watcherPort
   };
-  if (adapter === "extension") {
+  if (adapter === "extension" || adapter === "terminal") {
     shared.cdpPort = numericEnv("RECIPE_CDP_PORT", "CDP_PORT") ?? existing.cdpPort ?? defaults.cdpPort;
   } else {
     shared.metroPort = watcherPort;

package/docs/CONTRIBUTING.md

@@ -93,7 +93,7 @@ The input path is argv 1 and `METAMASK_RECIPE_ADAPTER_INPUT`. Its document is:
 ```json
 {
   "schemaVersion": 1,
-  "platform": "mobile|extension|core",
+  "platform": "mobile|extension|core|terminal",
   "action": "metamask.example.action",
   "node": {},
   "context": {

package/docs/cli-contract.md

@@ -0,0 +1,163 @@
+# mm-harness CLI contract
+
+This page lists every `mm-harness` invocation that something outside this repo depends on, and what that caller reads back. The golden tests in `tests/contract/goldens-*.test.sh` freeze this surface. A refactor that changes any of it fails CI until someone accepts the change with `yarn test:goldens --update` and updates the callers in the same release.
+
+Callers scanned (2026-10-02):
+- Farmslot projects `metamask-{extension,mobile,core}-farm` and `va-mmcx-terminal-farm`: `project.json` hooks, `setup/*.sh`, `scripts/*.sh`, worker templates.
+- Farmslot gateway: `services/gateway/src/methods/recipe.ts` and the modules it calls.
+- Recipe libraries: `experimental-metamask-recipe-perps` and `experimental-metamask-recipe-terminal` (`checks/*.mjs`).
+- This repo's README and `docs/`.
+
+## Resolution and environment
+
+- Farms resolve the binary with `HARNESS_BIN="${METAMASK_HARNESS_BIN:-${MM_HARNESS_BIN:-mm-harness}}"; command -v "$HARNESS_BIN"`. `MM_HARNESS_BIN` hands the whole invocation to another checkout's `bin/mm-harness`.
+- Static review runs `{{support}}/bin/mm-harness` with entry `dist/mm-harness-cli.js`, so the package layout (`bin/`, `dist/`) is part of the contract.
+- Hook environment: `RECIPE_SLOT_ID`, `RECIPE_RUNTIME_DIR` (default `temp/recipe/runtime`), `RECIPE_WALLET_FIXTURE`, `RECIPE_LIBRARY_PATH`, `MM_HARNESS_DOMAIN`, `IOS_SIMULATOR`/`ADB_SERIAL` (mobile slots), `RECIPE_HARNESS_ROOT=temp/recipe/harness` (Extension).
+
+## Commands, callers, and what they consume
+
+`G:` names the golden that freezes the row (`tests/contract/goldens/<family>/<case>.json`).
+
+### Recipe execution (gateway `recipe.ts`, worker templates, library checks)
+
+| Command | Caller | Consumes | G: |
+|---|---|---|---|
+| `run <recipe> --adapter <a> --artifacts-dir <d> --target <repo> [--slot <s>] --json [--cdp-port <p>] [--watcher-port <p>] [--launch-existing-dist] [--record-video=full-run]` | `recipe_run` hook, all four packs | exit code, then the artifact package (below) | `core/run-hook`, `extension/run-hook`, `extension/run-hook-plan` (all flags incl. `--record-video=full-run`), `mobile/run-hook`, `mobile/run-hook-plan`, `core/run-invalid`, `*/run-unknown-flag` |
+| `run <recipe> --artifacts-dir <d> --json` from the checkout | Core templates | exit code; `trace.json` on failure | `core/run-autodetect` |
+| `run <recipe> [k=v…] --plan [--adapter <a>] [--library ns=dir] [--json]`, with `RECIPE_LIBRARY_PATH=ns=dir` or cleared | templates; perps `checks/*.mjs` | exit code; `JSON.parse(stdout).status === 'pass'`; on rejection stdout+stderr matching `RECIPE_PARAMS_INVALID\|parameter\|required\|enum`. No harness code emits `RECIPE_PARAMS_INVALID`: plan rejections exit 5 with findings `recipe.missing_param` / `recipe.invalid_param_value_enum` / unknown-param, and a real run exits 5 with `RECIPE_VALIDATION_FAILED`. The check passes on the `parameter\|required\|enum` alternatives | `core/run-plan`, `mobile/run-plan`, `library/*` |
+| `run --list [--adapter <a>] [--json]`, `run <r> --describe --json` | templates, docs | prose | `discovery/run-list-*`, `discovery/run-describe` |
+| `call <action> [k=v…] --adapter <a> [--target] [--watcher-port] [--json]` | mobile `unlock` hook, templates | exit code (unlock output is ignored) | `core/call-command`, `mobile/call-unlock` |
+| `actions --raw --adapter <a> --json` | `recipe_action_manifest` hook, all packs | stdout is a Recipe v1 action manifest (`validateRecipeActionManifestDocument`) | `discovery/actions-raw-*` |
+| `actions --adapter <a> --json` | templates (Core runs `jq -r '.actions[].name'`) | `.actions[].name` | `discovery/actions-*` |
+| `actions --action <name> --json`, `actions <term> --json` | templates, docs | prose | `discovery/actions-action`, `discovery/actions-search` |
+
+### Readiness (preflight, health_check, recipe_doctor)
+
+| Command | Caller | Consumes | G: |
+|---|---|---|---|
+| `doctor --adapter <a> --target <repo> [--cdp-port\|--watcher-port <p>] --json` | `recipe_doctor` hook | `runner_protocol_version === 1`, `status === 'pass'`, every `checks[].status === 'pass'` | `*/doctor-json` |
+| `doctor --adapter <a> --target <repo> [--cdp-port\|--watcher-port <p>] [--runtime-dir <rd>] [--device <d>] --print-ready` | `health_check` (gateway `slot/check.ts`, `2>/dev/null`) | exit 0 and trimmed stdout equal to `OK` (Extension, Mobile) or `ready` (Core) | `*/doctor-print-ready`, `mobile/doctor-print-ready-device` |
+| `doctor … --expect-live [--json]` | Extension `ensure-runtime-ready.sh`, `preflight.sh`; templates | exit code; JSON shown to the agent | `extension/doctor-expect-live-json`, `mobile/doctor-expect-live-json` |
+| `prepare --target <repo> --platform <extension\|mobile\|core> --artifacts-dir <repo>/<rd> --json` | preflight (all packs, stdout to `/dev/null`) | exit code; gateway reads `<rd>/sandbox.json`: `schemaVersion === 1`, `steps[]` (`id`, `status`, `reason`), `ready`, `harness.name`, `harness.version` | `*/prepare` |
+| `install --adapter <a> --target <repo>` | `recipe_harness_install`, Core preflight | exit code | `*/install` |
+| `verify --adapter <a> --target <repo> [--json]` | `recipe_harness_verify`, Core preflight | exit code (JSON not parsed) | `core/verify`, `mobile/verify` |
+| `cleanup --adapter <a> --target <repo>` | `recipe_harness_cleanup`, Extension recycle | exit code | `*/cleanup` |
+
+### Runtime lifecycle
+
+| Command | Caller | Consumes | G: |
+|---|---|---|---|
+| `launch --verify --adapter extension --target <repo> --watcher-port <p> --cdp-port <p> --surface <fullscreen\|sidepanel> [--build] [--url <u>]` | Extension `preflight.sh` | exit code | `extension/launch-verify` |
+| `launch --adapter extension --target --cdp-port (--fullscreen \| --sidepanel --url <u>) [--verify] [--build] [--remote-flag K=V] [--json]` | Extension browser resource boot hook and slot actions | exit code | `extension/launch-boot-fullscreen`, `extension/launch-sidepanel-url`, `extension/launch-verify-remote-flag`, `extension/launch-build-verify` (cold, through the stubbed browser/build leaf; `live-calls.log` frozen) |
+| `launch <ios\|android> --adapter mobile --target <repo> --verify --json --watcher-port <p> [--build] [--device <d>]` | Mobile `preflight.sh` | exit code; stdout saved to `<rd>/mobile-launch/summary.json` (not parsed) | `mobile-launch/launch-ios-verify`, `mobile-launch/launch-ios-device-verify`, `mobile-launch/launch-android-device-verify` (`leaf-calls.log` frozen) |
+| `stop --adapter <extension\|mobile> --port <p> --target <repo>` | teardown, recycle, shutdown hooks | exit code | `extension/stop`, `mobile/stop` |
+| `fixtures set --adapter extension --target <repo> --fixture <rd>/wallet-fixture.json` | Extension preflight | exit code | `extension/fixtures-set-no-browser` |
+| `fixtures set --adapter mobile --target <repo> --json` | Mobile preflight | exit code; stdout saved to `<rd>/mobile-launch/wallet-setup.json` | `mobile/fixtures-set` |
+| `fixtures generate --target <repo> --fixture <rd>/wallet-fixture.json --out <rd>/fixture-state.json` | Extension `launch-browser.sh` | reads `fixture-state.json` | `extension/fixtures-generate` |
+| `<repo>/temp/recipe/harness/extension/runner/bin/mm-harness resolve-extension --adapter extension --target <repo>` (overlay path, not the public bin) | Extension `setup/launch-browser.sh:53,449` | stdout must match `/^[a-p]{32}$/`; failure falls back to scanning | `extension/resolve-extension-overlay` |
+| `provision runway <ios\|android> --adapter mobile --target --slot --watcher-port --runtime-dir --run <id> [--device] [--force]` | Mobile `runway-preflight.sh` | exit code (non-zero falls back) | `mobile/provision-runway-android` (ios needs `gh` + network: not covered) |
+
+### Task tooling (gateway and worker templates)
+
+| Command | Caller | Consumes | G: |
+|---|---|---|---|
+| `checklist mark <taskDir> {start\|<n>\|complete [--mark-last]\|blocked --reason <s>\|no-change --reason <s>\|--help}` | `{{TASK_DIR}}/mark` shim (`mark_cmd`) | exit code; `SIGNAL.json`, `CHECKLIST.md` | `task/mark-*` |
+| `pr-body render <taskDir> --json` (cwd = task dir) | gateway `pr-body-render.ts` (`pr_body_cmd`) | on failure `JSON.parse(stdout).error`, else stderr; then `artifacts/pr-body.md` | `task/pr-body-render-*` |
+| `review checklist --out <file> [--domain <d>] [--since <sha>]` | domain fixtures, review templates | the written file | `task/review-checklist` |
+| `check diff …`, `recipe-quality build …` | templates | exit code | not covered: run repo lint/test tooling |
+
+### Discovery (moves to Farmslot in phase 2a)
+
+`--help`, `--version`, `help [review] --json`, `actions` (above), `run --list`, `call --list`, `completion-candidates actions`, `execution-template {new,list,materialize} --json`, `completions {zsh,bash}`, and the unknown-command error. G: `discovery/*`.
+
+## Files callers read
+
+- **Recipe artifacts dir** (`--artifacts-dir`): `summary.json` (`.status`), `trace.json`, `artifact-manifest.json` (`.runStatus` equals `summary.status`; Recipe v1), optional `recipe.json`, `recipe-resolution.json` with `resolved-recipes/<sha256>.recipe.json`, and videos when `--record-video=full-run`. Frozen with full normalised values (`valueTrees`) for passing runs in `core/run-hook`, `core/run-autodetect`, `core/call-command` and `library/run-library-recipe`. `extension/run-hook` and `mobile/run-hook` run cold with no runtime, so they freeze the failure envelope and exit code, and their artifact tree is `null` (nothing is written). A passing Extension or Mobile artifact package needs a live runtime and is not covered.
+- **`<rd>/sandbox.json`** from `prepare`: frozen in full by `*/prepare`.
+- **Pid files and logs** under `<rd>`: `browser.pid`, `recipe-harness-webpack.pid`, `recipe-harness-webpack.log` (Extension); `metro.log` (Mobile); the gateway kills `launcher.pid`, `browser.pid`, `chromium.pid`, `webpack.pid` and deletes `extension.id` and `preflight.pgid`. Live-runtime only, so not covered by the cold-path goldens.
+- **`<rd>/fixture-state.json`** from `fixtures generate`: `extension/fixtures-generate`.
+- **Task artifacts**: `SIGNAL.json`, `artifacts/pr-body.md`, review checklist file.
+
+## Callers that are out of contract today
+
+These are real farm bugs. The goldens freeze the current rejections, so fixing either side shows up as a reviewed golden change. The farm fixes go in a separate Farmslot PR.
+
+| Caller | Today | Correct call | G: |
+|---|---|---|---|
+| Mobile `scripts/cleanup-recipe-harness.sh:30` (`recipe_harness_cleanup`) | `cleanup … --allow-managed-changes` exits 2 (`CLI_UNKNOWN_OPTION`); its `No mobile harness backup found` fallback never matches, so the hook always fails | `cleanup --adapter mobile --target <repo>` | `mobile/cleanup-allow-managed-changes`, `mobile/cleanup` |
+| Mobile `project.json` `unlock` hook | `call app.unlock` exits 2 (unknown action); the gateway ignores the result, so unlock is a silent no-op | `call metamask.wallet.ensure_unlocked --adapter mobile --target <repo> --watcher-port <p>` | `mobile/call-unlock` |
+| Mobile `scripts/runway-preflight.sh:66` | `provision runway android` exits 2 (only `ios`), so the Android runway profile always falls back | add Android runway to the harness, or have the farm reject Android before calling | `mobile/provision-runway-android` |
+| Mobile templates `dev.md`, `dev-interactive.md`, `fix-bug.md`, `review-pr.md` | `mark complete --status blocked --outcome partial --reason …` exits 2 | `mark blocked --reason "<why>"` | `task/mark-invalid-status-outcome`, `task/mark-blocked` |
+| Docs | `launch --build-lavamoat` (only `runtime-launch` has it); `run --target <recipe-file>` | `runtime-launch --build-lavamoat`; `run <recipe-file> --target <repo>` | — |
+
+## Terminal adapter: TODO
+
+#298 merged the `terminal` adapter (`fd1c77e`). Discovery already reflects it (`discovery/actions-matrix`, the adapter hint in `help`). **Follow-up, not in this PR:** freeze its farm hooks once a stub browser replaces the LaunchServices launch of a visible Chrome for Testing (the goldens must never start a real browser). Add `tests/contract/goldens-terminal.test.sh` covering the `va-mmcx-terminal-farm` hooks:
+
+- [ ] `run <recipe> --adapter terminal --artifacts-dir <d> --target <repo> --slot <s> --cdp-port <p> --watcher-port <p> --json`
+- [ ] `actions --raw --adapter terminal --json`
+- [ ] `doctor --adapter terminal --target <repo> --cdp-port <p> --watcher-port <p> --json`
+- [ ] `install --adapter terminal --target <repo>`
+- [ ] `verify --adapter terminal --target <repo> -- --cdp-port <p> --watcher-port <p> --account <a>`
+- [ ] `cleanup --adapter terminal --target <repo> -- --cdp-port <p>`
+- [ ] `launch --adapter terminal --target <repo> --cdp-port <p> --watcher-port <p> --signer extension --account <a>` (use the stub browser from #298's `tests/fixtures/terminal-stub-browser.mjs`)
+- [ ] `stop --adapter terminal --target <repo>` with `RECIPE_CDP_PORT`
+- [ ] `run terminal.perps.<name> k=v… --adapter terminal --target <t> --cdp-port <p> --watcher-port <p> --plan` (recipe-terminal `checks/plan-recipes.mjs`)
+- [ ] runtime layout of `temp/recipe/runtime/terminal/` (`browser.pid` is watched by the farm)
+- [ ] discovery: add `terminal` to the per-adapter loop in `goldens-discovery.test.sh` (`actions --raw`, `actions`, `run --list`, `call --list`)
+- [ ] recipe-terminal `console-guard.mjs` imports the harness's `library/actions/shared/console-findings.mjs` and `tests/fixtures/console-allowlist-vectors.json`: freeze both paths and the exported surface
+
+## Running the goldens
+
+```bash
+yarn test:goldens               # compare all families in parallel (CI runs them in the contract shards)
+yarn test:goldens mobile        # families whose name contains "mobile"
+yarn test:goldens --update      # rewrite goldens, print a per-field diff summary, drop orphans
+```
+
+Every family checks its own golden directory: a golden no case writes fails the family, in CI too (`--update` deletes it). Every family also fails on a golden directory that has no `goldens-<dir>.test.sh`, so deleting a whole family script is caught. Families run in parallel locally and sequentially inside the contract CI shards.
+
+Each case runs under a safety cap, `GOLDENS_CASE_TIMEOUT` (default 600 s). A case that hits it reports `TIMEOUT <case>` and fails without being compared or written, so `--update` can never accept a truncated capture.
+
+Each family is a normal contract test (`tests/contract/goldens-<family>.test.sh`). `gd_init` (`tests/contract/goldens/lib.sh`) builds a sandbox on `ct_init`, and every case runs under `env -i`:
+- `gd_init` first unsets every inherited `MM_HARNESS_*`, `RECIPE_*`, `METAMASK_*` and `FARMSLOT_*` variable, plus device and port pins (`IOS_SIMULATOR`, `ADB_SERIAL`, `WATCHER_PORT`, `METRO_PORT`, `CDP_PORT`, `IDB_PATH`, `ANDROID_HOME`, …). A developer's `MM_HARNESS_BIN` or `MM_HARNESS_IDB_PATH` export therefore cannot redirect a case;
+- the environment is an allowlist: sandbox `HOME`, caches, config, `FARMSLOT_HOME`, `TZ=UTC`, no update probe, and only the variables the family sets itself;
+- every interpreter and tool the goldens launch is resolved to its real binary before `HOME` moves into the sandbox: `node` (`process.execPath`), `python3` (`sys.executable`, for the test shell's port holder only), `git` (`git --exec-path`), `bash` (`$BASH`) and `timeout`. A tool that resolves to a script, the shape of an asdf/mise/volta/pyenv shim, fails the family up front with a message naming it. Each is checked to run with a sandboxed `HOME`;
+- `PATH` is pinned to the case stubs, the sandbox stubs, those real binaries, and `/usr/bin:/bin:/usr/sbin:/sbin`. Host tools (`idb`, `capture-helper`, a developer's Chrome) cannot change a golden;
+- device-tool discovery is pinned: `MM_HARNESS_IDB_PATH` and `MM_HARNESS_ADB_PATH` point at sandbox stubs, which discovery checks before any absolute Homebrew or pipx path;
+- localhost probes cannot reach a real server. `gd_reserve_ports` holds ephemeral ports that are bound but never listened on (`127.0.0.1` and `::1`), so Metro `/status` and CDP probes cannot connect (on macOS they time out rather than being refused) and nothing real can take the port mid-run. Each family exports the farm's slot port variables (`RECIPE_CDP_PORT`, `WATCHER_PORT`, `METRO_PORT`) set to those ports, so commands without an explicit port use them too. Goldens show them as `<PORT:NAME>`, rewritten only in port positions (`*port` keys, `:<port>`, `port <n>`/`PORT=<n>`, or an argument that is exactly the port), so an unrelated equal number such as a 60000 ms timeout is never rewritten;
+- `tmux`, `xcrun` and `adb` are stubbed (`ct_init`, plus one booted simulator and one Android device for Mobile);
+- forbidden stubs record any call to `open`, `osascript`, `lsappinfo`, `screencapture`, `yarn`, `npx`, `npm`, `corepack`, `gh` and Chrome/Chromium, and the family fails if one is called. A browser stub answers only `--version`, and `npm` only `root -g` (install-source detection), with a sandbox path;
+- inert stubs on the case PATH only: `lsof`, `pgrep` and `pkill` find nothing, `ps` passes per-pid queries (`-p`, the CLI identifying its own processes) and lists an empty host for table listings, and `watchman` and `caffeinate` are no-ops. `stop` cannot see or signal a real process or touch a host daemon;
+- `RECIPE_HARNESS_BROWSER` points at the sandbox Chrome stub, so browser resolution never probe-launches Chrome for Testing or reads host Chrome policy;
+- `MM_HARNESS_MOBILE_VERIFY_PROBE_TIMEOUT_MS=2000` shortens Mobile verify's live-bridge wait (default 60 s), because no fixture provides a debug target.
+
+Mobile Metro, device, bridge and wallet leaves, the Extension build/browser leaf, and the fixture-state leaf are stubbed through `MM_HARNESS_SCRIPT_BIN_*`. `leaf-calls.log` and `live-calls.log` are frozen per launch case.
+
+A golden records:
+- `bin` (only when a case runs another executable) and argv;
+- the exit code;
+- stdout (parsed JSON, or lines), and stderr when the exit code is non-zero;
+- `--file`/`--log` files in full;
+- `--tree` runtime trees: relative paths plus each JSON file's key shape, where arrays record the union of every element;
+- `--value-tree` artifact packages: relative paths plus each JSON file's normalised values;
+- `--shallow-tree` for the internal overlay: paths two levels deep, no shapes.
+
+The goldens need the harness to be a git checkout: `execution-provenance.json` `runner.head` and `libraries[0].head` are `null` outside one, which changes the artifact goldens. CI and the farm checkouts satisfy this.
+
+### Normaliser
+
+`tests/contract/goldens/normalize.mjs` is the only normaliser. It rewrites only volatile values:
+
+1. Absolute paths: the sandbox becomes `<SANDBOX>`, the repo `<REPO>`, the real `$HOME` `<HOME>`, the node binary and its prefix `<NODE>`/`<NODE_PREFIX>`, and `os.tmpdir()` `<TMP>`. Both `/var` and `/private/var` spellings are covered. Ports from `gd_reserve_ports` become `<PORT:NAME>` in port positions only: numbers under `*port` keys, and in text after `:`, `port `, `port=` or `PORT=`, or a whole string equal to the port.
+2. UUIDs become `<UUID>`. Git object ids (40 hex, or a short hex value under a `*head`/`*gitRef`/`*commit` key) become `<GIT_REF>`. ISO-8601 timestamps become `<TIMESTAMP>`, and compact stamps in names `<STAMP>`. Path-derived slot ids `local-<adapter>-<8 hex>` become `local-<adapter>-<HASH>`.
+3. The package version becomes `<HARNESS_VERSION>`. Any other `x.y.z` under a key ending in `version` becomes `<VERSION>`.
+4. Numbers under volatile keys: `*pid` becomes `<PID>`, `*port` `<PORT>`, `*At`/`*Time`/`*timestamp`/`mtime*` `<TIMESTAMP>`, and `*Ms`/`duration*`/`elapsed*` `<DURATION>`. Values inside `schema` and `examples` subtrees (static manifest content) are never rewritten.
+5. `invocationDigest` becomes `<DIGEST>`: it hashes `recipe-invocation.json`, which carries sandbox paths and timestamps and is frozen itself in normalised form. `runner.sourceFingerprint` becomes `<FINGERPRINT>`: it hashes the harness source tree, so any harness edit changes it. A `status` holding `git status --porcelain` output (provenance `runner.status` and `libraries[].status`, empty when clean) becomes `<GIT_STATUS>`. Content-only digests (recipe and dependency digests) stay frozen.
+6. Durations in text (`0.3s`, `123ms`) become `<DURATION>`.
+
+In tree listings, files whose names differ only by a volatile token collapse into one row: a count and the union of their key shapes, or the sorted list of their values in a value tree.
+
+The `--update` summary diffs objects by key. Arrays whose entries all carry a unique `id`, `name` or `path` (manifest artifacts) diff by that key, so an inserted entry reads as one addition. Lists of plain values report `+[added] -[removed]`; other arrays diff element by element.
+
+The goldens run from the source checkout, so `harness.source` reads `source-checkout/source-checkout` and `harness.executable` is `<REPO>/bin/mm-harness`. On the farm both name the installed package instead.