@deeeed/metamask-harness 0.67.1 → 0.69.0

package/dist/command-journal.js

@@ -1,9 +1,12 @@
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { OperationRecord, readOperations, processIdentity, ensureRuntimeDirectory } from "@farmslot/recipe-harness/runtime/operation";
+import { latestTaskDir } from "@farmslot/agent-runtime";
 import { recipeRuntimeDir } from "./paths.js";
 const COMMAND_JOURNAL_FILE = "last-command.json";
 const JOURNALED_COMMANDS = /* @__PURE__ */ new Set([
+  "prepare",
   "call",
   "check",
   "checklist",
@@ -12,6 +15,7 @@ const JOURNALED_COMMANDS = /* @__PURE__ */ new Set([
   "fixtures",
   "install",
   "launch",
+  "runtime-launch",
   "provision",
   "recipe-quality",
   "run",
@@ -25,6 +29,8 @@ async function withCommandJournal(command, argv, execute) {
   if (!JOURNALED_COMMANDS.has(command)) return execute();
   const handle = tryBeginCommandJournal(command, argv);
   const previous = activeCommandJournal;
+  const parentId = process.env.MM_HARNESS_OPERATION_ID;
+  if (handle) process.env.MM_HARNESS_OPERATION_ID = handle.operation.value.id;
   activeCommandJournal = handle;
   try {
     const exitCode = await execute();
@@ -35,8 +41,16 @@ async function withCommandJournal(command, argv, execute) {
     throw error;
   } finally {
     activeCommandJournal = previous;
+    if (parentId) process.env.MM_HARNESS_OPERATION_ID = parentId;
+    else delete process.env.MM_HARNESS_OPERATION_ID;
   }
 }
+function recordCommandStage(stage) {
+  activeCommandJournal?.operation.stage(stage);
+}
+function recordCommandOutput(chunk) {
+  activeCommandJournal?.operation.output(chunk);
+}
 function recordCommandEvidence(...evidence) {
   const handle = activeCommandJournal;
   if (!handle || evidence.length === 0) return;
@@ -58,7 +72,12 @@ function commandJournalPath(target, runtimeDir) {
   return path.join(path.resolve(target), relative, COMMAND_JOURNAL_FILE);
 }
 function readCommandJournal(target, runtimeDir) {
-  const file = commandJournalPath(target, runtimeDir);
+  const legacyFile = commandJournalPath(target, runtimeDir);
+  const operations = readOperations(path.join(path.dirname(legacyFile), "operations"));
+  const live = operations.filter((operation) => operation.status === "running" && processIdentity(operation.pid) === operation.processStartedAt);
+  const roots = operations.filter((operation) => !operation.parentId).sort((a, b) => (a.finishedAt ?? a.startedAt).localeCompare(b.finishedAt ?? b.startedAt));
+  const selected = live.find((operation) => !operation.parentId) ?? live.at(-1) ?? roots.at(-1) ?? operations.at(-1);
+  const file = selected ? path.join(path.dirname(legacyFile), "operations", `${selected.id}.journal.json`) : legacyFile;
   let descriptor;
   try {
     const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
@@ -113,12 +132,34 @@ function redactCommandArgs(argv) {
   }
   return redacted;
 }
+function pruneCompletedJournals(directory, operations) {
+  const completed = operations.filter((operation) => operation.status !== "running");
+  for (const operation of completed.slice(0, -100)) {
+    for (const suffix of [".json", ".journal.json", ".log"]) {
+      fs.rmSync(path.join(directory, `${operation.id}${suffix}`), { force: true });
+    }
+  }
+}
 function tryBeginCommandJournal(command, argv) {
   try {
     const target = invocationTarget(argv);
     if (!fs.existsSync(target)) return void 0;
     const runtimeDir = optionValue(argv, "--runtime-dir");
-    const file = commandJournalPath(target, runtimeDir);
+    const legacyFile = commandJournalPath(target, runtimeDir);
+    const taskDir = latestTaskDir(path.join(target, "temp", "tasks"));
+    const signalFile = taskDir && path.join(taskDir, "SIGNAL.json");
+    const liveTask = signalFile && fs.existsSync(signalFile) && JSON.parse(fs.readFileSync(signalFile, "utf8")).status === "running";
+    const directory = path.join(path.dirname(legacyFile), "operations");
+    const operations = readOperations(directory, (error) => process.stderr.write(`mm-harness: ignoring invalid prior operation: ${error.message}
+`));
+    pruneCompletedJournals(directory, operations);
+    const inherited = process.env.MM_HARNESS_OPERATION_ID;
+    const parent = inherited && operations.find((operation2) => operation2.id === inherited && operation2.target === target && operation2.status === "running" && processIdentity(operation2.pid) === operation2.processStartedAt);
+    const operation = new OperationRecord(directory, command, target, {
+      ...parent ? { parentId: parent.id } : {},
+      ...liveTask ? { mirrorDirectory: path.join(taskDir, "artifacts", "operations") } : {}
+    });
+    const file = path.join(directory, `${operation.value.id}.journal.json`);
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const record = {
       schemaVersion: 1,
@@ -132,7 +173,7 @@ function tryBeginCommandJournal(command, argv) {
       finishedAt: null
     };
     writeAtomic(file, record);
-    return { file, record };
+    return { file, record, operation };
   } catch (error) {
     process.stderr.write(
       `mm-harness: resumability journal unavailable: ${errorMessage(error)}
@@ -155,14 +196,17 @@ function tryFinishCommandJournal(handle, exitCode) {
       `mm-harness: resumability journal could not finalize: ${errorMessage(error)}
 `
     );
+  } finally {
+    handle.operation.finish(exitCode);
   }
 }
 function writeAtomic(file, record) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
+  ensureRuntimeDirectory(path.dirname(file));
   const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
   let descriptor;
   try {
     descriptor = fs.openSync(temporary, "wx", 384);
+    fs.fchmodSync(descriptor, 384);
     fs.writeFileSync(descriptor, `${JSON.stringify(record, null, 2)}
 `);
     fs.fsyncSync(descriptor);
@@ -175,9 +219,8 @@ function writeAtomic(file, record) {
   }
 }
 function invocationTarget(argv) {
-  return path.resolve(
-    optionValue(argv, "--target") ?? process.cwd()
-  );
+  const target = path.resolve(optionValue(argv, "--target") ?? process.cwd());
+  return fs.existsSync(target) ? fs.realpathSync(target) : target;
 }
 function evidencePaths(argv) {
   const values = /* @__PURE__ */ new Set();
@@ -257,6 +300,8 @@ export {
   isSensitiveKey,
   readCommandJournal,
   recordCommandEvidence,
+  recordCommandOutput,
+  recordCommandStage,
   redactCommandArgs,
   redactStructuredValue,
   withCommandJournal

package/dist/commands/call.js

@@ -65,6 +65,9 @@ async function handleCall(argv) {
   }
   const { action: shortName, args, rest } = parseCallArgs(argv);
   const { options } = parseArgs(rest, "call");
+  if (["domain", "source", "sort"].some((name) => optionString(options, name) !== void 0)) {
+    throw usageError("--domain, --source, and --sort require call --list.");
+  }
   const json = optionFlag(options, "json");
   if (!shortName) {
     let example = "mm-harness call <action>";

package/dist/commands/checklist.js

@@ -12,6 +12,7 @@ const MARK_SCRIPT = require2.resolve(
 const { resolveChecklistPaths } = require2(
   "@farmslot/agent-runtime/scripts/checklist-target.cjs"
 );
+const { readSubtaskIndex, SubtaskRefusal } = require2("@farmslot/agent-runtime/scripts/subtask-unit.cjs");
 const USAGE = "mm-harness checklist <mark <task-dir> <step> | closeout <task-dir>> [options]";
 const CHECKLIST_VALUE_OPTIONS = /* @__PURE__ */ new Set([
   "--reason",
@@ -129,10 +130,10 @@ function checklistStepRequiresDiffPass(checklist, stepNumber) {
   const step = enumerateChecklistCheckboxes(checklist).find((item) => item.stepNumber === stepNumber);
   return step !== void 0 && /mm-harness check diff/u.test(step.rawLabel);
 }
-function checkDiffGateReady(taskDir, step) {
+function checkDiffGateReady(taskDir, step, parentChecklist) {
   const stepNumber = numericMarkStep(step);
   if (stepNumber === null) return true;
-  const { taskPath } = resolveChecklistPaths(taskDir);
+  const taskPath = parentChecklist ? path.join(taskDir, parentChecklist) : resolveChecklistPaths(taskDir).taskPath;
   let checklist = "";
   try {
     checklist = fs.readFileSync(taskPath, "utf8");
@@ -203,6 +204,16 @@ async function handleChecklist(argv) {
     return EXIT.usage;
   }
   if (preserveTerminalSignal(resolvedTaskDir, step)) return EXIT.ok;
+  if (step === "sub" && forwarded[2] === "complete") {
+    try {
+      const unit = readSubtaskIndex(resolvedTaskDir)?.units.find((unit2) => unit2.id === forwarded[1]);
+      if (unit && !checkDiffGateReady(resolvedTaskDir, String(unit.parent.stepNumber), unit.parent.checklist)) return EXIT.runtime;
+    } catch (error) {
+      if (!(error instanceof SubtaskRefusal)) throw error;
+      console.error(error.message);
+      return error.code;
+    }
+  }
   if (!checkDiffGateReady(resolvedTaskDir, step)) return EXIT.runtime;
   teachRecipeCompletion(resolvedTaskDir, step);
   const result = spawnSync(

package/dist/commands/fixtures.js

@@ -559,13 +559,12 @@ async function fixturesFinalize(adapter, target, options, json) {
   }
   return exitCode;
 }
-function fixturesSync(adapter, target, json) {
+async function fixturesSync(adapter, target, json) {
   const mmHarnessBin = path.join(runnerDir, "bin/mm-harness");
-  const installResult = spawnScript(
+  const installResult = await spawnScriptStreaming(
     mmHarnessBin,
     ["install", "--adapter", adapter, "--target", target],
-    target,
-    json
+    target
   );
   if (installResult.status !== 0) {
     if (!json) {
@@ -578,7 +577,7 @@ function fixturesSync(adapter, target, json) {
   const syncArgs = ["--target", target];
   if (process.env.CDP_PORT) syncArgs.push("--cdp-port", process.env.CDP_PORT);
   if (process.env.RECIPE_SLOT_ID) syncArgs.push("--slot-id", process.env.RECIPE_SLOT_ID);
-  const syncResult = spawnScript(syncFixtureSh, syncArgs, target, json);
+  const syncResult = await spawnScriptStreaming(syncFixtureSh, syncArgs, target);
   if (syncResult.status !== 0 || fixtureSummary(target, adapter).status !== "ready") {
     if (!json) console.error("\u2717 no usable wallet fixture source was found.\n  Next: mm-harness fixtures init --from <path>   or   mm-harness fixtures init --dev");
     return EXIT.runtime;

package/dist/commands/launch/index.js

@@ -320,6 +320,10 @@ async function handleLaunchLocked(argv, stream) {
   if (attempt.status === 0) {
     return await settleLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, remoteFlagRequest, true, attempt.remoteFeatureFlags);
   }
+  const readinessFailure = mobileReadinessFailure(attempt);
+  if (readinessFailure) {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, readinessFailure);
+  }
   if (adapter === "extension" && attempt.output.includes("REMOTE_FLAG_NOT_PINNABLE:")) {
     return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: "REMOTE_FLAG_NOT_PINNABLE",
@@ -503,6 +507,10 @@ async function handleLaunchLocked(argv, stream) {
     state.recovered.push(recoveryCode);
     return await settleLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, remoteFlagRequest, true, attempt.remoteFeatureFlags);
   }
+  const retryReadinessFailure = mobileReadinessFailure(attempt);
+  if (retryReadinessFailure) {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, retryReadinessFailure);
+  }
   return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
     code: "SAME_RECOVERY_TWICE",
     message: `launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ""} failed again after ${recoveryCode} recovery \u2014 refusing to loop.`,
@@ -511,6 +519,17 @@ async function handleLaunchLocked(argv, stream) {
     originalError: attempt.output.trim() || void 0
   });
 }
+function mobileReadinessFailure(result) {
+  const block = result.readinessBlock;
+  if (!block) return void 0;
+  return {
+    code: block.reasonCode === "deps-not-ready" ? "MOBILE_DEPENDENCIES_NOT_READY" : "MOBILE_READINESS_BLOCKED",
+    message: block.message,
+    userAction: block.userAction,
+    recoverable: false,
+    exitCode: result.status
+  };
+}
 function extensionQuickReattachFailed(output) {
   return /\[reattach\]|extension quick reattach|mm-harness launch --build/u.test(output);
 }

package/dist/commands/list-executables.js

@@ -5,13 +5,14 @@ import { importRecipeProtocol } from "../paths.js";
 import { color } from "../cli-color.js";
 import { EXIT } from "./shared.js";
 import { optionFlag, optionString, optionStrings, resolveAdapter, shellQuoteArg } from "./parse-args.js";
-import { describeManifestActions, renderHumanActionCatalog } from "./manifest.js";
+import { actionDomain, describeManifestActions, renderHumanActionCatalog } from "./manifest.js";
 import {
   describeRunnableRecipe,
   listRunnableRecipes,
   resolveMetaMaskLibrarySources
 } from "./run-engine.js";
 const finalSegment = (name) => name.split(".").pop() ?? name;
+const recipeDomain = (name) => name.includes(".") ? name.split(".")[0].replaceAll("_", "-") : "general";
 function catalogDescription(description) {
   if (!description) return "";
   const firstSentence = description.match(/^.*?[.!?](?:\s|$)/u)?.[0]?.trim() ?? description;
@@ -20,23 +21,64 @@ function catalogDescription(description) {
 async function handleListExecutables(command, options) {
   const json = optionFlag(options, "json");
   const { adapter } = resolveAdapter(options);
+  const domainFilter = optionString(options, "domain")?.replaceAll("_", "-");
+  const sourceFilter = optionString(options, "source");
+  const sort = optionString(options, "sort") ?? (json ? "name" : "domain");
+  const groupKey = (entry, domain) => sort === "library" ? entry.source : sort === "domain" ? domain : "";
+  const select = (available2, domainOf) => available2.filter((entry) => (!domainFilter || domainOf(entry) === domainFilter) && (!sourceFilter || entry.source === sourceFilter)).sort((left, right) => groupKey(left, domainOf(left)).localeCompare(groupKey(right, domainOf(right))) || left.name.localeCompare(right.name));
+  const out = (style, text) => color(style, text, { stream: process.stdout });
+  const stylesFor = (domains) => {
+    const palette = ["label", "accent", "ok", "warn"];
+    return new Map([...new Set(domains)].sort().map((domain, index) => [domain, palette[index % palette.length]]));
+  };
   const librarySources = await resolveMetaMaskLibrarySources(optionStrings(options, "library"));
+  const libraryLines = () => {
+    const lines = ["Libraries loaded:"];
+    for (const source of librarySources ?? []) {
+      const name = source.name ?? path.basename(source.root);
+      const kind = source.provenance?.kind === "bundled" ? "bundled" : "linked";
+      lines.push(`  ${out("bold", name)} ${kind} \xB7 ${source.root}`);
+    }
+    if (domainFilter || sourceFilter) {
+      lines.push(`Filter: ${[domainFilter && `domain=${domainFilter}`, sourceFilter && `source=${sourceFilter}`].filter(Boolean).join(" ")}`);
+    }
+    return lines;
+  };
   if (command === "run") {
-    const recipes = await listRunnableRecipes(adapter, librarySources);
+    const available2 = await listRunnableRecipes(adapter, librarySources);
+    const recipes = select(available2, (recipe) => recipeDomain(recipe.name));
     if (json) {
       console.log(JSON.stringify({ schemaVersion: 1, command, action: "list", adapter, recipes }, null, 2));
       return EXIT.ok;
     }
-    const out = (style, text) => color(style, text, { stream: process.stdout });
+    const domainStyles = stylesFor(available2.map((recipe) => recipeDomain(recipe.name)));
     console.log(out("bold", `runnable recipes (${adapter})`));
+    for (const line of libraryLines()) console.log(line);
     console.log(out("comment", "Inspect: mm-harness run <recipe> --describe"));
+    if (recipes.length === 0) {
+      console.log("No runnable recipes match.");
+      console.log(`Available domains: ${[...domainStyles.keys()].join(", ") || "none"}`);
+      console.log(`Available sources: ${[...new Set(available2.map((recipe) => recipe.source))].join(", ") || "none"}`);
+    }
+    const groups = /* @__PURE__ */ new Map();
     for (const recipe of recipes) {
-      const shadowed = recipe.shadows.length > 0 ? ` shadows=${recipe.shadows.join(",")}` : "";
-      const variant = recipe.variant ? ` variant=${recipe.variant}` : " variant=all";
-      const parameters = recipe.parameters.length > 0 ? ` params=${recipe.parameters.map((parameter) => parameter.name).join(",")}` : "";
-      const summary = catalogDescription(recipe.description);
-      const description = summary ? ` \u2014 ${summary}` : "";
-      console.log(`  ${out("cmd", recipe.name)} ${out("dim", `[${recipe.source}]${variant}${shadowed}${parameters}`)}${description}`);
+      const group = groupKey(recipe, recipeDomain(recipe.name));
+      groups.set(group, [...groups.get(group) ?? [], recipe]);
+    }
+    for (const [group, entries] of groups) {
+      if (group) {
+        const label = sort === "library" ? `Library: ${group}` : group;
+        console.log(`
+${out(sort === "domain" ? domainStyles.get(group) : "bold", label)} ${out("dim", `(${entries.length})`)}`);
+      }
+      for (const recipe of entries) {
+        const style = domainStyles.get(recipeDomain(recipe.name));
+        const shadowed = recipe.shadows.length > 0 ? ` shadows=${recipe.shadows.join(",")}` : "";
+        const variant = recipe.variant ? ` variant=${recipe.variant}` : " variant=all";
+        const summary = catalogDescription(recipe.description);
+        console.log(`  ${out(style, recipe.name)} ${out("dim", `library=${recipe.source}${variant}${shadowed}`)}`);
+        if (summary) console.log(`    ${summary}`);
+      }
     }
     return EXIT.ok;
   }
@@ -47,9 +89,10 @@ async function handleListExecutables(command, options) {
   );
   const { getRecipeActionManifestActionNames } = await importRecipeProtocol();
   const protocolNames = new Set(getRecipeActionManifestActionNames(manifest));
-  const described = describeManifestActions(manifest, actionSources).filter((entry) => protocolNames.has(entry.name)).sort((left, right) => left.name.localeCompare(right.name));
+  const available = describeManifestActions(manifest, actionSources).filter((entry) => protocolNames.has(entry.name)).sort((left, right) => left.name.localeCompare(right.name));
+  const described = select(available, actionDomain);
   const shortCounts = /* @__PURE__ */ new Map();
-  for (const entry of described) {
+  for (const entry of available) {
     const short = finalSegment(entry.name);
     shortCounts.set(short, (shortCounts.get(short) ?? 0) + 1);
   }
@@ -73,9 +116,17 @@ async function handleListExecutables(command, options) {
     console.log(JSON.stringify({ schemaVersion: 1, command, action: "list", adapter, actions }, null, 2));
     return EXIT.ok;
   }
+  const contextLines = libraryLines();
+  if (described.length === 0) {
+    contextLines.push(`Available domains: ${[...new Set(available.map(actionDomain))].sort().join(", ") || "none"}`);
+    contextLines.push(`Available sources: ${[...new Set(available.map((entry) => entry.source))].sort().join(", ") || "none"}`);
+  }
   console.log(renderHumanActionCatalog(described, {
     title: `invocable actions (${adapter})`,
     guidance: "Use: mm-harness call <name>  \xB7  short names shown first where unambiguous",
+    sort,
+    domainStyles: stylesFor(available.map(actionDomain)),
+    contextLines,
     displayName: (entry) => {
       const short = shortByName.get(entry.name);
       return short ? `${short} (${entry.name})` : `${entry.name} (full name only \u2014 ambiguous short)`;

package/dist/commands/manifest.js

@@ -345,16 +345,21 @@ function summarizeDescribedAction(entry) {
   const { schema: _schema, examples: _examples, ...summary } = entry;
   return summary;
 }
+function actionDomain(entry) {
+  return entry.category.replaceAll("_", "-");
+}
 function renderHumanActionCatalog(actions, options) {
   const out = (style, text) => color(style, text, { stream: process.stdout });
   const groups = /* @__PURE__ */ new Map();
   for (const entry of actions) {
-    const group = actionDomainGroup(entry);
+    const group = options.sort === "name" ? "" : options.sort === "library" ? `Library: ${entry.source}` : options.sort === "domain" ? actionDomain(entry) : actionDomainGroup(entry);
     groups.set(group, [...groups.get(group) ?? [], entry]);
   }
-  const lines = [out("bold", options.title), out("comment", options.guidance)];
+  const lines = [out("bold", options.title), ...options.contextLines ?? [], out("comment", options.guidance)];
+  if (actions.length === 0) lines.push("No callable actions match.");
   for (const [group, entries] of groups) {
-    lines.push("", `${out(group === "official" ? "label" : "accent", group)} ${out("dim", `(${entries.length})`)}`);
+    const groupStyle = options.sort === "domain" ? options.domainStyles?.get(group) ?? "accent" : group === "official" ? "label" : "accent";
+    if (group) lines.push("", `${out(groupStyle, group)} ${out("dim", `(${entries.length})`)}`);
     for (const entry of entries) {
       const fieldNames = humanFieldNames(entry);
       const fields = fieldNames.length ? ` ${out("dim", `fields=${fieldNames.join(",")}`)}` : "";
@@ -362,7 +367,8 @@ function renderHumanActionCatalog(actions, options) {
       const description = entry.description ? ` ${out("comment", `\u2014 ${entry.description}`)}` : "";
       const source = ` ${out("dim", `[${entry.source}]`)}`;
       const risk = entry.capabilities.length ? ` ${out("dim", `risk=${entry.capabilities.join(",")}`)}` : "";
-      lines.push(`  ${out("cmd", options.displayName?.(entry) ?? entry.name)}${source}${fields}${cases}${risk}${description}`);
+      const nameStyle = options.domainStyles?.get(actionDomain(entry)) ?? "cmd";
+      lines.push(`  ${out(nameStyle, options.displayName?.(entry) ?? entry.name)}${source}${fields}${cases}${risk}${description}`);
     }
   }
   return lines.join("\n");
@@ -585,6 +591,7 @@ function levenshtein(left, right) {
 }
 export {
   ACTION_MATRIX_ADAPTERS,
+  actionDomain,
   actionExampleCommand,
   actionLibraryContextArgs,
   describeManifestActions,

package/dist/commands/prepare.js

@@ -1,4 +1,7 @@
+import { acquireCheckoutLock, trackCheckoutChild } from "../checkout-lock.js";
+import { recordCommandStage } from "../command-journal.js";
 import { spawn } from "node:child_process";
+import { OperationOutputTail } from "@farmslot/recipe-harness/runtime/operation";
 import fs from "node:fs";
 import path from "node:path";
 import {
@@ -168,18 +171,19 @@ function spawnStep(executable, args, target) {
       // stream a recorded readiness step captures.
       env: { ...process.env, MM_HARNESS_NO_UPDATE_CHECK: "1" }
     });
+    if (child.pid) trackCheckoutChild(target, child.pid);
     let stdout = "";
-    let stderr = "";
+    const stderr = new OperationOutputTail();
     child.stdout?.setEncoding("utf8");
     child.stderr?.setEncoding("utf8");
     child.stdout?.on("data", (chunk) => {
       stdout += chunk;
     });
     child.stderr?.on("data", (chunk) => {
-      stderr += chunk;
+      stderr.append(chunk);
     });
-    child.on("error", (error) => resolve({ error, status: null, stdout, stderr }));
-    child.on("close", (status) => resolve({ status, stdout, stderr }));
+    child.on("error", (error) => resolve({ error, status: null, stdout, stderr: stderr.toString() }));
+    child.on("close", (status) => resolve({ status, stdout, stderr: stderr.toString() }));
   });
 }
 async function runStep(executable, target, artifactsDir, id, args, { json, onSpawn }) {
@@ -305,6 +309,22 @@ function resolvePlatform(requested, target) {
   );
 }
 async function handlePrepare(argv) {
+  const { options } = parseArgs(argv, "prepare");
+  const target = targetPath(options);
+  if (!fs.existsSync(target)) return handlePrepareLocked(argv);
+  const lock = acquireCheckoutLock(target, "prepare");
+  if ("message" in lock) {
+    if (optionFlag(options, "json")) console.log(JSON.stringify({ status: "fail", error: { code: "SANDBOX_BUSY", message: lock.message }, exitCode: EXIT.runtime }));
+    else console.error(`${lock.message} Next: inspect the owning operation with mm-harness status --watch`);
+    return EXIT.runtime;
+  }
+  try {
+    return await handlePrepareLocked(argv);
+  } finally {
+    lock.release();
+  }
+}
+async function handlePrepareLocked(argv) {
   const { options } = parseArgs(argv, "prepare");
   const json = optionFlag(options, "json");
   const target = targetPath(options);
@@ -372,6 +392,7 @@ async function handlePrepare(argv) {
     const step = await runStep(executable, target, artifactsDir, id, args, {
       json,
       onSpawn: (stepStartedAt) => {
+        recordCommandStage(id);
         activeStep = { id, startedAt: new Date(stepStartedAt).toISOString() };
         writeProgress();
         view?.start(id, stepStartedAt);

package/dist/commands/run-engine.js

@@ -20,7 +20,8 @@ import {
 import {
   importRecipeHarness,
   importRecipeProtocol,
-  runnerDir
+  runnerDir,
+  recipeRuntimePath
 } from "../paths.js";
 import { captureHelperSupportsRecordSessionSnapshots } from "../recording-target.js";
 import { startRecipeRecording, stopRecipeRecording } from "../run-recording.js";
@@ -277,7 +278,11 @@ async function resolveRecipeExecution(adapter, recipe, artifactsDir, projectRoot
     recipeDocument: recipeDocument ?? recipe,
     ...absoluteRecipePath ? { recipePath: absoluteRecipePath } : {},
     ...librarySources ? { librarySources } : {},
-    excludedProductRoots: [absoluteArtifactsDir],
+    excludedProductRoots: [
+      absoluteArtifactsDir,
+      recipeRuntimePath(projectRoot, "operations"),
+      recipeRuntimePath(projectRoot, "lock-members")
+    ],
     helperPaths: commandHelperPaths(recipeDocument ?? recipe, projectRoot)
   };
   const startProvenance = await captureExecutionProvenance(
@@ -416,6 +421,7 @@ function runtimeRecipeDocument(recipe, absoluteRecipePath) {
 function recipeProcessEnvironment() {
   const env = { ...process.env };
   delete env.MM_HARNESS_CHECKOUT_LOCK_TOKEN;
+  delete env.MM_HARNESS_OPERATION_ID;
   return env;
 }
 function executionLibrarySources(sources, invocationTrust) {

package/dist/commands/run.js

@@ -147,6 +147,9 @@ async function handleRun(parsed) {
   }
 }
 async function handleRunInner({ positional, options }, stream) {
+  if (!optionFlag(options, "list") && ["domain", "source", "sort"].some((name) => optionString(options, name) !== void 0)) {
+    throw usageError("--domain, --source, and --sort require run --list.");
+  }
   if (optionFlag(options, "describe") && (optionFlag(options, "list") || optionFlag(options, "plan"))) {
     const message = "--describe cannot be combined with --list or --plan.";
     const userAction = "choose one: mm-harness run --list, mm-harness run <recipe> --describe, or mm-harness run <recipe> --plan";

package/dist/commands/runtime-launch.js

@@ -1,4 +1,5 @@
-import { spawnSync } from "node:child_process";
+import { checkoutBusyOut, spawnScriptStreaming } from "./shared.js";
+import { acquireCheckoutLock } from "../checkout-lock.js";
 import fs from "node:fs";
 import path from "node:path";
 import {
@@ -23,7 +24,18 @@ import {
   usageError
 } from "./parse-args.js";
 import { FeatureFlagSpecError, parseRemoteFlagSpec } from "../feature-flags.js";
-async function handleRuntimeLaunch({ options }) {
+async function handleRuntimeLaunch(args) {
+  const target = targetPath(args.options);
+  if (optionFlag(args.options, "help") || !fs.existsSync(target)) return handleRuntimeLaunchLocked(args);
+  const lock = acquireCheckoutLock(target, "runtime-launch");
+  if ("message" in lock) return checkoutBusyOut(optionFlag(args.options, "json"), "runtime-launch", lock.message, lock.path);
+  try {
+    return await handleRuntimeLaunchLocked(args);
+  } finally {
+    lock.release();
+  }
+}
+async function handleRuntimeLaunchLocked({ options }) {
   if (optionFlag(options, "help")) {
     console.log(`mm-harness runtime-launch --adapter <extension|mobile> --target <checkout> [flags]
 
@@ -186,11 +198,11 @@ async function handleRuntimeLaunch({ options }) {
       cdpPort
     }));
   }
-  const result = spawnSync(command[0], command.slice(1), {
-    cwd: target,
-    encoding: "utf8",
-    maxBuffer: 5 * 1024 * 1024,
-    stdio: jsonMode ? ["ignore", "pipe", "pipe"] : "inherit"
+  const result = await spawnScriptStreaming(command[0], command.slice(1), target, {
+    forward: jsonMode ? "stderr" : "original",
+    stdin: jsonMode ? "ignore" : "inherit",
+    capture: false,
+    stage: mode
   });
   const summaryPath = path.join(artifactsDir, "summary.json");
   const summary = readJsonIfExists(summaryPath);