@deeeed/metamask-harness 0.16.0 → 0.17.1

package/dist/commands/logs.js

@@ -19,9 +19,10 @@ async function handleLogs(argv) {
   const logSources = surface.logSources(target);
   const appLogSource = surface.appLogSource(target);
   const sourceLabels = logSources.map((entry) => entry.label);
-  const defaultSource = sourceLabels[0];
+  const appSourceLabel = appLogSource?.label ?? "app";
+  const defaultSource = appLogSource && appSourceLabel !== "app" ? appSourceLabel : sourceLabels[0];
   const source = str(options, "source") ?? defaultSource;
-  const validSources = [...sourceLabels, ...appLogSource ? ["app"] : []];
+  const validSources = [...sourceLabels, ...appLogSource ? [appSourceLabel] : [], ...appLogSource && appSourceLabel !== "app" ? ["app"] : []];
   if (!validSources.includes(source)) {
     return usageOut(json, "logs", `--source must be one of: ${validSources.join(", ")}.`, `mm-harness logs --source ${defaultSource}`);
   }
@@ -32,11 +33,12 @@ async function handleLogs(argv) {
     }
     process.env.RECIPE_LOG_EVENTS = events;
   }
-  const requested = source === "app" ? appLogSource : logSources.find((entry) => entry.label === source);
-  const ordered = source === "app" ? requested ? [requested] : [] : requested ? [requested, ...logSources.filter((entry) => entry !== requested)] : logSources;
+  const isAppSource = source === "app" || source === appSourceLabel;
+  const requested = isAppSource ? appLogSource : logSources.find((entry) => entry.label === source);
+  const ordered = isAppSource ? requested ? [requested] : [] : requested ? [requested] : logSources;
   const logFile = ordered.find((entry) => fs.existsSync(entry.path))?.path;
   if (!logFile) {
-    if (source === "app" && appLogSource) {
+    if (isAppSource && appLogSource) {
       const message = `application console unavailable for this checkout (${path.basename(appLogSource.path)} is absent).`;
       const userAction = surface.hints.launch;
       if (json) {
@@ -55,7 +57,7 @@ async function handleLogs(argv) {
       }
       return EXIT.runtime;
     }
-    const names = source === "app" && appLogSource ? path.basename(appLogSource.path) : logSources.map((entry) => path.basename(entry.path)).join(" / ");
+    const names = isAppSource && appLogSource ? path.basename(appLogSource.path) : logSources.map((entry) => path.basename(entry.path)).join(" / ");
     return usageOut(
       json,
       "logs",

package/dist/commands/manifest.js

@@ -1,37 +1,29 @@
 import { loadActionManifest, validateManifest } from "../manifest.js";
 import { EXIT } from "./shared.js";
-import {
-  actionManifestPathOption,
-  isRecord,
-  optionFlag,
-  optionString,
-  resolveAdapter
-} from "./parse-args.js";
-async function handleManifest({ options }) {
-  const { adapter } = resolveAdapter(options);
-  const actionManifestPath = actionManifestPathOption(options, adapter);
-  const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
-  await validateManifest(manifest);
-  if (optionFlag(options, "json")) console.log(JSON.stringify(manifest, null, 2));
-  else console.log(actionManifestPath);
-  return 0;
-}
-async function handleActions({ options }) {
+import { isRecord, optionFlag, optionString, resolveAdapter } from "./parse-args.js";
+async function handleActions({ options, positional }) {
   const { adapter } = resolveAdapter(options);
   const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
   await validateManifest(manifest);
+  if (optionFlag(options, "raw")) {
+    console.log(JSON.stringify(manifest, null, 2));
+    return EXIT.ok;
+  }
   const json = optionFlag(options, "json");
   const action = optionString(options, "action");
+  const query = positional[0]?.trim();
   const category = optionString(options, "category")?.toLowerCase();
   const categoriesOnly = optionFlag(options, "categories");
   const all = describeManifestActions(manifest);
   const categories = summarizeActionCategories(all);
   if (categoriesOnly && (action || category)) {
     const message = "--categories cannot be combined with --action or --category.";
+    const userAction = `mm-harness actions --adapter ${adapter} --categories`;
     if (json) {
-      console.log(JSON.stringify({ schemaVersion: 1, command: "actions", adapter, error: { code: "ACTION_FILTER_CONFLICT", message } }, null, 2));
+      console.log(JSON.stringify({ schemaVersion: 1, command: "actions", adapter, error: { code: "ACTION_FILTER_CONFLICT", message, userAction } }, null, 2));
     } else {
-      console.error(`\u2717 mm-harness actions: ${message}`);
+      console.error(`\u2717 mm-harness actions: ${message}
+  Next: ${userAction}`);
     }
     return EXIT.usage;
   }
@@ -52,10 +44,10 @@ async function handleActions({ options }) {
     }
     return EXIT.usage;
   }
-  const actions = action ? fuzzyResolveActions(categoryActions, action) : categoryActions;
+  const actions = action ? fuzzyResolveActions(categoryActions, action) : query ? searchActions(categoryActions, query) : categoryActions;
   if (action && actions.length === 0) {
     const message = `no action matches "${action}" for the ${adapter} adapter.`;
-    const userAction = `mm-harness actions --adapter ${adapter}   # list the vocabulary`;
+    const userAction = `mm-harness actions --adapter ${adapter}`;
     if (json) {
       console.log(JSON.stringify({ schemaVersion: 1, command: "actions", adapter, action, category, error: { code: "ACTION_UNKNOWN", message, userAction } }, null, 2));
     } else {
@@ -64,24 +56,70 @@ async function handleActions({ options }) {
     }
     return EXIT.usage;
   }
+  if (query && actions.length === 0) {
+    const message = `no action matches search "${query}" for the ${adapter} adapter.`;
+    const userAction = `mm-harness actions --adapter ${adapter} --categories`;
+    if (json) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        command: "actions",
+        adapter,
+        query,
+        category,
+        error: { code: "ACTION_SEARCH_EMPTY", message, userAction }
+      }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness actions: ${message}
+  Next: ${userAction}`);
+    }
+    return EXIT.usage;
+  }
+  const relatedActions = action && actions.length === 1 ? findRelatedActions(all, actions[0]) : void 0;
   if (json) {
-    console.log(JSON.stringify({ schemaVersion: 1, command: "actions", adapter, category, actions }, null, 2));
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      command: "actions",
+      adapter,
+      ...query ? { query } : {},
+      category,
+      actions,
+      ...relatedActions ? { relatedActions } : {}
+    }, null, 2));
   } else {
     for (const entry of actions) {
       const fields = entry.fields.length ? ` fields=${entry.fields.join(",")}` : "";
       console.log(`${entry.name} (${entry.kind})${fields}${entry.description ? ` \u2014 ${entry.description}` : ""}`);
     }
+    if (relatedActions) console.log(`Related: ${relatedActions.join(", ")}`);
   }
   return 0;
 }
 function fuzzyResolveActions(entries, query) {
   const exactFull = entries.filter((e) => e.name === query);
   if (exactFull.length > 0) return exactFull;
-  const finalSegment = (name) => name.split(".").pop() ?? name;
-  const exactSegment = entries.filter((e) => finalSegment(e.name) === query);
+  const finalSegment2 = (name) => name.split(".").pop() ?? name;
+  const exactSegment = entries.filter((e) => finalSegment2(e.name) === query);
   if (exactSegment.length > 0) return exactSegment;
-  return entries.filter((e) => finalSegment(e.name).includes(query));
+  return entries.filter((e) => finalSegment2(e.name).includes(query));
 }
+function searchActions(entries, query) {
+  const terms = searchTerms(query);
+  if (terms.length === 0) return [];
+  return entries.map((entry) => {
+    const scores = terms.map((term) => actionSearchScore(entry, term));
+    return { entry, scores, score: scores.reduce((total, value) => total + value, 0) };
+  }).filter(({ score, scores }) => score > 0 && scores.every((value) => value > 0)).sort((left, right) => right.score - left.score || left.entry.name.localeCompare(right.entry.name)).map(({ entry }) => entry);
+}
+function findRelatedActions(entries, selected, limit = 5) {
+  const selectedNameTerms = searchTerms(finalSegment(selected.name).replaceAll("_", " "));
+  return entries.filter((entry) => entry.name !== selected.name).map((entry) => {
+    const nameTerms = new Set(searchTerms(finalSegment(entry.name).replaceAll("_", " ")));
+    const sharedScore = selectedNameTerms.filter((term) => nameTerms.has(term)).reduce((score2, term) => score2 + (GENERIC_OPERATION_TERMS.has(term) ? 5 : 30), 0);
+    const score = (entry.category === selected.category ? 100 : 0) + sharedScore;
+    return { name: entry.name, score };
+  }).filter(({ score }) => score > 0).sort((left, right) => right.score - left.score || left.name.localeCompare(right.name)).slice(0, limit).map(({ name }) => name);
+}
+const GENERIC_OPERATION_TERMS = /* @__PURE__ */ new Set(["assert", "call", "close", "ensure", "place", "read", "start", "teardown"]);
 function summarizeActionCategories(actions) {
   const counts = /* @__PURE__ */ new Map();
   for (const action of actions) counts.set(action.category, (counts.get(action.category) ?? 0) + 1);
@@ -114,22 +152,69 @@ function describeManifestAction(name, kind, metadata) {
   return {
     name,
     kind,
-    category: actionCategory(name),
+    category: actionCategory(name, record.category),
     description: typeof record.description === "string" ? record.description : "",
     fields: properties,
     schema,
     examples: record.examples
   };
 }
-function actionCategory(name) {
+function actionCategory(name, configured) {
+  if (typeof configured === "string" && configured.trim()) return configured.trim().toLowerCase();
   const segments = name.split(".");
   if (segments[0] === "metamask" && segments.length > 2) return segments[1] ?? "metamask";
-  return segments[0] || "other";
+  if (segments[0] === "app" || segments[0] === "cdp") return "runtime";
+  if (segments[0] === "ui") return "ui";
+  if (name.startsWith("assert_")) return "assertion";
+  if (name === "watch_logs" || name === "index_artifacts") return "evidence";
+  if (name === "command" || name === "wait" || name === "call" || name === "end") return "control";
+  return segments.length > 1 ? segments[0] || "utility" : "utility";
+}
+function actionSearchScore(entry, term) {
+  const name = entry.name.toLowerCase();
+  const segment = finalSegment(name);
+  const nameTerms = searchTerms(name.replaceAll(".", " ").replaceAll("_", " "));
+  const fields = entry.fields.map((field) => field.toLowerCase());
+  const description = entry.description.toLowerCase();
+  if (name === term) return 120;
+  if (segment === term) return 110;
+  if (entry.category === term) return 100;
+  if (fields.includes(term)) return 90;
+  if (nameTerms.includes(term)) return 80;
+  if (name.includes(term)) return 70;
+  if (fields.some((field) => field.includes(term))) return 60;
+  if (description.includes(term)) return 50;
+  if ([...nameTerms, ...fields].some((candidate) => fuzzyTermMatch(term, candidate))) return 40;
+  return 0;
+}
+function fuzzyTermMatch(term, candidate) {
+  if (term.length < 4 || candidate.length < 4) return false;
+  const threshold = Math.max(1, Math.floor(Math.max(term.length, candidate.length) / 4));
+  return levenshtein(term, candidate) <= threshold;
+}
+function searchTerms(value) {
+  return value.toLowerCase().match(/[a-z0-9]+/gu) ?? [];
+}
+function finalSegment(name) {
+  return name.split(".").pop() ?? name;
+}
+function levenshtein(left, right) {
+  const prior = Array.from({ length: right.length + 1 }, (_, index) => index);
+  for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+    const current = [leftIndex];
+    for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+      const substitution = (prior[rightIndex - 1] ?? 0) + (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1);
+      current[rightIndex] = Math.min((current[rightIndex - 1] ?? 0) + 1, (prior[rightIndex] ?? 0) + 1, substitution);
+    }
+    for (let index = 0; index < current.length; index += 1) prior[index] = current[index] ?? 0;
+  }
+  return prior[right.length] ?? right.length;
 }
 export {
   describeManifestActions,
+  findRelatedActions,
   fuzzyResolveActions,
   handleActions,
-  handleManifest,
+  searchActions,
   summarizeActionCategories
 };

package/dist/commands/parse-args.js

@@ -19,6 +19,7 @@ function parseArgs(argv, command) {
   const options = {};
   const booleanOptions = /* @__PURE__ */ new Set([
     "json",
+    "jsonStream",
     "launchExistingDist",
     "startWatch",
     "record",

package/dist/commands/provision.js

@@ -1,7 +1,7 @@
 import { detectAdapter } from "../harness.js";
 import { assertAdapter } from "../paths.js";
 import { getAdapterSurface } from "../adapters/surface.js";
-import { ADAPTER_DETECT_NEXT, usageOut } from "./shared.js";
+import { ADAPTER_DETECT_NEXT, usageOut, writeInteractiveProgress } from "./shared.js";
 import {
   applyWatcherPortOption,
   optionFlag,
@@ -25,9 +25,13 @@ async function handleProvision({ positional, options, rawArgv }) {
   }
   const surface = getAdapterSurface(adapter);
   const rerunCommand = provisionRerunCommand(rawArgv, options, adapter, target);
+  const platform = optionString(options, "platform") ?? optionString(options, "devicePlatform") ?? (positional[0] === "runway" ? positional[1] : positional[0]) ?? "ios";
+  if (adapter === "mobile") {
+    writeInteractiveProgress(json, `\u2192 provision mobile ${platform} \u2014 resolving simulator and Runway artifact`);
+  }
   const result = await surface.runwayProvision.run(target, {
     json,
-    platform: optionString(options, "platform") ?? optionString(options, "devicePlatform") ?? (positional[0] === "runway" ? positional[1] : positional[0]) ?? "ios",
+    platform,
     branch: optionString(options, "branch"),
     defaultBranch: optionString(options, "defaultBranch"),
     run: optionString(options, "run"),
@@ -42,8 +46,10 @@ async function handleProvision({ positional, options, rawArgv }) {
     resolveOnly: optionFlag(options, "resolveOnly"),
     rerunCommand
   });
+  const next = result.status === "pass" && adapter === "mobile" && result.resolveOnly !== true ? `mm-harness launch ${String(result.platform ?? platform)} --adapter mobile --target ${shellQuote(target)}` : void 0;
+  const output = next ? { ...result, next } : result;
   if (json) {
-    console.log(JSON.stringify(result, null, 2));
+    console.log(JSON.stringify(output, null, 2));
   } else if (result.status === "pass") {
     const cache = typeof result.cache === "object" && result.cache ? result.cache : void 0;
     const simulator = typeof result.simulator === "object" && result.simulator ? result.simulator : void 0;
@@ -54,6 +60,7 @@ async function handleProvision({ positional, options, rawArgv }) {
       const action = result.skipped ? "already provisioned" : "provisioned";
       console.error(`\u2713 ${action} ${adapter} ${result.platform ?? ""} simulator=${simulator?.name ?? "unknown"} cache=${cache?.status ?? "unknown"}`);
     }
+    if (next) console.error(`  Next: ${next}`);
   } else {
     console.error(`\u2717 mm-harness provision: ${result.error?.message ?? "provision failed"}
   Next: ${result.error?.userAction ?? rerunCommand}`);

package/dist/commands/run-engine.js

@@ -31,6 +31,7 @@ import {
   optionString,
   isRecord,
   shellQuoteArg,
+  targetPath,
   usageError
 } from "./parse-args.js";
 async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManifestPath, runtimeOptions = {}) {
@@ -66,7 +67,8 @@ async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManif
       await validateManifest(manifest);
       const { createMetaMaskRunner } = await import("../runner.js");
       const runner = await createMetaMaskRunner(adapter, manifest, {
-        quietStdout: runtimeOptions.stdoutIsMachineContract === true
+        quietStdout: runtimeOptions.stdoutIsMachineContract === true,
+        onActionEvent: runtimeOptions.onActionEvent
       });
       const runRequest = {
         recipePath: path.resolve(recipe),
@@ -198,12 +200,7 @@ function libraryRecipeNames(adapter) {
   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")) {
@@ -229,32 +226,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);
@@ -348,6 +319,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(" ")}.`;
@@ -405,10 +377,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;
   }
@@ -421,21 +395,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;
@@ -448,7 +426,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);
@@ -457,7 +437,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 };
@@ -502,6 +484,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(
@@ -588,6 +571,7 @@ async function ensureExtensionProofRuntime(target, heal, state, json, deps = {})
   }
   const recoveryCode = tier === "build" ? "extension.runtime_rebuilt" : "extension.runtime_reloaded";
   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");
@@ -642,7 +626,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 };
@@ -651,6 +635,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") {
@@ -660,7 +645,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" ? 'set MM_TEST_ACCOUNT_ADDRESS=<0x\u2026> in env, 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(
@@ -680,7 +665,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
           }
         },

package/dist/commands/run-report.js

@@ -34,7 +34,7 @@ function renderRunReport(summary, entries) {
     lines.push(
       "",
       "## Side findings",
-      `- REVIEW ${sideFindingTotal} distinct application warning/error event(s); see diagnostics.json (non-blocking)`
+      `- REVIEW ${sideFindingTotal} distinct application warning/error event(s) (non-blocking; expanded below and stored in diagnostics.json)`
     );
   }
   lines.push("", "## Steps");