@deeeed/metamask-harness 0.17.5 → 0.18.0

package/dist/commands/run-engine.js

@@ -9,8 +9,9 @@ import {
   recipeRunning,
   checkHealBounds
 } from "../heal-bounds.js";
-import { loadActionManifest, validateManifest } from "../manifest.js";
+import { resolveActionManifest, validateManifest } from "../manifest.js";
 import { getAdapterSurface } from "../adapters/surface.js";
+import { extensionProductConfigBlock } from "../adapters/extension/product-config.js";
 import {
   importRecipeHarness,
   importRecipeProtocol,
@@ -20,56 +21,51 @@ import {
 import { captureHelperSupportsRecordSessionSnapshots } from "../recording-target.js";
 import { listRecipeFiles } from "../recipe-files.js";
 import { startRecipeRecording, stopRecipeRecording } from "../run-recording.js";
+import {
+  beginRunDiagnostics,
+  finishRunDiagnostics
+} from "../run-diagnostics.js";
 import { EXIT, spawnScriptStreaming } from "./shared.js";
 import {
   actionManifestPathOption,
   optionString,
   isRecord,
   shellQuoteArg,
+  targetPath,
   usageError
 } from "./parse-args.js";
-async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManifestPath, runtimeOptions = {}) {
-  const previousCdpPort = process.env.CDP_PORT;
-  const previousRecipeCdpPort = process.env.RECIPE_CDP_PORT;
-  const previousWatcherPort = process.env.WATCHER_PORT;
-  const previousMetroPort = process.env.METRO_PORT;
-  const previousExtensionAutolaunch = process.env.METAMASK_RECIPE_EXTENSION_AUTOLAUNCH;
-  getAdapterSurface(adapter).resolveSlotPorts(projectRoot);
-  if (runtimeOptions.cdpPort) {
-    process.env.CDP_PORT = runtimeOptions.cdpPort;
-    process.env.RECIPE_CDP_PORT = runtimeOptions.cdpPort;
-  }
-  if (runtimeOptions.watcherPort) {
-    process.env.WATCHER_PORT = runtimeOptions.watcherPort;
-    process.env.METRO_PORT = runtimeOptions.watcherPort;
-  }
-  if (runtimeOptions.launchExistingDist) {
-    process.env.METAMASK_RECIPE_EXTENSION_AUTOLAUNCH = "1";
+function requireRecipeTrustResolver(harness) {
+  if (typeof harness.resolveRecipeTrustInput !== "function") {
+    throw usageError(
+      "Recipe trust enforcement requires a newer @farmslot/recipe-harness than the installed package. Next: mm-harness update"
+    );
   }
+  return harness.resolveRecipeTrustInput;
+}
+async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManifestPath, runtimeOptions = {}, preflightedExecution) {
+  const restoreRuntimeEnvironment = activateRecipeRuntimeEnvironment(
+    adapter,
+    projectRoot,
+    runtimeOptions
+  );
   try {
+    const execution = preflightedExecution ?? await resolveRecipeExecution(
+      adapter,
+      recipe,
+      artifactsDir,
+      projectRoot,
+      actionManifestPath,
+      runtimeOptions
+    );
+    const { runner, runRequest, absoluteArtifactsDir, useFramedExtensionRecording } = execution;
+    await runner.preflight(runRequest);
     await prepareRuntimeIfNeeded(adapter, projectRoot, runtimeOptions);
-    const absoluteArtifactsDir = path.resolve(artifactsDir);
-    const recordVideo = runtimeOptions.recordVideo ?? false;
-    const useFramedExtensionRecording = adapter === "extension" && recordVideo === "full-run" && captureHelperSupportsRecordSessionSnapshots(projectRoot);
+    const diagnosticBaseline = await beginRunDiagnostics(adapter, projectRoot);
     const recording = useFramedExtensionRecording ? await startRecipeRecording(adapter, projectRoot, absoluteArtifactsDir, {
       record: true,
       cdpPort: runtimeOptions.cdpPort
     }) : void 0;
     try {
-      const manifest = loadActionManifest(adapter, actionManifestPath);
-      await validateManifest(manifest);
-      const { createMetaMaskRunner } = await import("../runner.js");
-      const runner = await createMetaMaskRunner(adapter, manifest, {
-        quietStdout: runtimeOptions.stdoutIsMachineContract === true
-      });
-      const runRequest = {
-        recipePath: path.resolve(recipe),
-        artifactsDir: absoluteArtifactsDir,
-        projectRoot,
-        env: recipeRunEnv(adapter, runtimeOptions),
-        recordVideo: useFramedExtensionRecording ? false : recordVideo,
-        ...runtimeOptions.librarySources ? { librarySources: runtimeOptions.librarySources } : {}
-      };
       let result;
       try {
         result = await runner.run(runRequest);
@@ -80,17 +76,141 @@ async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManif
         }
       }
       await stopRecipeRecording(recording, result);
-      return result;
+      return finishRunDiagnostics(diagnosticBaseline, result);
     } finally {
       await stopRecipeRecording(recording);
     }
   } finally {
+    restoreRuntimeEnvironment();
+  }
+}
+async function preflightRecipe(adapter, recipe, artifactsDir, projectRoot, actionManifestPath, runtimeOptions = {}) {
+  const restoreRuntimeEnvironment = activateRecipeRuntimeEnvironment(
+    adapter,
+    projectRoot,
+    runtimeOptions
+  );
+  try {
+    const execution = await resolveRecipeExecution(
+      adapter,
+      recipe,
+      artifactsDir,
+      projectRoot,
+      actionManifestPath,
+      runtimeOptions
+    );
+    await execution.runner.preflight(execution.runRequest);
+    return execution;
+  } finally {
+    restoreRuntimeEnvironment();
+  }
+}
+async function resolveRecipeExecution(adapter, recipe, artifactsDir, projectRoot, actionManifestPath, runtimeOptions) {
+  const absoluteArtifactsDir = path.resolve(artifactsDir);
+  const absoluteRecipePath = typeof recipe === "string" ? path.resolve(recipe) : void 0;
+  const recordVideo = runtimeOptions.recordVideo ?? false;
+  const resolveRecipeTrustInput = requireRecipeTrustResolver(await importRecipeHarness());
+  const trust = resolveRecipeTrustInput({
+    sourceTrust: runtimeOptions.source?.trust,
+    sourceKind: runtimeOptions.source?.kind,
+    sourceName: runtimeOptions.source?.name,
+    sourceDigest: runtimeOptions.source?.digest,
+    approvalDigest: runtimeOptions.approval?.planDigest
+  });
+  const librarySources = executionLibrarySources(
+    runtimeOptions.librarySources,
+    trust.source?.trust ?? "trusted"
+  );
+  const { manifest, actionSources } = await resolveActionManifest(
+    adapter,
+    actionManifestPath,
+    librarySources,
+    process.env.METAMASK_RECIPE_LIVE_ADAPTER_DIR
+  );
+  const { createMetaMaskRunner } = await import("../runner.js");
+  const runner = await createMetaMaskRunner(adapter, manifest, {
+    quietStdout: runtimeOptions.stdoutIsMachineContract === true,
+    autoHud: trust.source && trust.source.trust !== "trusted" ? false : runtimeOptions.autoHud,
+    onActionEvent: runtimeOptions.onActionEvent,
+    actionSources,
+    // A direct engineer invocation is the explicit trust boundary for a
+    // task-local adapter. Inherited gateway provenance remains authoritative,
+    // so an untrusted worker cannot promote itself with CLI flags.
+    trustTaskActions: (trust.source?.trust ?? "trusted") === "trusted"
+  });
+  const useFramedExtensionRecording = adapter === "extension" && recordVideo === "full-run" && trust.source?.trust !== "untrusted" && trust.source?.trust !== "unknown" && captureHelperSupportsRecordSessionSnapshots(projectRoot);
+  return {
+    runner,
+    absoluteArtifactsDir,
+    useFramedExtensionRecording,
+    runRequest: {
+      ...absoluteRecipePath ? { recipePath: absoluteRecipePath } : { recipeDocument: recipe },
+      artifactsDir: absoluteArtifactsDir,
+      projectRoot,
+      inheritProcessEnv: false,
+      env: {
+        ...recipeProcessEnvironment(),
+        ...recipeRunEnv(adapter, runtimeOptions),
+        METAMASK_RECIPE_ACTION_SOURCE_MAP: actionSourceMap(actionSources)
+      },
+      recordVideo: useFramedExtensionRecording ? false : recordVideo,
+      ...trust,
+      ...librarySources ? { librarySources } : {}
+    }
+  };
+}
+function recipeProcessEnvironment() {
+  const env = { ...process.env };
+  delete env.MM_HARNESS_CHECKOUT_LOCK_TOKEN;
+  return env;
+}
+function executionLibrarySources(sources, invocationTrust) {
+  return sources?.map((source) => {
+    if (source.name === "metamask" || source.provenance?.trust === "trusted") return source;
+    return {
+      ...source,
+      provenance: {
+        ...source.provenance,
+        kind: source.provenance?.kind ?? "library",
+        trust: invocationTrust === "trusted" ? "trusted" : "unknown",
+        name: source.provenance?.name ?? source.name ?? path.basename(source.root)
+      }
+    };
+  });
+}
+function activateRecipeRuntimeEnvironment(adapter, projectRoot, runtimeOptions) {
+  const previousCdpPort = process.env.CDP_PORT;
+  const previousRecipeCdpPort = process.env.RECIPE_CDP_PORT;
+  const previousWatcherPort = process.env.WATCHER_PORT;
+  const previousMetroPort = process.env.METRO_PORT;
+  const previousExtensionAutolaunch = process.env.METAMASK_RECIPE_EXTENSION_AUTOLAUNCH;
+  getAdapterSurface(adapter).resolveSlotPorts(projectRoot);
+  if (runtimeOptions.cdpPort) {
+    process.env.CDP_PORT = runtimeOptions.cdpPort;
+    process.env.RECIPE_CDP_PORT = runtimeOptions.cdpPort;
+  }
+  if (runtimeOptions.watcherPort) {
+    process.env.WATCHER_PORT = runtimeOptions.watcherPort;
+    process.env.METRO_PORT = runtimeOptions.watcherPort;
+  }
+  if (runtimeOptions.launchExistingDist) {
+    process.env.METAMASK_RECIPE_EXTENSION_AUTOLAUNCH = "1";
+  }
+  return () => {
     restoreEnv("CDP_PORT", previousCdpPort);
     restoreEnv("RECIPE_CDP_PORT", previousRecipeCdpPort);
     restoreEnv("WATCHER_PORT", previousWatcherPort);
     restoreEnv("METRO_PORT", previousMetroPort);
     restoreEnv("METAMASK_RECIPE_EXTENSION_AUTOLAUNCH", previousExtensionAutolaunch);
+  };
+}
+function actionSourceMap(sources) {
+  const roots = {};
+  for (const [action, source] of sources) {
+    if (source.tier === "official") continue;
+    roots[action] = source.implementationRoot ?? (source.tier === "task" ? path.join(path.dirname(source.manifestPath), "actions") : path.join(path.dirname(path.dirname(source.manifestPath)), "actions"));
   }
+  return JSON.stringify(roots);
 }
 function recipeRunEnv(adapter, runtimeOptions = {}) {
   const base = {
@@ -162,12 +282,16 @@ function resolveRunRecipeArg(recipeArg, adapter, librarySources) {
           const file = path.join(source.root, "recipes", candidate);
           if (isRecipeFile(file)) return { recipeFile: file };
         }
+        const listedFile = recipeFileByPublicName(path.join(source.root, "recipes"), recipeArg, adapter);
+        if (listedFile) return { recipeFile: listedFile };
       }
     } else {
       for (const candidate of candidates) {
         const file = recipePath(candidate);
         if (isRecipeFile(file)) return { recipeFile: file };
       }
+      const listedFile = recipeFileByPublicName(recipePath(""), recipeArg, adapter);
+      if (listedFile) return { recipeFile: listedFile };
     }
   }
   const packagedNames = libraryRecipeNames(adapter);
