@deeeed/metamask-harness 0.14.7 → 0.15.0

package/dist/commands/launch/index.js

@@ -7,6 +7,7 @@ import { recipeRuntimePath, runnerDir } from "../../paths.js";
 import { getAdapterSurface } from "../../adapters/surface.js";
 import {
   ADAPTER_DETECT_NEXT,
+  checkoutBusyOut,
   EXIT,
   flag,
   parseFlags,
@@ -23,9 +24,15 @@ import {
   newHealState,
   parseHeal
 } from "../../heal-bounds.js";
-import { extensionDepsBlock, extensionRuntimeReusable, launchExtension } from "./extension.js";
+import {
+  extensionDepsBlock,
+  extensionRuntimeReusable,
+  installExtensionDeps,
+  launchExtension
+} from "./extension.js";
 import { launchMobile } from "./mobile.js";
 import { applyDeviceTargeting } from "../device-target.js";
+import { acquireCheckoutLock } from "../../checkout-lock.js";
 const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
   "build",
   "watch",
@@ -37,6 +44,21 @@ const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
 ]);
 const DEFAULT_EXTENSION_DAPP_URL = "https://metamask.github.io/test-dapp/";
 async function handleLaunch(argv) {
+  const { options } = parseFlags(argv, LAUNCH_BOOLEANS);
+  const json = flag(options, "json");
+  const target = targetOf(options);
+  if (!fs.existsSync(target)) return handleLaunchLocked(argv);
+  const lock = acquireCheckoutLock(target, "launch");
+  if ("message" in lock) {
+    return checkoutBusyOut(json, "launch", lock.message, lock.path);
+  }
+  try {
+    return await handleLaunchLocked(argv);
+  } finally {
+    lock.release();
+  }
+}
+async function handleLaunchLocked(argv) {
   const { positional, options } = parseFlags(argv, LAUNCH_BOOLEANS);
   const json = flag(options, "json");
   const target = targetOf(options);
@@ -86,14 +108,14 @@ async function handleLaunch(argv) {
   if (envResult && "code" in envResult) {
     return usageOut(json, "launch", envResult.message, "mm-harness launch android --device <adb-serial|device-name>");
   }
-  const tier = wantVerify ? "verify" : wantBuild ? "build" : "quick";
+  const tier = wantBuild ? "build" : "quick";
   if (adapter === "extension") {
     const requestedUrl = typeof options["url"] === "string" && options["url"] ? options["url"] : "";
     if (requestedUrl || displayMode === "sidepanel") {
       process.env.EXTENSION_START_URL = requestedUrl || DEFAULT_EXTENSION_DAPP_URL;
     }
   }
-  if (!json && adapter === "extension" && tier !== "verify") {
+  if (!json && adapter === "extension") {
     const modeNote = displayMode === "sidepanel" ? `sidepanel \xB7 dapp ${process.env.EXTENSION_START_URL ?? DEFAULT_EXTENSION_DAPP_URL}` : "fullscreen";
     const workNote = wantWatch ? "watch only" : tier === "build" ? "clean build" : "quick reuse probe";
     console.error(
@@ -118,32 +140,35 @@ async function handleLaunch(argv) {
       exitCode: EXIT.infra
     });
   }
-  if (tier === "verify") {
-    const verifyCdpPort = Number(process.env.CDP_PORT ?? "");
-    if (adapter === "extension" && Number.isInteger(verifyCdpPort) && verifyCdpPort > 0) {
-      const { ensureExtensionReady } = await import("../../adapters/extension/ensure-ready.js");
-      const convergence = await ensureExtensionReady(target, { cdpPort: verifyCdpPort });
-      console.error(
-        `[launch] home-tab convergence: ${convergence.action} (${convergence.homeTabs.before}\u2192${convergence.homeTabs.after} tabs, closed ${convergence.homeTabs.closed})${convergence.ready ? "" : ` \u2014 ${convergence.reasonCode}`}`
-      );
-    }
-    const liveArgs = ["live", "--adapter", adapter, "--target", target];
-    if (adapter === "mobile" && mobileTarget) liveArgs.push("--platform", mobileTarget);
-    if (json) liveArgs.push("--json");
-    return handleHarness(liveArgs);
-  }
   if (adapter === "extension") {
     const willBuild = wantWatch || tier === "build" || !await extensionRuntimeReusable(target);
     if (willBuild) {
       const depsBlock = extensionDepsBlock(target);
       if (depsBlock) {
-        return usageOut(json, "launch", depsBlock.message, depsBlock.userAction);
+        if (heal === "off") {
+          return usageOut(json, "launch", depsBlock.message, depsBlock.userAction);
+        }
+        const recoveryCode2 = "deps.installed";
+        state.attemptedRecoveries.push(recoveryCode2);
+        const repaired = await installExtensionDeps(target);
+        if (repaired.status !== 0 || extensionDepsBlock(target)) {
+          return launchFail(json, adapter, mobileTarget, tier, state, {
+            code: "DEPENDENCY_INSTALL_FAILED",
+            message: depsBlock.message,
+            recoverable: false,
+            userAction: "install the checkout-pinned Node version, then re-run mm-harness launch",
+            originalError: repaired.output,
+            exitCode: EXIT.infra
+          });
+        }
+        state.recovered.push(recoveryCode2);
+        state.mutations.push({ type: "dependencies", action: "installed", path: target });
       }
     }
   }
   let attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, json, displayMode);
   if (attempt.status === 0) {
-    return await finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch);
+    return await finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
   }
   if (heal === "off") {
     return launchFail(json, adapter, mobileTarget, tier, state, {
@@ -159,7 +184,7 @@ async function handleLaunch(argv) {
     const rebuildAttempt = await executeComposition(adapter, mobileTarget, "build", wantWatch, target, json, displayMode);
     if (rebuildAttempt.status === 0) {
       state.recovered.push(recoveryCode2);
-      return await finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch);
+      return await finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
     }
     return launchFail(json, adapter, mobileTarget, tier, state, {
       code: "EXTENSION_RELAUNCH_FAILED",
@@ -195,7 +220,7 @@ async function handleLaunch(argv) {
   attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, json, displayMode);
   if (attempt.status === 0) {
     state.recovered.push(recoveryCode);
-    return await finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch);
+    return await finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
   }
   return launchFail(json, adapter, mobileTarget, tier, state, {
     code: "SAME_RECOVERY_TWICE",
@@ -303,7 +328,7 @@ async function executeComposition(adapter, mobileTarget, tier, wantWatch, target
   }
   return launchExtension(target, tier, wantWatch, displayMode);
 }
-async function finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, sidepanelRecoveryAllowed = true) {
+async function finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, sidepanelRecoveryAllowed = true) {
   if (adapter === "extension" && displayMode === "sidepanel") {
     const sidepanelSh = path.join(runnerDir, "adapters/extension/sidepanel-toggle.sh");
     const sidepanelArgs = ["open"];
@@ -330,6 +355,7 @@ async function finishLaunch(json, adapter, mobileTarget, tier, displayMode, targ
             target,
             state,
             wantWatch,
+            wantVerify,
             false
           );
         }
@@ -351,6 +377,12 @@ async function finishLaunch(json, adapter, mobileTarget, tier, displayMode, targ
       });
     }
   }
+  if (wantVerify) {
+    const verifyArgs = ["verify", "--adapter", adapter, "--target", target];
+    if (adapter === "mobile" && mobileTarget) verifyArgs.push("--platform", mobileTarget);
+    if (json) verifyArgs.push("--json");
+    return handleHarness(verifyArgs);
+  }
   return launchPass(json, adapter, mobileTarget, tier, displayMode, state);
 }
 function launchPass(json, adapter, mobileTarget, tier, displayMode, state) {

package/dist/commands/logs.js

@@ -17,10 +17,11 @@ async function handleLogs(argv) {
     return usageOut(json, "logs", "core is headless; it has no dev server logs.", surface.hints.launch);
   }
   const logSources = surface.logSources(target);
+  const appLogSource = surface.appLogSource(target);
   const sourceLabels = logSources.map((entry) => entry.label);
   const defaultSource = sourceLabels[0];
   const source = str(options, "source") ?? defaultSource;
-  const validSources = [...sourceLabels, "app"];
+  const validSources = [...sourceLabels, ...appLogSource ? ["app"] : []];
   if (!validSources.includes(source)) {
     return usageOut(json, "logs", `--source must be one of: ${validSources.join(", ")}.`, `mm-harness logs --source ${defaultSource}`);
   }
@@ -31,11 +32,30 @@ async function handleLogs(argv) {
     }
     process.env.RECIPE_LOG_EVENTS = events;
   }
-  const requested = logSources.find((entry) => entry.label === source);
-  const ordered = requested ? [requested, ...logSources.filter((entry) => entry !== requested)] : logSources;
+  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 logFile = ordered.find((entry) => fs.existsSync(entry.path))?.path;
   if (!logFile) {
-    const names = logSources.map((entry) => path.basename(entry.path)).join(" / ");
+    if (source === "app" && appLogSource) {
+      const message = `application console unavailable for this checkout (${path.basename(appLogSource.path)} is absent).`;
+      const userAction = surface.hints.launch;
+      if (json) {
+        console.log(JSON.stringify({
+          schemaVersion: 1,
+          command: "logs",
+          adapter,
+          source,
+          status: "fail",
+          error: { code: "APP_LOG_UNAVAILABLE", message, userAction },
+          exitCode: EXIT.runtime
+        }, null, 2));
+      } else {
+        console.error(`\u2717 logs: ${message}`);
+        console.error(`  Next: ${userAction}`);
+      }
+      return EXIT.runtime;
+    }
+    const names = source === "app" && appLogSource ? path.basename(appLogSource.path) : logSources.map((entry) => path.basename(entry.path)).join(" / ");
     return usageOut(
       json,
       "logs",

package/dist/commands/run-engine.js

@@ -298,6 +298,27 @@ async function validateRunRecipeStatic(recipeArg, adapter, options) {
   }
   const validation = manifestOk ? await validateRecipeAdapterAware(recipe, manifest, librarySources) : { status: "invalid", findings: [], summary: { errors: 1, warnings: 0 } };
   findings.push(...validation.findings);
+  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 errorCount = findings.filter((finding) => finding.severity === "error").length;
   return {
     recipe,
@@ -305,7 +326,7 @@ async function validateRunRecipeStatic(recipeArg, adapter, options) {
     findings,
     errorCount,
     manifestOk,
-    schemaValid: validation.status === "valid",
+    schemaValid: validation.status === "valid" && errorCount === 0,
     ...librarySources ? { librarySources } : {}
   };
 }
@@ -369,11 +390,12 @@ 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: await resolveMetaMaskLibrarySources(void 0),
+    stdoutIsMachineContract: true
   });
   return { status: result.status === "pass" ? "pass" : "fail" };
 }
-async function prepareHeal(adapter, target, options, json) {
+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.";
     if (json) {
@@ -407,13 +429,203 @@ async function prepareHeal(adapter, target, options, json) {
     }
     return EXIT.infra;
   }
+  if (adapter === "extension") {
+    const previousCdpPort = process.env.CDP_PORT;
+    const previousRecipeCdpPort = process.env.RECIPE_CDP_PORT;
+    const previousWatcherPort = process.env.WATCHER_PORT;
+    const explicitCdpPort = optionString(options, "cdpPort");
+    const explicitWatcherPort = optionString(options, "watcherPort") ?? optionString(options, "metroPort");
+    if (explicitCdpPort) {
+      process.env.CDP_PORT = explicitCdpPort;
+      process.env.RECIPE_CDP_PORT = explicitCdpPort;
+    }
+    if (explicitWatcherPort) process.env.WATCHER_PORT = explicitWatcherPort;
+    try {
+      const current = await ensureExtensionProofRuntime(target, heal, state, json);
+      if (current !== null) return current;
+    } finally {
+      restoreEnv("CDP_PORT", previousCdpPort);
+      restoreEnv("RECIPE_CDP_PORT", previousRecipeCdpPort);
+      restoreEnv("WATCHER_PORT", previousWatcherPort);
+    }
+  }
+  if (adapter === "mobile" && prepareOptions.skipMobileSourceFreshness !== true) {
+    const current = await ensureMobileProofRuntime(target, heal, state, json);
+    if (current !== null) return current;
+  }
   return { state, heal };
 }
+async function ensureMobileProofRuntime(target, heal, state, json, deps = {}) {
+  const source = await import("../adapters/mobile/source-freshness.js");
+  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));
+    } else {
+      console.error(`\u2717 ${message}`);
+      console.error(`  Next: ${userAction}`);
+    }
+    return EXIT.infra;
+  }
+  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`);
+  const restart = deps.restart ?? (async () => {
+    const result2 = await runOneNode(
+      "mobile",
+      "app.lifecycle",
+      { command: "restart" },
+      target,
+      void 0
+    );
+    return { status: result2.status === "pass" ? 0 : EXIT.runtime, output: result2.status };
+  });
+  const result = await restart();
+  const recorded = result.status === 0 && record(initial.fingerprint);
+  const verified = recorded ? check() : initial;
+  if (result.status !== 0 || !recorded || verified.status !== "current") {
+    const message = "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: "MOBILE_SOURCE_RELOAD_FAILED", message, userAction, originalError: result.output }
+      }, null, 2));
+    } else {
+      console.error(`\u2717 ${message}`);
+      console.error(`  Next: ${userAction}`);
+    }
+    return EXIT.infra;
+  }
+  state.recovered.push(recoveryCode);
+  state.mutations.push({ type: "runtime", action: "restarted", reasonCode: `source-${initial.status}` });
+  return null;
+}
+async function ensureExtensionProofRuntime(target, heal, state, json, deps = {}) {
+  const decide = deps.decide ?? (async () => {
+    const { decideExtensionReadiness } = await import("../adapters/extension/runtime-decision.js");
+    const port = Number(process.env.CDP_PORT);
+    return decideExtensionReadiness(target, {
+      ...Number.isInteger(port) && port > 0 ? { cdpPort: port } : {},
+      pageMode: "home-or-sidepanel"
+    });
+  });
+  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;
+  }
+  const tier = initial.decision === "build" ? "build" : "quick";
+  const canHeal = heal === "auto" || heal === "infra-only" && tier === "quick";
+  const targetArg = JSON.stringify(path.resolve(target));
+  const userAction = tier === "build" ? `mm-harness launch --build --verify --adapter extension --target ${targetArg}` : `mm-harness launch --verify --adapter extension --target ${targetArg}`;
+  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));
+    } else {
+      console.error(`\u2717 ${message}`);
+      console.error(`  Next: ${userAction}`);
+    }
+    return EXIT.infra;
+  }
+  const recoveryCode = tier === "build" ? "extension.runtime_rebuilt" : "extension.runtime_reloaded";
+  state.attemptedRecoveries.push(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);
+  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));
+    } else {
+      console.error(`\u2717 ${message}`);
+      console.error(`  Next: ${userAction}`);
+    }
+    return EXIT.infra;
+  }
+  state.recovered.push(recoveryCode);
+  state.mutations.push({ type: "runtime", action: tier === "build" ? "rebuilt" : "reloaded", reasonCode: initial.reasonCode });
+  return null;
+}
 const RUN_RECOVERY_CODE = {
-  mobile: "metro.restarted",
-  extension: "chrome.reopened",
-  core: "runtime.reset"
+  mobile: "mobile.runtime_recovered",
+  extension: "extension.runtime_recovered",
+  core: "run.retried"
 };
+async function recoverRunInfra(adapter, target, json) {
+  getAdapterSurface(adapter).resolveSlotPorts(target);
+  if (adapter === "extension") {
+    const { launchExtension } = await import("./launch/extension.js");
+    return launchExtension(target, "quick", false);
+  }
+  if (adapter === "mobile") {
+    const { launchMobile } = await import("./launch/mobile.js");
+    const platform = process.env.PLATFORM === "android" ? "android" : "ios";
+    return launchMobile(target, platform, "quick", json);
+  }
+  return { status: 0, output: "headless run retry" };
+}
 function readRunFailureText(result) {
   try {
     const trace = JSON.parse(fs.readFileSync(result.tracePath, "utf8"));
@@ -423,7 +635,7 @@ function readRunFailureText(result) {
     return "";
   }
 }
-async function executeWithHealBounds(exec, adapter, target, heal, state) {
+async function executeWithHealBounds(exec, adapter, target, heal, state, recover = () => recoverRunInfra(adapter, target, false)) {
   let result = await exec();
   for (; ; ) {
     if (result.status === "pass") return { result, violation: null };
@@ -432,6 +644,7 @@ async function executeWithHealBounds(exec, adapter, target, heal, state) {
     if (heal === "off") return { result, violation: null };
     const recoveryCode = RUN_RECOVERY_CODE[adapter];
     state.attemptedRecoveries.push(recoveryCode);
+    await recover();
     result = await exec();
     if (result.status === "pass") {
       state.recovered.push(recoveryCode);
@@ -488,8 +701,11 @@ function countRecipeNodes(recipe) {
 export {
   countRecipeNodes,
   emitHealViolation,
+  ensureExtensionProofRuntime,
+  ensureMobileProofRuntime,
   executeWithHealBounds,
   prepareHeal,
+  recoverRunInfra,
   resolveMetaMaskLibrarySources,
   resolveRunRecipeArg,
   runOneNode,

package/dist/commands/run.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { walletFixturePath } from "../paths.js";
 import { color } from "../cli-color.js";
 import { recipeRunning } from "../heal-bounds.js";
-import { EXIT } from "./shared.js";
+import { checkoutBusyOut, EXIT, usageOut } from "./shared.js";
 import {
   optionFlag,
   optionString,
@@ -18,6 +18,7 @@ import {
   emitHealViolation,
   executeWithHealBounds,
   prepareHeal,
+  recoverRunInfra,
   runRecipe,
   validateRunRecipeStatic
 } from "./run-engine.js";
@@ -26,6 +27,7 @@ import { applyDeviceTargeting } from "./device-target.js";
 import { getAdapterSurface } from "../adapters/surface.js";
 import { coreDependencyBlock } from "./core-readiness.js";
 import { writeRunReport } from "./run-report.js";
+import { acquireCheckoutLock } from "../checkout-lock.js";
 async function handleRun({ positional, options }) {
   if (optionFlag(options, "list")) return handleListExecutables("run", options);
   const targetRecipe = positional[0];
@@ -33,6 +35,14 @@ async function handleRun({ positional, options }) {
   if (optionFlag(options, "plan")) return handleRunPlan(targetRecipe, options);
   const { adapter, target } = resolveAdapter(options);
   const json = optionFlag(options, "json");
+  if (!fs.existsSync(target)) {
+    return usageOut(
+      json,
+      "run",
+      `target does not exist: ${target}`,
+      "pass --target <metamask-checkout> pointing to an existing checkout"
+    );
+  }
   getAdapterSurface(adapter).resolveSlotPorts(target);
   const dtResult = applyDeviceTargeting("run", adapter, options, { gate: true, rerun: "" });
   if ("code" in dtResult) {
@@ -54,56 +64,63 @@ async function handleRun({ positional, options }) {
     return emitRunUsageError(json, adapter, validated.recipeFile, depsBlock.code, depsBlock.message, depsBlock.userAction);
   }
   const artifactsDir = requiredOption(options, "artifactsDir", "run requires --artifacts-dir <dir>.");
-  const prepared = await prepareHeal(adapter, target, options, json);
-  if (typeof prepared === "number") return prepared;
-  const { state, heal } = prepared;
-  const librarySources = validated.librarySources;
-  const runtimeOptions = {
-    ...runtimeOptionsFromCli(options),
-    ...librarySources ? { librarySources } : {},
-    stdoutIsMachineContract: json
-  };
-  const { result, violation } = await executeWithHealBounds(
-    // validated.recipeFile, not the raw arg: the arg may be a library recipe NAME
-    // that only the resolver knows how to turn into a file.
-    () => runRecipe(adapter, validated.recipeFile, artifactsDir, target, optionString(options, "actionManifest"), runtimeOptions),
-    adapter,
-    target,
-    heal,
-    state
-  );
-  if (violation !== null) return emitHealViolation(json, "run", result, violation, state, adapter);
-  const report = writeRunReport(result);
-  const exitCode = result.status === "pass" ? EXIT.ok : EXIT.runtime;
-  if (json) {
-    console.log(
-      JSON.stringify(
-        {
-          schemaVersion: 1,
-          command: "run",
-          adapter,
-          status: result.status,
-          exitCode,
-          recovered: state.recovered,
-          mutations: state.mutations,
-          reportPath: report.path,
-          result
-        },
-        null,
-        2
-      )
+  const lock = acquireCheckoutLock(target, "run");
+  if ("message" in lock) return checkoutBusyOut(json, "run", lock.message, lock.path);
+  try {
+    const prepared = await prepareHeal(adapter, target, options, json);
+    if (typeof prepared === "number") return prepared;
+    const { state, heal } = prepared;
+    const librarySources = validated.librarySources;
+    const runtimeOptions = {
+      ...runtimeOptionsFromCli(options),
+      ...librarySources ? { librarySources } : {},
+      stdoutIsMachineContract: json
+    };
+    const { result, violation } = await executeWithHealBounds(
+      // validated.recipeFile, not the raw arg: the arg may be a library recipe NAME
+      // that only the resolver knows how to turn into a file.
+      () => runRecipe(adapter, validated.recipeFile, artifactsDir, target, optionString(options, "actionManifest"), runtimeOptions),
+      adapter,
+      target,
+      heal,
+      state,
+      () => recoverRunInfra(adapter, target, json)
     );
-  } else {
-    const out = (style, text) => color(style, text, { stream: process.stdout });
-    console.log(`${out(result.status === "pass" ? "ok" : "err", result.status.toUpperCase())} ${out("bold", "recipe run")} ${out("dim", `[${adapter}]`)}`);
-    if (report.preview.length > 0) {
-      console.log(out("label", "summary:"));
-      for (const line of report.preview) console.log(`  ${formatPreviewLine(line, out)}`);
+    if (violation !== null) return emitHealViolation(json, "run", result, violation, state, adapter);
+    const report = writeRunReport(result);
+    const exitCode = result.status === "pass" ? EXIT.ok : EXIT.runtime;
+    if (json) {
+      console.log(
+        JSON.stringify(
+          {
+            schemaVersion: 1,
+            command: "run",
+            adapter,
+            status: result.status,
+            exitCode,
+            recovered: state.recovered,
+            mutations: state.mutations,
+            reportPath: report.path,
+            result
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      const out = (style, text) => color(style, text, { stream: process.stdout });
+      console.log(`${out(result.status === "pass" ? "ok" : "err", result.status.toUpperCase())} ${out("bold", "recipe run")} ${out("dim", `[${adapter}]`)}`);
+      if (report.preview.length > 0) {
+        console.log(out("label", "summary:"));
+        for (const line of report.preview) console.log(`  ${formatPreviewLine(line, out)}`);
+      }
+      console.log(`${out("label", "report:")} ${out("path", report.path)}`);
+      console.log(`${out("label", "artifacts:")} ${out("path", result.artifactManifestPath)}`);
     }
-    console.log(`${out("label", "report:")} ${out("path", report.path)}`);
-    console.log(`${out("label", "artifacts:")} ${out("path", result.artifactManifestPath)}`);
+    return exitCode;
+  } finally {
+    lock.release();
   }
-  return exitCode;
 }
 function formatPreviewLine(line, out) {
   const match = /^(PASS|FAIL)\s+(.+)$/u.exec(line);
@@ -271,8 +288,8 @@ function emitPlanUsageError(json, adapter, recipeFile, code, message) {
 function runArgLooksLikeRecipeFile(value) {
   return path.isAbsolute(value) || value.includes("/") || value.includes(path.sep) || value.endsWith(".json") || fs.existsSync(path.resolve(value));
 }
-function emitRunRecipeRunning(json) {
-  const message = "a recipe is currently running \u2014 refusing to start while another recipe executes.";
+function emitRunRecipeRunning(json, detail) {
+  const message = detail ?? "a recipe is currently running \u2014 refusing to start while another recipe executes.";
   if (json) {
     console.log(JSON.stringify({ schemaVersion: 1, status: "fail", recoverable: false, error: { code: "RECIPE_RUNNING", message } }, null, 2));
   } else {