@deeeed/metamask-harness 0.17.5 → 0.19.0

package/dist/commands/run-engine.js

@@ -7,90 +7,220 @@ import {
   newHealState,
   parseHeal,
   recipeRunning,
-  checkHealBounds
+  checkHealBounds,
+  conciseFailureForHuman
 } 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,
-  recipePath,
   runnerDir
 } from "../paths.js";
 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,
+  optionStrings,
   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";
-  }
+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);
       } finally {
         if (adapter === "mobile") {
           const { hideMobileHudOnTeardown } = await import("../adapters.js");
-          await hideMobileHudOnTeardown(projectRoot, recipeRunEnv(adapter, runtimeOptions));
+          await hideMobileHudOnTeardown(
+            projectRoot,
+            recipeRunEnv(adapter, runtimeOptions)
+          );
         }
       }
       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 } = 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,
+    suppressLibraryResolutionLogs: runtimeOptions.suppressLibraryResolutionLogs,
+    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 } : {},
+      adapter,
+      ...runtimeOptions.params ? { params: runtimeOptions.params } : {}
+    }
+  };
+}
+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);
+    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 = {
@@ -113,7 +243,8 @@ function recipeRunEnv(adapter, runtimeOptions = {}) {
   };
 }
 async function prepareRuntimeIfNeeded(adapter, projectRoot, runtimeOptions) {
-  if (adapter !== "extension" || runtimeOptions.skipExtensionRuntimePrepare === true) return;
+  if (adapter !== "extension" || runtimeOptions.skipExtensionRuntimePrepare === true)
+    return;
   const { prepareExtensionRuntime } = await import("../adapters/extension/runtime.js");
   await prepareExtensionRuntime({
     projectRoot,
@@ -128,21 +259,74 @@ function restoreEnv(key, value) {
   if (value === void 0) delete process.env[key];
   else process.env[key] = value;
 }
-async function validateRecipeAdapterAware(recipe, manifest, librarySources) {
-  const { validateRecipeDocument, validateRecipeWithManifest } = await importRecipeProtocol();
-  let externalFlowIds;
+async function validateRecipeAdapterAware(adapter, recipe, manifest, librarySources, rootRef, params) {
+  const protocol = await importRecipeProtocol();
+  let externalRecipeIds;
+  let libraryResolution;
+  const harness = await importRecipeHarness();
   if (librarySources && librarySources.length > 0) {
-    const harness = await importRecipeHarness();
-    const resolution = await harness.loadRecipeLibraries(librarySources);
-    externalFlowIds = new Set(resolution.flows.keys());
-  }
-  const validationOptions = externalFlowIds !== void 0 ? { externalFlowIds } : void 0;
-  const schema = validateRecipeDocument(recipe, validationOptions);
-  const withManifest = validateRecipeWithManifest(recipe, manifest, validationOptions);
-  const findings = [...schema.findings, ...withManifest.findings];
-  const errors = findings.filter((finding) => finding.severity === "error").length;
+    libraryResolution = await harness.loadRecipeLibraries(librarySources, {
+      adapter
+    });
+    externalRecipeIds = new Set(libraryResolution.recipes.keys());
+  }
+  const validationOptions = externalRecipeIds !== void 0 ? { externalRecipeIds } : void 0;
+  const withManifest = protocol.validateRecipeWithManifest(
+    recipe,
+    manifest,
+    validationOptions
+  );
+  const findings = [...withManifest.findings];
+  if (withManifest.status === "valid" && isRecord(recipe) && libraryResolution) {
+    try {
+      const digest = protocol.digestRecipeDocument(recipe);
+      const dependencies = harness.resolveRecipeDependencies({
+        rootRef: rootRef ?? `$root:${digest}`,
+        root: recipe,
+        rootSource: {
+          kind: "recipe-file",
+          trust: "unknown",
+          name: rootRef ?? "recipe file",
+          digest
+        },
+        recipes: libraryResolution.recipes
+      });
+      if (params) {
+        harness.validateRecipeDependencyParams({
+          root: recipe,
+          params,
+          recipes: dependencies.recipes
+        });
+      }
+      for (const dependency of dependencies.recipes.values()) {
+        findings.push(
+          ...protocol.validateRecipeWithManifest(
+            dependency.document,
+            manifest,
+            validationOptions
+          ).findings
+        );
+      }
+    } catch (error) {
+      const resolutionError = error instanceof harness.RecipeResolutionError ? error : void 0;
+      if (!resolutionError) throw error;
+      findings.push({
+        severity: "error",
+        code: resolutionError.code,
+        path: "workflow",
+        message: `${resolutionError.message} Next: ${resolutionError.userAction}`
+      });
+    }
+  }
+  const errors = findings.filter(
+    (finding) => finding.severity === "error"
+  ).length;
   const warnings = findings.length - errors;
-  return { status: errors > 0 ? "invalid" : "valid", findings, summary: { errors, warnings } };
+  return {
+    status: errors > 0 ? "invalid" : "valid",
+    findings,
+    summary: { errors, warnings }
+  };
 }
 function isRecipeFile(p) {
   try {
@@ -151,107 +335,169 @@ function isRecipeFile(p) {
     return false;
   }
 }
-function resolveRunRecipeArg(recipeArg, adapter, librarySources) {
+async function resolveRunRecipeArg(recipeArg, adapter, librarySources) {
   const direct = path.resolve(recipeArg);
   if (isRecipeFile(direct)) return { recipeFile: direct };
+  const sources = effectiveLibrarySources(librarySources);
+  const harness = await importRecipeHarness();
+  const resolution = await harness.loadRecipeLibraries(sources, { adapter });
   if (!recipeArg.includes("/") && !recipeArg.includes(path.sep)) {
-    const candidates = recipeNameCandidates(recipeArg, adapter);
-    if (librarySources && librarySources.length > 0) {
-      for (const source of librarySources) {
-        for (const candidate of candidates) {
-          const file = path.join(source.root, "recipes", candidate);
-          if (isRecipeFile(file)) return { recipeFile: file };
-        }
-      }
-    } else {
-      for (const candidate of candidates) {
-        const file = recipePath(candidate);
-        if (isRecipeFile(file)) return { recipeFile: file };
-      }
-    }
+    const selected = resolution.recipes.get(recipeArg);
+    if (selected) return { recipeFile: selected.path, ref: selected.ref };
   }
-  const packagedNames = libraryRecipeNames(adapter);
-  const nonCanonical = librarySources?.filter((s) => s.name !== "metamask") ?? [];
-  const notFoundCore = nonCanonical.length > 0 ? `recipe not found: ${recipeArg} \u2014 not a file, and no recipe matched in library sources [${librarySources.map((s) => s.name ?? path.basename(s.root)).join(", ")}].` : `recipe not found: ${recipeArg} \u2014 not a file, and no packaged library recipe matched.`;
-  const suffix = packagedNames.length > 0 ? ` Library recipes for ${adapter}: ${packagedNames.join(", ")} (mm-harness run <name>).` : ` The packaged library has no recipes for ${adapter}.`;
+  const available = [...resolution.recipes.keys()].sort();
+  const nonCanonical = sources.filter((source) => source.name !== "metamask");
+  const notFoundCore = nonCanonical.length > 0 ? `recipe not found: ${recipeArg} \u2014 not a file, and no recipe matched in library sources [${sources.map((source) => source.name ?? path.basename(source.root)).join(", ")}].` : `recipe not found: ${recipeArg} \u2014 not a file, and no packaged library recipe matched.`;
+  const suffix = available.length > 0 ? ` Library recipes for ${adapter}: ${available.join(", ")} (mm-harness run <name>).` : ` The packaged library has no recipes for ${adapter}.`;
   return { notFound: notFoundCore + suffix };
 }
-function libraryRecipeNames(adapter) {
-  let entries;
+function effectiveLibrarySources(librarySources) {
+  return librarySources && librarySources.length > 0 ? librarySources : [{ name: "metamask", root: path.resolve(runnerDir, "library") }];
+}
+async function listRunnableRecipes(adapter, librarySources) {
+  const harness = await importRecipeHarness();
+  const resolution = await harness.loadRecipeLibraries(
+    effectiveLibrarySources(librarySources),
+    {
+      adapter
+    }
+  );
+  return [...resolution.recipes.values()].map(
+    (recipe) => recipeSummary(recipe.ref, adapter, recipe.document, recipe)
+  ).sort((left, right) => left.name.localeCompare(right.name));
+}
+async function describeRunnableRecipe(recipeArg, adapter, librarySources) {
+  const resolved = await resolveRunRecipeArg(
+    recipeArg,
+    adapter,
+    librarySources
+  );
+  if ("notFound" in resolved) return resolved;
+  let document;
   try {
-    entries = listRecipeFiles(recipePath(""));
-  } 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);
-  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)];
-}
-function singleRecipeNameCandidates(name, adapter) {
-  if (name.endsWith(".recipe.json")) {
-    return uniqueStrings([domainPathForRecipeFile(name), name]);
-  }
-  const bases = uniqueStrings([domainPathForRecipeName(name), name]);
-  const candidates = [];
-  for (const base of bases) {
-    candidates.push(`${base}.${adapter}.recipe.json`, `${base}.recipe.json`, base);
-  }
-  return candidates;
-}
-function domainPathForRecipeFile(name) {
-  const suffix = ".recipe.json";
-  const base = name.slice(0, -suffix.length);
-  return `${domainPathForRecipeName(base)}${suffix}`;
-}
-function domainPathForRecipeName(name) {
-  if (name.includes("/") || name.includes(path.sep)) return name;
-  const dot = name.indexOf(".");
-  return dot > 0 ? `${name.slice(0, dot)}/${name.slice(dot + 1)}` : 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);
+    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 harness = await importRecipeHarness();
+  const libraryResolution = await harness.loadRecipeLibraries(
+    effectiveLibrarySources(librarySources),
+    { adapter }
+  );
+  const selected = resolved.ref ? libraryResolution.recipes.get(resolved.ref) : void 0;
+  const composition = recipeComposition(document, libraryResolution.recipes);
+  const summary = recipeSummary(
+    resolved.ref ?? recipeArg,
+    adapter,
+    document,
+    selected
+  );
+  return {
+    recipe: {
+      ...summary,
+      source: selected?.source ?? "file",
+      file: selected?.file ?? resolved.recipeFile,
+      path: resolved.recipeFile,
+      ...typeof document.$schema === "string" ? { $schema: document.$schema } : {},
+      actions: composition.actions,
+      nestedRecipes: composition.nestedRecipes,
+      unresolvedRecipes: composition.unresolvedRecipes
+    }
+  };
+}
+function recipeSummary(ref, adapter, document, selected) {
+  return {
+    name: ref,
+    source: selected?.source ?? "file",
+    file: selected?.file ?? "",
+    shadows: selected?.shadows ?? [],
+    adapter,
+    variant: selected?.adapter ?? null,
+    parameters: recipeParameters(document),
+    ...typeof document.title === "string" && document.title.trim() ? { title: document.title.trim() } : {},
+    ...typeof document.description === "string" && document.description.trim() ? { description: document.description.trim() } : {}
+  };
+}
+function recipeParameters(document) {
+  if (!isRecord(document.paramsSchema)) return [];
+  const schema = document.paramsSchema;
+  const required = new Set(
+    Array.isArray(schema.required) ? schema.required.filter(
+      (entry) => typeof entry === "string"
+    ) : []
+  );
+  if (!isRecord(schema.properties)) return [];
+  return Object.entries(schema.properties).map(([name, raw]) => {
+    const property = isRecord(raw) ? raw : {};
+    return {
+      name,
+      ...typeof property.type === "string" ? { type: property.type } : {},
+      required: required.has(name),
+      ...Object.hasOwn(property, "default") ? { default: property.default } : {},
+      ...typeof property.description === "string" ? { description: property.description } : {},
+      ...Array.isArray(property.enum) ? { enum: property.enum } : {}
+    };
+  });
+}
+function recipeComposition(recipe, recipes) {
+  const actions = /* @__PURE__ */ new Set();
+  const nestedRecipes = /* @__PURE__ */ new Set();
+  const unresolvedRecipes = /* @__PURE__ */ new Set();
+  const visitedRecipes = /* @__PURE__ */ new Set();
+  const visitNode = (value) => {
+    if (!isRecord(value) || typeof value.action !== "string") return;
+    if (value.action !== "call") {
+      actions.add(value.action);
+      return;
+    }
+    if (typeof value.ref !== "string") return;
+    nestedRecipes.add(value.ref);
+    const dependency = recipes.get(value.ref);
+    if (!dependency) {
+      unresolvedRecipes.add(value.ref);
+      return;
+    }
+    if (visitedRecipes.has(value.ref)) return;
+    visitedRecipes.add(value.ref);
+    visitRecipe(dependency.document);
+  };
+  const visitWorkflow = (value) => {
+    if (!isRecord(value)) return;
+    if (isRecord(value.nodes)) Object.values(value.nodes).forEach(visitNode);
+  };
+  const visitRecipe = (document) => {
+    visitWorkflow(document.workflow);
+  };
+  visitRecipe(recipe);
+  return {
+    actions: [...actions].sort(),
+    nestedRecipes: [...nestedRecipes].sort(),
+    unresolvedRecipes: [...unresolvedRecipes].sort()
+  };
+}
+async function validateRunRecipeStatic(recipeArg, adapter, options, params = {}) {
+  let librarySources = await resolveMetaMaskLibrarySources(
+    optionStrings(options, "library")
+  );
+  const resolved = await resolveRunRecipeArg(
+    recipeArg,
+    adapter,
+    librarySources
+  );
   const recipeFile = "recipeFile" in resolved ? resolved.recipeFile : path.resolve(recipeArg);
+  if ("recipeFile" in resolved && !resolved.ref) {
+    librarySources = await resolveMetaMaskLibrarySources(
+      optionStrings(options, "library"),
+      recipeFile
+    );
+  }
   const empty = {
     recipe: void 0,
     recipeFile,
@@ -259,6 +505,7 @@ async function validateRunRecipeStatic(recipeArg, adapter, options) {
     errorCount: 0,
     manifestOk: false,
     schemaValid: false,
+    effectiveParams: params,
     ...librarySources ? { librarySources } : {}
   };
   if ("notFound" in resolved) {
@@ -283,7 +530,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);
@@ -296,30 +547,47 @@ async function validateRunRecipeStatic(recipeArg, adapter, options) {
       message: error instanceof Error ? error.message : String(error)
     });
   }
-  const validation = manifestOk ? await validateRecipeAdapterAware(recipe, manifest, librarySources) : { status: "invalid", findings: [], summary: { errors: 1, warnings: 0 } };
-  findings.push(...validation.findings);
+  let effectiveParams = params;
   if (isRecord(recipe)) {
-    const validate = isRecord(recipe.validate) ? recipe.validate : void 0;
-    const workflow = validate && isRecord(validate.workflow) ? validate.workflow : void 0;
-    if (workflow?.startState != null) {
-      findings.push({
-        severity: "error",
-        code: "recipe.start-state-placement",
-        path: "validate.workflow.startState",
-        message: "startState must be declared at the recipe root, not validate.workflow.startState"
-      });
-    }
-    const startState = isRecord(recipe.startState) ? recipe.startState : void 0;
-    if (adapter === "extension" && startState?.action === "metamask.perps.start_state" && startState.page === false) {
-      findings.push({
-        severity: "error",
-        code: "recipe.extension-perps-start-page",
-        path: "startState.page",
-        message: "Extension metamask.perps.start_state must enter Perps; omit page or provide a string target instead of false"
-      });
+    const protocol = await importRecipeProtocol();
+    effectiveParams = protocol.applyRecipeParamDefaults(
+      params,
+      recipe.paramsSchema
+    );
+    findings.push(
+      ...protocol.validateRecipeParams(effectiveParams, recipe.paramsSchema).findings
+    );
+    const workflow = isRecord(recipe.workflow) ? recipe.workflow : void 0;
+    const nodes = workflow && isRecord(workflow.nodes) ? workflow.nodes : void 0;
+    if (adapter === "extension" && nodes) {
+      for (const [nodeId, node] of Object.entries(nodes)) {
+        if (isRecord(node) && node.action === "metamask.perps.start_state" && node.page === false) {
+          findings.push({
+            severity: "error",
+            code: "recipe.extension-perps-start-page",
+            path: `workflow.nodes.${nodeId}.page`,
+            message: "Extension metamask.perps.start_state must enter Perps; omit page or provide a string target instead of false"
+          });
+        }
+      }
     }
   }
-  const errorCount = findings.filter((finding) => finding.severity === "error").length;
+  const validation = manifestOk ? await validateRecipeAdapterAware(
+    adapter,
+    recipe,
+    manifest,
+    librarySources,
+    resolved.ref,
+    effectiveParams
+  ) : {
+    status: "invalid",
+    findings: [],
+    summary: { errors: 1, warnings: 0 }
+  };
+  findings.push(...validation.findings);
+  const errorCount = findings.filter(
+    (finding) => finding.severity === "error"
+  ).length;
   return {
     recipe,
     recipeFile,
@@ -327,13 +595,21 @@ async function validateRunRecipeStatic(recipeArg, adapter, options) {
     errorCount,
     manifestOk,
     schemaValid: validation.status === "valid" && errorCount === 0,
+    effectiveParams,
     ...librarySources ? { librarySources } : {}
   };
 }
 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(
+      optionStrings(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,67 +617,119 @@ 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));
+    if (actionManifest)
+      parts.push("--action-manifest", shellQuoteArg(actionManifest));
     return ` This is an action, not a recipe. Use: ${parts.join(" ")}.`;
   } catch {
     return "";
   }
 }
-async function resolveMetaMaskLibrarySources(libraryEntry) {
+async function resolveMetaMaskLibrarySources(libraryEntry, recipePath) {
   const harness = await importRecipeHarness();
-  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."
-      );
-    }
-    return void 0;
-  }
-  const sources = await harness.resolveRecipeLibrarySources(
-    libraryEntry ? { cliEntries: [libraryEntry] } : void 0
+  const cliEntries = typeof libraryEntry === "string" ? [libraryEntry] : libraryEntry ? [...libraryEntry] : [];
+  const sources = await harness.resolveRecipeLibrarySources({
+    ...cliEntries.length > 0 ? { cliEntries } : {},
+    ...recipePath ? { recipePath } : {}
+  });
+  const canonicalRoot = path.resolve(runnerDir, "library");
+  const configuredCanonical = sources.find(
+    (source) => source.name === "metamask"
   );
-  sources.push({ name: "metamask", root: path.join(runnerDir, "library") });
-  return sources;
+  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 {
-    schema_version: 1,
+    $schema: "https://farmslot.io/schemas/recipe-v1.schema.json",
     title: `mm-harness call ${action}`,
     description: `Ad-hoc single-action execution of ${action} via the real engine path (mm-harness call).`,
-    validate: {
-      workflow: {
-        entry: "call",
-        nodes: {
-          call: { action, ...args, next: "done", intent: `Call ${action} in isolation` },
-          done: { action: "end", status: "pass" }
-        }
+    workflow: {
+      entry: "call",
+      nodes: {
+        call: {
+          ...args,
+          action,
+          next: "done",
+          intent: typeof args.intent === "string" ? args.intent : `Complete the requested ${action} operation`
+        },
+        done: { action: "end", status: "pass" }
       }
     }
   };
 }
 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);
+  const validation = await validateRecipeAdapterAware(
+    adapter,
+    recipe,
+    manifest,
+    librarySources
+  );
   if (validation.status === "invalid") return { status: "fail" };
   const scratch = await mkdtemp(path.join(os.tmpdir(), "mm-harness-fixtures-"));
   const recipeFile = path.join(scratch, "set.recipe.json");
   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),