@@ -176,6 +300,155 @@ function resolveRunRecipeArg(recipeArg, adapter, librarySources) {
   const suffix = packagedNames.length > 0 ? ` Library recipes for ${adapter}: ${packagedNames.join(", ")} (mm-harness run <name>).` : ` The packaged library has no recipes for ${adapter}.`;
   return { notFound: notFoundCore + suffix };
 }
+function readRecipeMetadata(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    return {
+      ...typeof parsed.title === "string" && parsed.title.trim() ? { title: parsed.title.trim() } : {},
+      ...typeof parsed.description === "string" && parsed.description.trim() ? { description: parsed.description.trim() } : {}
+    };
+  } catch {
+    return {};
+  }
+}
+function recipeNameFromFile(file, adapter) {
+  if (!file.endsWith(".recipe.json")) return void 0;
+  let name = file.slice(0, -".recipe.json".length).replace(/[\\/]/gu, ".");
+  const scope = name.split(".").pop() ?? "";
+  if (["mobile", "extension", "core"].includes(scope) && scope !== adapter) return void 0;
+  const scoped = scope === adapter;
+  if (scoped) name = name.slice(0, -(adapter.length + 1));
+  return { name, scoped };
+}
+function recipeFileByPublicName(recipesRoot, recipeName, adapter) {
+  let match;
+  let files;
+  try {
+    files = listRecipeFiles(recipesRoot);
+  } catch {
+    return void 0;
+  }
+  for (const file of files) {
+    const candidate = recipeNameFromFile(file, adapter);
+    if (!candidate || candidate.name !== recipeName) continue;
+    if (!match || candidate.scoped && !match.scoped) match = { file, scoped: candidate.scoped };
+  }
+  return match ? path.join(recipesRoot, match.file) : void 0;
+}
+function listRunnableRecipes(adapter, librarySources) {
+  const sources = librarySources && librarySources.length > 0 ? librarySources : [{ name: "metamask", root: recipePath("") }];
+  const resolved = /* @__PURE__ */ new Map();
+  for (const source of sources) {
+    const recipesRoot = librarySources && librarySources.length > 0 ? path.join(source.root, "recipes") : source.root;
+    let files;
+    try {
+      files = listRecipeFiles(recipesRoot);
+    } catch {
+      continue;
+    }
+    const sourceName = source.name ?? path.basename(source.root);
+    const withinSource = /* @__PURE__ */ new Map();
+    for (const file of files) {
+      const candidate = recipeNameFromFile(file, adapter);
+      if (!candidate) continue;
+      const existing = withinSource.get(candidate.name);
+      if (!existing || candidate.scoped && !existing.scoped) {
+        withinSource.set(candidate.name, { file, scoped: candidate.scoped });
+      }
+    }
+    for (const [name, candidate] of withinSource) {
+      const winner = resolved.get(name);
+      if (winner) winner.shadows.push(sourceName);
+      else resolved.set(name, {
+        name,
+        source: sourceName,
+        file: path.join("recipes", candidate.file),
+        shadows: [],
+        ...readRecipeMetadata(path.join(recipesRoot, candidate.file))
+      });
+    }
+  }
+  return [...resolved.values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+function describeRunnableRecipe(recipeArg, adapter, librarySources) {
+  const resolved = resolveRunRecipeArg(recipeArg, adapter, librarySources);
+  if ("notFound" in resolved) return resolved;
+  let document;
+  try {
+    document = JSON.parse(fs.readFileSync(resolved.recipeFile, "utf8"));
+  } catch (error) {
+    return {
+      unreadable: `could not read recipe ${resolved.recipeFile}: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+  if (!isRecord(document)) {
+    return { unreadable: `recipe ${resolved.recipeFile} must contain a JSON object.` };
+  }
+  const listed = listRunnableRecipes(adapter, librarySources).find((candidate) => candidate.name === recipeArg);
+  const composition = recipeComposition(document);
+  return {
+    recipe: {
+      name: listed?.name ?? recipeArg,
+      source: listed?.source ?? "file",
+      file: listed?.file ?? resolved.recipeFile,
+      shadows: listed?.shadows ?? [],
+      ...typeof document.title === "string" && document.title.trim() ? { title: document.title.trim() } : {},
+      ...typeof document.description === "string" && document.description.trim() ? { description: document.description.trim() } : {},
+      adapter,
+      path: resolved.recipeFile,
+      ...Object.prototype.hasOwnProperty.call(document, "schema_version") ? { schemaVersion: document.schema_version } : {},
+      inputs: isRecord(document.inputs) ? redactRecipeInputs(document.inputs) : {},
+      inputOverridesSupported: false,
+      actions: composition.actions,
+      actionsComplete: composition.actionsComplete,
+      flows: composition.flows
+    }
+  };
+}
+function recipeComposition(recipe) {
+  const actions = /* @__PURE__ */ new Set();
+  const flows = /* @__PURE__ */ new Set();
+  const visitNode = (value) => {
+    if (!isRecord(value) || typeof value.action !== "string") return;
+    actions.add(value.action);
+    if (value.action === "call" && typeof value.ref === "string") flows.add(value.ref);
+  };
+  const visitWorkflow = (value) => {
+    if (!isRecord(value)) return;
+    for (const phase of ["setup", "teardown"]) {
+      if (Array.isArray(value[phase])) value[phase].forEach(visitNode);
+    }
+    if (isRecord(value.nodes)) Object.values(value.nodes).forEach(visitNode);
+  };
+  visitNode(recipe.startState);
+  if (isRecord(recipe.validate)) visitWorkflow(recipe.validate.workflow);
+  const inlineFlows = isRecord(recipe.flows) ? recipe.flows : {};
+  const visitedFlows = /* @__PURE__ */ new Set();
+  let actionsComplete = true;
+  for (const ref of flows) {
+    if (visitedFlows.has(ref)) continue;
+    visitedFlows.add(ref);
+    const flow = inlineFlows[ref];
+    if (flow !== void 0) {
+      visitWorkflow(isRecord(flow) && isRecord(flow.workflow) ? flow.workflow : flow);
+    } else {
+      actionsComplete = false;
+    }
+  }
+  return {
+    actions: [...actions].sort(),
+    actionsComplete,
+    flows: [...flows].sort()
+  };
+}
+function redactRecipeInputs(inputs) {
+  return Object.fromEntries(
+    Object.entries(inputs).map(([key, value]) => [
+      key,
+      /(?:password|passphrase|secret|token|credential|mnemonic|seed|srp|vault|api[_-]?key|private[_-]?key)/iu.test(key) ? "<redacted>" : isRecord(value) ? redactRecipeInputs(value) : Array.isArray(value) ? value.map((entry) => isRecord(entry) ? redactRecipeInputs(entry) : entry) : value
+    ])
+  );
+}
 function libraryRecipeNames(adapter) {
   let entries;
   try {
@@ -183,20 +456,11 @@ function libraryRecipeNames(adapter) {
   } catch {
     return [];
   }
-  const scopes = ["mobile", "extension", "core"];
-  const names = entries.filter((f) => f.endsWith(".recipe.json")).map((f) => f.slice(0, -".recipe.json".length).replace(/[\\/]/gu, ".")).filter((n) => {
-    const scope = n.split(".").pop() ?? "";
-    return !scopes.includes(scope) || scope === adapter;
-  }).map((n) => n.endsWith(`.${adapter}`) ? n.slice(0, -(adapter.length + 1)) : n);
+  const names = entries.map((file) => recipeNameFromFile(file, adapter)?.name).filter((name) => Boolean(name));
   return [...new Set(names)].sort();
 }
 function recipeNameCandidates(recipeArg, adapter) {
-  const names = [recipeArg, ...LEGACY_RECIPE_ALIASES[recipeArg] ?? []];
-  const candidates = [];
-  for (const name of names) {
-    candidates.push(...singleRecipeNameCandidates(name, adapter));
-  }
-  return [...new Set(candidates)];
+  return singleRecipeNameCandidates(recipeArg, adapter);
 }
 function singleRecipeNameCandidates(name, adapter) {
   if (name.endsWith(".recipe.json")) {
@@ -222,32 +486,6 @@ function domainPathForRecipeName(name) {
 function uniqueStrings(values) {
   return [...new Set(values)];
 }
-const LEGACY_RECIPE_ALIASES = {
-  "action-validation": ["runner.action-validation"],
-  "action-validation.extension.recipe.json": ["runner.action-validation.extension.recipe.json"],
-  "action-validation.mobile.recipe.json": ["runner.action-validation.mobile.recipe.json"],
-  "app-lifecycle-android-smoke": ["app.lifecycle.android-smoke"],
-  "app-lifecycle-android-smoke.mobile.recipe.json": ["app.lifecycle.android-smoke.mobile.recipe.json"],
-  "order-lifecycle": ["perps.order-lifecycle"],
-  "order-lifecycle.core.recipe.json": ["perps.order-lifecycle.core.recipe.json"],
-  "perps-lifecycle": ["perps.lifecycle"],
-  "perps-lifecycle.recipe.json": ["perps.lifecycle.recipe.json"],
-  "perps-performance": ["perps.performance"],
-  "perps-performance-background-resume": ["perps.performance.background-resume"],
-  "perps-performance-background-resume.mobile.recipe.json": ["perps.performance.background-resume.mobile.recipe.json"],
-  "perps-performance-cold-start": ["perps.performance.cold-start"],
-  "perps-performance-cold-start.mobile.recipe.json": ["perps.performance.cold-start.mobile.recipe.json"],
-  "perps-performance-warm-start": ["perps.performance.warm-start"],
-  "perps-performance-warm-start.mobile.recipe.json": ["perps.performance.warm-start.mobile.recipe.json"],
-  "perps-performance.mobile.recipe.json": ["perps.performance.mobile.recipe.json"],
-  "read-markets": ["perps.read-markets"],
-  "read-markets.core.recipe.json": ["perps.read-markets.core.recipe.json"],
-  "smoke": ["runner.smoke"],
-  "smoke.extension.recipe.json": ["runner.smoke.extension.recipe.json"],
-  "smoke.mobile.recipe.json": ["runner.smoke.mobile.recipe.json"],
-  "trading-lifecycle": ["perps.trading-lifecycle"],
-  "trading-lifecycle.core.recipe.json": ["perps.trading-lifecycle.core.recipe.json"]
-};
 async function validateRunRecipeStatic(recipeArg, adapter, options) {
   const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
   const resolved = resolveRunRecipeArg(recipeArg, adapter, librarySources);
@@ -283,7 +521,11 @@ async function validateRunRecipeStatic(recipeArg, adapter, options) {
     };
   }
   const findings = [];
-  const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
+  const { manifest } = await resolveActionManifest(
+    adapter,
+    optionString(options, "actionManifest"),
+    librarySources
+  );
   let manifestOk = true;
   try {
     await validateManifest(manifest);
@@ -333,7 +575,12 @@ async function validateRunRecipeStatic(recipeArg, adapter, options) {
 async function actionInsteadOfRecipeHint(recipeArg, adapter, options) {
   if (recipeArg.includes("/") || recipeArg.includes(path.sep)) return "";
   try {
-    const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
+    const librarySources = await resolveMetaMaskLibrarySources(optionString(options, "library"));
+    const { manifest } = await resolveActionManifest(
+      adapter,
+      optionString(options, "actionManifest"),
+      librarySources
+    );
     const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
     const actions = getRecipeActionManifestActionNames(manifest);
     const matches = actions.includes(recipeArg) ? [recipeArg] : actions.filter((name) => name.split(".").pop() === recipeArg);
@@ -341,6 +588,7 @@ async function actionInsteadOfRecipeHint(recipeArg, adapter, options) {
     const device = optionString(options, "device");
     const actionManifest = optionString(options, "actionManifest");
     const parts = ["mm-harness", "call", matches[0]];
+    parts.push("--adapter", adapter, "--target", shellQuoteArg(targetPath(options)));
     if (device) parts.push("--device", shellQuoteArg(device));
     if (actionManifest) parts.push("--action-manifest", shellQuoteArg(actionManifest));
     return ` This is an action, not a recipe. Use: ${parts.join(" ")}.`;
@@ -353,16 +601,33 @@ async function resolveMetaMaskLibrarySources(libraryEntry) {
   if (typeof harness.resolveRecipeLibrarySources !== "function") {
     if (libraryEntry) {
       throw usageError(
-        "--library requires @farmslot/recipe-harness >= 0.3.3 (recipe-library support / resolveRecipeLibrarySources). The pinned 0.3.0 lacks it, and npm 0.3.2 still does not export it \u2014 recipe-library support is PENDING PUBLISH from farmslot."
+        "--library requires a current @farmslot/recipe-harness installation that exports recipe-library support. Next: mm-harness update"
       );
     }
     return void 0;
   }
+  const cliEntries = typeof libraryEntry === "string" ? [libraryEntry] : libraryEntry ? [...libraryEntry] : [];
   const sources = await harness.resolveRecipeLibrarySources(
-    libraryEntry ? { cliEntries: [libraryEntry] } : void 0
+    cliEntries.length > 0 ? { cliEntries } : void 0
   );
-  sources.push({ name: "metamask", root: path.join(runnerDir, "library") });
-  return sources;
+  const canonicalRoot = path.resolve(runnerDir, "library");
+  const configuredCanonical = sources.find((source) => source.name === "metamask");
+  if (configuredCanonical && path.resolve(configuredCanonical.root) !== canonicalRoot) {
+    throw usageError(
+      `Recipe library source metamask must resolve to ${canonicalRoot}; got ${path.resolve(configuredCanonical.root)}.`
+    );
+  }
+  if (!sources.some((source) => path.resolve(source.root) === canonicalRoot)) {
+    sources.push({ name: "metamask", root: canonicalRoot });
+  }
+  return sources.map((source) => ({
+    ...source,
+    provenance: source.provenance ?? {
+      kind: source.name === "metamask" ? "bundled" : "library",
+      trust: source.name === "metamask" ? "trusted" : "unknown",
+      name: source.name ?? path.basename(source.root)
+    }
+  }));
 }
 function synthesizeOneNodeRecipe(action, args) {
   return {
@@ -373,7 +638,12 @@ function synthesizeOneNodeRecipe(action, args) {
       workflow: {
         entry: "call",
         nodes: {
-          call: { action, ...args, next: "done", intent: `Call ${action} in isolation` },
+          call: {
+            ...args,
+            action,
+            next: "done",
+            intent: typeof args.intent === "string" ? args.intent : `Call ${action} in isolation`
+          },
           done: { action: "end", status: "pass" }
         }
       }
@@ -381,7 +651,8 @@ function synthesizeOneNodeRecipe(action, args) {
   };
 }
 async function runOneNode(adapter, action, args, target, actionManifest) {
-  const manifest = loadActionManifest(adapter, actionManifest);
+  const librarySources = await resolveMetaMaskLibrarySources(void 0);
+  const { manifest } = await resolveActionManifest(adapter, actionManifest, librarySources);
   const recipe = synthesizeOneNodeRecipe(action, args);
   const validation = await validateRecipeAdapterAware(recipe, manifest);
   if (validation.status === "invalid") return { status: "fail" };
@@ -390,7 +661,7 @@ async function runOneNode(adapter, action, args, target, actionManifest) {
   fs.writeFileSync(recipeFile, `${JSON.stringify(recipe, null, 2)}
 `);
   const result = await runRecipe(adapter, recipeFile, path.join(scratch, "artifacts"), target, actionManifest, {
-    librarySources: await resolveMetaMaskLibrarySources(void 0),
+    librarySources,
     stdoutIsMachineContract: true
   });
   return { status: result.status === "pass" ? "pass" : "fail" };
@@ -398,10 +669,12 @@ async function runOneNode(adapter, action, args, target, actionManifest) {
 async function prepareHeal(adapter, target, options, json, prepareOptions = {}) {
   if (recipeRunning(target)) {
     const msg = "a recipe is currently running \u2014 refusing to start while another recipe executes.";
+    const userAction = `inspect the checkout state with: mm-harness status --target ${shellQuoteArg(target)} --json; retry after the active recipe finishes`;
     if (json) {
-      console.log(JSON.stringify({ schemaVersion: 1, status: "fail", recoverable: false, error: { code: "RECIPE_RUNNING", message: msg } }, null, 2));
+      console.log(JSON.stringify({ schemaVersion: 1, status: "fail", recoverable: false, error: { code: "RECIPE_RUNNING", message: msg, userAction } }, null, 2));
     } else {
-      console.error(`\u2717 mm-harness: ${msg}`);
+      console.error(`\u2717 mm-harness: ${msg}
+  Next: ${userAction}`);
     }
     return EXIT.bounded;
   }
@@ -414,21 +687,25 @@ async function prepareHeal(adapter, target, options, json, prepareOptions = {})
     return EXIT.usage;
   }
   const state = newHealState();
+  prepareOptions.onPhase?.("install");
   const ensured = await ensureOverlay(adapter, target, heal, state, json);
   if (!ensured.ok) {
+    const userAction = `mm-harness install --adapter ${adapter} --target ${shellQuoteArg(target)}`;
     if (json) {
       console.log(
         JSON.stringify(
-          { schemaVersion: 1, status: "fail", recoverable: false, mutations: state.mutations, error: { code: "OVERLAY_INSTALL_FAILED", message: ensured.error } },
+          { schemaVersion: 1, status: "fail", recoverable: false, mutations: state.mutations, error: { code: "OVERLAY_INSTALL_FAILED", message: ensured.error, userAction } },
           null,
           2
         )
       );
     } else {
-      console.error(`\u2717 overlay auto-ensure failed: ${ensured.error}`);
+      console.error(`\u2717 overlay auto-ensure failed: ${ensured.error}
+  Next: ${userAction}`);
     }
     return EXIT.infra;
   }
+  prepareOptions.onPhase?.("healthcheck");
   if (adapter === "extension") {
     const previousCdpPort = process.env.CDP_PORT;
     const previousRecipeCdpPort = process.env.RECIPE_CDP_PORT;
@@ -441,7 +718,9 @@ async function prepareHeal(adapter, target, options, json, prepareOptions = {})
     }
     if (explicitWatcherPort) process.env.WATCHER_PORT = explicitWatcherPort;
     try {
-      const current = await ensureExtensionProofRuntime(target, heal, state, json);
+      const current = await ensureExtensionProofRuntime(target, heal, state, json, {
+        onRecovery: (code) => prepareOptions.onPhase?.("recover", { code })
+      });
       if (current !== null) return current;
     } finally {
       restoreEnv("CDP_PORT", previousCdpPort);
@@ -450,7 +729,9 @@ async function prepareHeal(adapter, target, options, json, prepareOptions = {})
     }
   }
   if (adapter === "mobile" && prepareOptions.skipMobileSourceFreshness !== true) {
-    const current = await ensureMobileProofRuntime(target, heal, state, json);
+    const current = await ensureMobileProofRuntime(target, heal, state, json, {
+      onRecovery: (code) => prepareOptions.onPhase?.("recover", { code })
+    });
     if (current !== null) return current;
   }
   return { state, heal };
@@ -460,6 +741,20 @@ async function ensureMobileProofRuntime(target, heal, state, json, deps = {}) {
   const check = deps.check ?? (() => source.mobileSourceCheck(target));
   const record = deps.record ?? ((fingerprint) => source.recordMobileSourceBaseline(target, fingerprint));
   const initial = check();
+  if (initial.status === "unavailable") {
+    if (json) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        status: "fail",
+        recoverable: false,
+        error: initial.error
+      }, null, 2));
+    } else {
+      console.error(`\u2717 ${initial.error.message}`);
+      console.error(`  Next: ${initial.error.userAction}`);
+    }
+    return EXIT.usage;
+  }
   if (initial.status === "current") return null;
   const targetArg = JSON.stringify(path.resolve(target));
   const userAction = `mm-harness call app.lifecycle --arg command=restart --adapter mobile --target ${targetArg}`;
@@ -481,6 +776,7 @@ async function ensureMobileProofRuntime(target, heal, state, json, deps = {}) {
   }
   const recoveryCode = "mobile.source_reloaded";
   state.attemptedRecoveries.push(recoveryCode);
+  deps.onRecovery?.(recoveryCode);
   if (!json) console.error(`\u2192 Mobile proof preflight: source ${initial.status}; restarting the app before execution`);
   const restart = deps.restart ?? (async () => {
     const result2 = await runOneNode(
@@ -521,6 +817,12 @@ async function ensureMobileProofRuntime(target, heal, state, json, deps = {}) {
   state.mutations.push({ type: "runtime", action: "restarted", reasonCode: `source-${initial.status}` });
   return null;
 }
+function resolveRunMobilePlatform() {
+  if (process.env.PLATFORM === "android" || process.env.PLATFORM === "ios") {
+    return process.env.PLATFORM;
+  }
+  return process.env.ADB_SERIAL || process.env.ANDROID_SERIAL ? "android" : "ios";
+}
 async function ensureExtensionProofRuntime(target, heal, state, json, deps = {}) {
   const decide = deps.decide ?? (async () => {
     const { decideExtensionReadiness } = await import("../adapters/extension/runtime-decision.js");
@@ -532,6 +834,22 @@ async function ensureExtensionProofRuntime(target, heal, state, json, deps = {})
   });
   const initial = await decide();
   if (initial.decision === "ready") return null;
+  if (initial.reasonCode === "runtime-dist-check-failed") {
+    const message = `Extension proof runtime freshness could not be checked: ${initial.reasons[0] ?? initial.decision}`;
+    const userAction2 = `mm-harness doctor --adapter extension --target ${JSON.stringify(path.resolve(target))}`;
+    if (json) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        status: "fail",
+        recoverable: false,
+        error: { code: "EXTENSION_RUNTIME_CHECK_FAILED", message, userAction: userAction2 }
+      }, null, 2));
+    } else {
+      console.error(`\u2717 ${message}`);
+      console.error(`  Next: ${userAction2}`);
+    }
+    return EXIT.infra;
+  }
   if (!["dist-stale", "dist-missing", "runtime-dist-stale", "runtime-dist-missing"].includes(initial.reasonCode)) {
     return null;
   }
@@ -556,20 +874,33 @@ async function ensureExtensionProofRuntime(target, heal, state, json, deps = {})
     return EXIT.infra;
   }
   const recoveryCode = tier === "build" ? "extension.runtime_rebuilt" : "extension.runtime_reloaded";
+  const productConfigBlock = tier === "build" ? extensionProductConfigBlock(target) : null;
+  if (productConfigBlock) {
+    const message = productConfigBlock.message;
+    const userAction2 = productConfigBlock.userAction;
+    if (json) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        status: "fail",
+        recoverable: false,
+        mutations: state.mutations,
+        error: { code: "EXTENSION_PRODUCT_CONFIG_REQUIRED", message, userAction: userAction2 }
+      }, null, 2));
+    } else {
+      console.error(`\u2717 ${message}`);
+      console.error(`  Next: ${userAction2}`);
+    }
+    return EXIT.infra;
+  }
   state.attemptedRecoveries.push(recoveryCode);
+  deps.onRecovery?.(recoveryCode);
   if (!json) console.error(`\u2192 Extension proof preflight: ${initial.reasonCode}; ${tier === "build" ? "rebuilding" : "reloading"} before execution`);
   const launch = deps.launch ?? (async (requestedTier) => {
     const { launchExtension } = await import("./launch/extension.js");
     return launchExtension(target, requestedTier, false);
   });
   const result = await launch(tier);
-  let verified = result.status === 0 ? await decide() : initial;
-  if (result.status === 0 && verified.decision !== "ready") {
-    for (let attempt = 0; attempt < 8 && verified.decision !== "ready"; attempt += 1) {
-      await new Promise((resolve) => setTimeout(resolve, 250));
-      verified = await decide();
-    }
-  }
+  const verified = result.status === 0 ? await decide() : initial;
   if (result.status !== 0 || verified.decision !== "ready") {
     const message = `Extension runtime recovery did not produce a current healthy runtime (${verified.reasonCode}).`;
     if (json) {
@@ -603,17 +934,11 @@ async function recoverRunInfra(adapter, target, json) {
   }
   if (adapter === "mobile") {
     const { launchMobile } = await import("./launch/mobile.js");
-    const platform = resolveRunMobilePlatform();
+    const platform = process.env.PLATFORM === "android" ? "android" : "ios";
     return launchMobile(target, platform, "quick", json);
   }
   return { status: 0, output: "headless run retry" };
 }
-function resolveRunMobilePlatform() {
-  if (process.env.PLATFORM === "android" || process.env.PLATFORM === "ios") {
-    return process.env.PLATFORM;
-  }
-  return process.env.ADB_SERIAL || process.env.ANDROID_SERIAL ? "android" : "ios";
-}
 function readRunFailureText(result) {
   try {
     const trace = JSON.parse(fs.readFileSync(result.tracePath, "utf8"));
@@ -623,7 +948,7 @@ function readRunFailureText(result) {
     return "";
   }
 }
-async function executeWithHealBounds(exec, adapter, target, heal, state, recover = () => recoverRunInfra(adapter, target, false)) {
+async function executeWithHealBounds(exec, adapter, target, heal, state, recover = () => recoverRunInfra(adapter, target, false), onRecovery = () => void 0) {
   let result = await exec();
   for (; ; ) {
     if (result.status === "pass") return { result, violation: null };
@@ -632,6 +957,7 @@ async function executeWithHealBounds(exec, adapter, target, heal, state, recover
     if (heal === "off") return { result, violation: null };
     const recoveryCode = RUN_RECOVERY_CODE[adapter];
     state.attemptedRecoveries.push(recoveryCode);
+    onRecovery(recoveryCode);
     await recover();
     result = await exec();
     if (result.status === "pass") {
@@ -641,7 +967,7 @@ async function executeWithHealBounds(exec, adapter, target, heal, state, recover
   }
 }
 function emitHealViolation(json, command, result, violation, state, adapter) {
-  const userAction = adapter === "core" && violation.code === "WALLET_STATE_REQUIRED" ? 'set MM_TEST_ACCOUNT_ADDRESS=<0x\u2026> in env, or add "account": "<0x\u2026>" to the node block in the recipe' : violation.userAction;
+  const userAction = adapter === "core" && violation.code === "WALLET_STATE_REQUIRED" ? 'create temp/recipe/runtime/wallet-fixture.json, or add "account": "<0x\u2026>" to the node block in the recipe' : violation.userAction ?? `inspect ${shellQuoteArg(result.summaryPath)} and ${shellQuoteArg(result.tracePath)}; fix the application or recipe failure before retrying`;
   if (json) {
     console.log(
       JSON.stringify(
@@ -661,7 +987,7 @@ function emitHealViolation(json, command, result, violation, state, adapter) {
             code: violation.code,
             message: violation.message,
             retryable: false,
-            userAction: userAction ?? null,
+            userAction,
             originalError: violation.originalError ?? null
           }
         },
@@ -688,12 +1014,16 @@ function countRecipeNodes(recipe) {
 }
 export {
   countRecipeNodes,
+  describeRunnableRecipe,
   emitHealViolation,
   ensureExtensionProofRuntime,
   ensureMobileProofRuntime,
   executeWithHealBounds,
+  listRunnableRecipes,
+  preflightRecipe,
   prepareHeal,
   recoverRunInfra,
+  requireRecipeTrustResolver,
   resolveMetaMaskLibrarySources,
   resolveRunRecipeArg,
   runOneNode,