-    stdoutIsMachineContract: true
-  });
+  const result = await runRecipe(
+    adapter,
+    recipeFile,
+    path.join(scratch, "artifacts"),
+    target,
+    actionManifest,
+    {
+      librarySources,
+      stdoutIsMachineContract: true
+    }
+  );
   return { status: result.status === "pass" ? "pass" : "fail" };
 }
 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 +742,43 @@ async function prepareHeal(adapter, target, options, json, prepareOptions = {})
     return EXIT.usage;
   }
   const state = newHealState();
-  const ensured = await ensureOverlay(adapter, target, heal, state, json);
+  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 +791,15 @@ 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 +808,15 @@ 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,19 +826,45 @@ 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}`;
   if (heal === "off") {
     const message = `Mobile loaded source is not current (${initial.status}).`;
     if (json) {
-      console.log(JSON.stringify({
-        schemaVersion: 1,
-        status: "fail",
-        recoverable: true,
-        mutations: state.mutations,
-        error: { code: "MOBILE_SOURCE_NOT_LOADED", message, userAction }
-      }, null, 2));
+      console.log(
+        JSON.stringify(
+          {
+            schemaVersion: 1,
+            status: "fail",
+            recoverable: true,
+            mutations: state.mutations,
+            error: { code: "MOBILE_SOURCE_NOT_LOADED", message, userAction }
+          },
+          null,
+          2
+        )
+      );
     } else {
       console.error(`\u2717 ${message}`);
       console.error(`  Next: ${userAction}`);
@@ -481,7 +873,11 @@ async function ensureMobileProofRuntime(target, heal, state, json, deps = {}) {
   }
   const recoveryCode = "mobile.source_reloaded";
   state.attemptedRecoveries.push(recoveryCode);
-  if (!json) console.error(`\u2192 Mobile proof preflight: source ${initial.status}; restarting the app before execution`);
+  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(
       "mobile",
@@ -490,7 +886,10 @@ async function ensureMobileProofRuntime(target, heal, state, json, deps = {}) {
       target,
       void 0
     );
-    return { status: result2.status === "pass" ? 0 : EXIT.runtime, output: result2.status };
+    return {
+      status: result2.status === "pass" ? 0 : EXIT.runtime,
+      output: result2.status
+    };
   });
   const result = await restart();
   const platform = resolveRunMobilePlatform();
@@ -504,23 +903,46 @@ async function ensureMobileProofRuntime(target, heal, state, json, deps = {}) {
   if (result.status !== 0 || bridge.status !== 0 || !recorded || verified.status !== "current") {
     const message = bridge.status !== 0 ? "Mobile source restart completed but the platform-matched bridge did not become ready." : "Mobile source restart did not produce a current loaded-source baseline.";
     if (json) {
-      console.log(JSON.stringify({
-        schemaVersion: 1,
-        status: "fail",
-        recoverable: false,
-        attemptedRecoveries: state.attemptedRecoveries,
-        error: { code: bridge.status !== 0 ? "MOBILE_BRIDGE_NOT_READY" : "MOBILE_SOURCE_RELOAD_FAILED", message, userAction, originalError: bridge.output || result.output }
-      }, null, 2));
+      console.log(
+        JSON.stringify(
+          {
+            schemaVersion: 1,
+            status: "fail",
+            recoverable: false,
+            attemptedRecoveries: state.attemptedRecoveries,
+            error: {
+              code: bridge.status !== 0 ? "MOBILE_BRIDGE_NOT_READY" : "MOBILE_SOURCE_RELOAD_FAILED",
+              message,
+              userAction,
+              originalError: bridge.output || result.output
+            }
+          },
+          null,
+          2
+        )
+      );
     } else {
       console.error(`\u2717 ${message}`);
-      console.error(`  Next: ${bridge.status !== 0 ? "inspect the bridge-status log and rerun mm-harness launch <platform>" : userAction}`);
+      console.error(
+        `  Next: ${bridge.status !== 0 ? "inspect the bridge-status log and rerun mm-harness launch <platform>" : userAction}`
+      );
     }
     return EXIT.infra;
   }
   state.recovered.push(recoveryCode);
-  state.mutations.push({ type: "runtime", action: "restarted", reasonCode: `source-${initial.status}` });
+  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,7 +954,38 @@ async function ensureExtensionProofRuntime(target, heal, state, json, deps = {})
   });
   const initial = await decide();
   if (initial.decision === "ready") return null;
-  if (!["dist-stale", "dist-missing", "runtime-dist-stale", "runtime-dist-missing"].includes(initial.reasonCode)) {
+  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;
   }
   const tier = initial.decision === "build" ? "build" : "quick";
@@ -542,13 +995,23 @@ async function ensureExtensionProofRuntime(target, heal, state, json, deps = {})
   if (!canHeal) {
     const message = `Extension proof runtime is not current (${initial.reasonCode}): ${initial.reasons[0] ?? initial.decision}`;
     if (json) {
-      console.log(JSON.stringify({
-        schemaVersion: 1,
-        status: "fail",
-        recoverable: true,
-        mutations: state.mutations,
-        error: { code: "EXTENSION_RUNTIME_NOT_CURRENT", message, userAction }
-      }, null, 2));
+      console.log(
+        JSON.stringify(
+          {
+            schemaVersion: 1,
+            status: "fail",
+            recoverable: true,
+            mutations: state.mutations,
+            error: {
+              code: "EXTENSION_RUNTIME_NOT_CURRENT",
+              message,
+              userAction
+            }
+          },
+          null,
+          2
+        )
+      );
     } else {
       console.error(`\u2717 ${message}`);
       console.error(`  Next: ${userAction}`);
@@ -556,30 +1019,67 @@ 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);
-  if (!json) console.error(`\u2192 Extension proof preflight: ${initial.reasonCode}; ${tier === "build" ? "rebuilding" : "reloading"} before execution`);
+  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) {
-      console.log(JSON.stringify({
-        schemaVersion: 1,
-        status: "fail",
-        recoverable: false,
-        attemptedRecoveries: state.attemptedRecoveries,
-        error: { code: "EXTENSION_RUNTIME_RECOVERY_FAILED", message, userAction, originalError: result.output }
-      }, null, 2));
+      console.log(
+        JSON.stringify(
+          {
+            schemaVersion: 1,
+            status: "fail",
+            recoverable: false,
+            attemptedRecoveries: state.attemptedRecoveries,
+            error: {
+              code: "EXTENSION_RUNTIME_RECOVERY_FAILED",
+              message,
+              userAction,
+              originalError: result.output
+            }
+          },
+          null,
+          2
+        )
+      );
     } else {
       console.error(`\u2717 ${message}`);
       console.error(`  Next: ${userAction}`);
@@ -587,7 +1087,11 @@ async function ensureExtensionProofRuntime(target, heal, state, json, deps = {})
     return EXIT.infra;
   }
   state.recovered.push(recoveryCode);
-  state.mutations.push({ type: "runtime", action: tier === "build" ? "rebuilt" : "reloaded", reasonCode: initial.reasonCode });
+  state.mutations.push({
+    type: "runtime",
+    action: tier === "build" ? "rebuilt" : "reloaded",
+    reasonCode: initial.reasonCode
+  });
   return null;
 }
 const RUN_RECOVERY_CODE = {
@@ -603,35 +1107,36 @@ 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"));
     const entries = Array.isArray(trace.entries) ? trace.entries : [];
-    return entries.filter((entry) => entry && entry.ok === false && typeof entry.error === "string").map((entry) => entry.error).join("\n").trim();
+    return entries.filter(
+      (entry) => entry && entry.ok === false && typeof entry.error === "string"
+    ).map((entry) => entry.error).join("\n").trim();
   } catch {
     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 };
-    const violation = checkHealBounds(target, readRunFailureText(result), state);
+    const violation = checkHealBounds(
+      target,
+      readRunFailureText(result),
+      state
+    );
     if (violation !== null) return { result, violation };
     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 +1146,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 +1166,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
           }
         },
@@ -670,8 +1175,9 @@ function emitHealViolation(json, command, result, violation, state, adapter) {
       )
     );
   } else {
+    const message = violation.code === "APP_LOGIC_FAILURE" && violation.originalError ? conciseFailureForHuman(violation.originalError) : violation.message;
     console.error(
-      `\u2717 mm-harness ${command}: ${violation.message}` + (violation.originalError ? `
+      `\u2717 mm-harness ${command}: ${message}` + (violation.originalError && violation.code !== "APP_LOGIC_FAILURE" ? `
   --- original failure ---
 ${violation.originalError}` : "") + (userAction ? `
   Next: ${userAction}` : "")
@@ -681,17 +1187,19 @@ ${violation.originalError}` : "") + (userAction ? `
 }
 function countRecipeNodes(recipe) {
   if (!isRecord(recipe)) return void 0;
-  const validate = isRecord(recipe.validate) ? recipe.validate : void 0;
-  const workflow = validate && isRecord(validate.workflow) ? validate.workflow : void 0;
+  const workflow = isRecord(recipe.workflow) ? recipe.workflow : void 0;
   const nodes = workflow && isRecord(workflow.nodes) ? workflow.nodes : void 0;
   return nodes ? Object.keys(nodes).length : void 0;
 }
 export {
   countRecipeNodes,
+  describeRunnableRecipe,
   emitHealViolation,
   ensureExtensionProofRuntime,
   ensureMobileProofRuntime,
   executeWithHealBounds,
+  listRunnableRecipes,
+  preflightRecipe,
   prepareHeal,
   recoverRunInfra,
   resolveMetaMaskLibrarySources,