@deeeed/metamask-harness 0.67.1 → 0.68.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.68.0 - 2026-09-29
+
+### Changed
+
+- Verify Mobile readiness with one combined status/bridge recipe, retaining device-discovery retries and RPC checks; recognize Lite screens when the release hides the Pro toggle.
+- Restart Metro when build environment inputs change and select the matching transform-cache generation without clearing caches.
+- Forward child checklist progress through the public CLI while retaining the owning step's diff-validation gate.
+- Keep operation and checkout ownership records readable under restrictive umasks, and exclude observation updates from product provenance.
+- Retain command-specific logs and stage observations in `status --watch`; preserve nested operation and checkout ownership across long builds. Pin protocol 0.33.0, recipe-harness 0.21.1, agent-runtime 0.15.1 and expo-recipe 0.12.2 for a consistent runtime dependency tree.
+
 ## 0.67.1 - 2026-09-29
 
 ### Fixed

package/adapters/mobile/metro-config.cjs

@@ -84,8 +84,12 @@ module.exports = async function harnessMetroConfig(baseConfig) {
     `^${escapeRegExp(tempRoot)}(?:${escapeRegExp(path.sep)}|$)`,
     blockListFlags(existingBlockList),
   );
+  // Inline environment values affect transformed JavaScript. Keep separate
+  // cache generations for those inputs instead of deleting the shared cache.
+  const envFingerprint = process.env.MM_HARNESS_METRO_ENV_FINGERPRINT;
   return {
     ...productConfig,
+    ...(envFingerprint ? { cacheVersion: `${productConfig.cacheVersion ?? ''}:mm-env:${envFingerprint}` } : {}),
     resolver: {
       ...productConfig.resolver,
       blockList: appendBlockList(existingBlockList, tempPattern),

package/adapters/mobile/start-metro.sh

@@ -10,6 +10,7 @@
 # Inputs:
 #   --target <metamask-mobile dir>  (default $PWD)
 #   --port <number>                 (default: WATCHER_PORT env, else METRO_PORT, else 8081)
+#   --restart                       restart Metro while retaining its transform cache
 #   --clear                         reset Metro bundler cache before starting
 # Outputs:
 #   Progress on stderr; exit 0 Metro ready; 1 failed to start; 2 bad args.
@@ -20,16 +21,19 @@ set -uo pipefail
 TARGET="$PWD"
 PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
 CLEAR=false
+RESTART=false
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --target) TARGET="$2"; shift 2 ;;
     --port)   PORT="$2"; shift 2 ;;
     --clear)  CLEAR=true; shift ;;
+    --restart) RESTART=true; shift ;;
     -h|--help)
-      printf 'Usage: start-metro.sh [--target <dir>] [--port <port>] [--clear]\n'
+      printf 'Usage: start-metro.sh [--target <dir>] [--port <port>] [--restart] [--clear]\n'
       printf '  --target  MetaMask Mobile checkout directory\n'
       printf '  --port    Metro port (default: WATCHER_PORT env or 8081)\n'
+      printf '  --restart restart while preserving the transform cache\n'
       printf '  --clear   restart with cleared cache\n'
       exit 0
       ;;
@@ -60,6 +64,9 @@ export MM_HARNESS_METRO_PROJECT_ROOT="$TARGET"
 export MM_HARNESS_METRO_BASE_CONFIG="$PRODUCT_METRO_CONFIG"
 export EXPO_OVERRIDE_METRO_CONFIG="$HARNESS_METRO_CONFIG"
 MOBILE_METRO_REQUIRED_ENV="${MOBILE_METRO_REQUIRED_ENV:-MM_INFURA_PROJECT_ID METAMASK_BUILD_TYPE METAMASK_ENVIRONMENT} MM_HARNESS_METRO_PROJECT_ROOT MM_HARNESS_METRO_BASE_CONFIG EXPO_OVERRIDE_METRO_CONFIG"
+if [ -n "${MM_HARNESS_METRO_ENV_FINGERPRINT:-}" ]; then
+  MOBILE_METRO_REQUIRED_ENV="$MOBILE_METRO_REQUIRED_ENV MM_HARNESS_METRO_ENV_FINGERPRINT"
+fi
 
 # RECIPE_RUNTIME_DIR (relative, validated) makes runtime state per-run so jobs
 # sharing one checkout do not collide on metro.log / metro.pid / metro.tmux.
@@ -212,8 +219,12 @@ fi
 
 # Decide whether to (re)start or skip.
 if metro_ready; then
-  if [ "$CLEAR" = true ]; then
-    printf 'Restarting Metro on port %s with cleared cache\n' "$PORT" >&2
+  if [ "$CLEAR" = true ] || [ "$RESTART" = true ]; then
+    if [ "$CLEAR" = true ]; then
+      printf 'Restarting Metro on port %s with cleared cache\n' "$PORT" >&2
+    else
+      printf 'Restarting Metro on port %s with its transform cache preserved\n' "$PORT" >&2
+    fi
     stop_metro_listener || exit 1
     rm -f "$PID_FILE"
   elif metro_listener_valid; then

package/dist/adapters/mobile/prepare.js

@@ -270,7 +270,8 @@ async function dispatchActionSequence(requestedActions, target, platform, json,
       platform,
       json,
       preflightMode,
-      watcherPort
+      watcherPort,
+      pendingMetroEnvFingerprint
     );
     if (result.status !== 0) return result;
     if (action.id === "yarn-setup") recordDepsBaseline(resolved);
@@ -378,7 +379,7 @@ function enableIosAccessibility(json) {
     return false;
   }
 }
-async function dispatchAction(action, target, platform, json, preflightMode = "fast", watcherPort) {
+async function dispatchAction(action, target, platform, json, preflightMode = "fast", watcherPort, metroEnvFingerprint) {
   const cwd = action.cwd ?? target;
   switch (action.id) {
     case "yarn-setup": {
@@ -396,7 +397,8 @@ async function dispatchAction(action, target, platform, json, preflightMode = "f
       return spawnScriptStreaming(
         leaf,
         withWatcherPort(["--target", cwd, ...extra], watcherPort),
-        target
+        target,
+        { MM_HARNESS_METRO_ENV_FINGERPRINT: metroEnvFingerprint ?? mobileMetroEnvCheck(path.resolve(target)).fingerprint }
       );
     }
     case "start-console-forwarder": {

package/dist/adapters/mobile/runtime-decision.js

@@ -184,7 +184,9 @@ async function decideMobileReadiness(target, options = {}) {
       env.status === "missing" ? "Metro environment has no successful bundle baseline; restart Metro to load the current environment without clearing its transform cache." : "Metro environment inputs changed since the successful bundle baseline; restart Metro without clearing its transform cache. Pass --clear-metro only if stale transforms are observed.",
       ...report.reasons
     ],
-    actions: report.decision === "ready" ? launchActions(resolved) : report.actions
+    actions: (report.decision === "ready" ? launchActions(resolved) : report.actions).map(
+      (action) => action.id === "start-metro" && !action.argv?.includes("--clear") && !action.argv?.includes("--restart") ? { ...action, argv: [...action.argv ?? [], "--restart"] } : action
+    )
   };
 }
 function writeDepsNote(resolved) {

package/dist/adapters/mobile/verify.js

@@ -1,7 +1,8 @@
-import { execFileSync, spawnSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { spawnScriptStreaming } from "../../commands/shared.js";
 import { readRuntimeContextField } from "../../harness.js";
 import { recipeHarnessPath, recipeHarnessRoot, recipeRuntimeDir, runnerDir } from "../../paths.js";
 const USAGE = "Usage: mm-harness verify --adapter mobile -- [--target <metamask-mobile>] [--artifacts-dir <dir>] [--static-only] [--platform ios|android] [--preflight-mode fast|auto|default|rebuild-native|clean] [--no-auto-start]";
@@ -11,19 +12,6 @@ const AUTO_START_TRUE = ["1", "true", "TRUE", "True", "yes", "YES", "Yes", "on",
 const AUTO_START_FALSE = ["0", "false", "FALSE", "False", "no", "NO", "No", "off", "OFF", "Off", ""];
 const AUTO_START_REFUSAL = "Mobile auto-start is not allowed from product-local scripts. Start or prepare the app through the runner/slot runtime, then rerun verify with --no-auto-start.";
 const EVM_READINESS_EXPRESSION = "(async function(){try{var engine=globalThis.Engine;var controller=engine&&engine.context&&engine.context.NetworkController;if(!controller||typeof controller.getSelectedNetworkClient!=='function')throw new Error('NetworkController selected client is unavailable');var client=controller.getSelectedNetworkClient();if(!client||!client.provider||typeof client.provider.request!=='function')throw new Error('selected EVM provider is unavailable');var result=await client.provider.request({method:'eth_blockNumber'});if(typeof result!=='string'||!/^0x[0-9a-f]+$/i.test(result))throw new Error('eth_blockNumber returned an invalid result');return {ok:true,result:result};}catch(error){return {ok:false,error:error&&(error.message||String(error))};}})()";
-const STATUS_SMOKE_RECIPE = `{
-  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
-  "title": "Mobile runner status smoke",
-  "description": "Checks that the installed runner can read Mobile app status before live verification.",
-  "workflow": {
-    "entry": "status",
-    "nodes": {
-      "status": { "action": "app.status", "intent": "Read Mobile app status through the runner-owned bridge", "next": "done" },
-      "done": { "action": "end", "status": "pass" }
-    }
-  }
-}
-`;
 const LIVE_SMOKE_RECIPE = `{
   "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
   "title": "Mobile v1 runner live bridge smoke",
@@ -241,30 +229,21 @@ function mobilePortHolder(port) {
     note: "HTTP /status probing is skipped during live verify because the React Native bridge is the authoritative readiness path for Mobile."
   };
 }
-function spawnToLog(logPath, command, args, options = {}) {
+async function spawnToLog(logPath, command, args, options = {}) {
   fs.mkdirSync(path.dirname(logPath), { recursive: true });
-  const fd = fs.openSync(logPath, "w");
-  try {
-    const result = spawnSync(command, args, {
-      cwd: options.cwd,
-      env: options.env ?? process.env,
-      stdio: ["ignore", fd, fd],
-      ...options.timeoutMs === void 0 ? {} : { timeout: options.timeoutMs }
-    });
-    if (result.error) {
-      const timedOut = result.error.code === "ETIMEDOUT";
-      fs.writeSync(
-        fd,
-        timedOut ? `Timed out after ${(options.timeoutMs ?? 0) / 1e3}s: ${[command, ...args].join(" ")}
-` : `${result.error.message}
-`
-      );
-      return timedOut ? 124 : 127;
-    }
-    return result.status ?? 1;
-  } finally {
-    fs.closeSync(fd);
+  const result = await spawnScriptStreaming(command, args, options.cwd ?? process.cwd(), {
+    env: Object.fromEntries(Object.entries(options.env ?? process.env).filter((entry) => entry[1] !== void 0)),
+    timeoutMs: options.timeoutMs,
+    forward: "none",
+    stage: path.basename(logPath, ".log")
+  });
+  fs.writeFileSync(logPath, result.output);
+  if (result.error) {
+    fs.appendFileSync(logPath, `${result.error.message}
+`);
+    return 127;
   }
+  return result.timedOut ? 124 : result.status;
 }
 function readJsonFile(file) {
   try {
@@ -372,42 +351,6 @@ async function runMobileVerify(argv, io = defaultIo) {
       deviceTarget = platform === "android" ? resolveJsEnvValue(target, "ADB_SERIAL") || resolveJsEnvValue(target, "ANDROID_DEVICE") : resolveJsEnvValue(target, "IOS_SIMULATOR");
     }
     const deviceArgs = deviceTarget ? ["--device", deviceTarget] : [];
-    const statusSmokeRecipe = path.join(artifacts, "mobile-status-smoke.recipe.json");
-    const precheckLog = path.join(artifacts, "logs/app-status-precheck.log");
-    let liveRuntimeOk = false;
-    for (let attempt = 1; attempt <= 5; attempt += 1) {
-      fs.writeFileSync(statusSmokeRecipe, STATUS_SMOKE_RECIPE);
-      const code = spawnToLog(precheckLog, runnerBin, [
-        "run",
-        statusSmokeRecipe,
-        "--adapter",
-        "mobile",
-        "--target",
-        target,
-        ...deviceArgs,
-        "--watcher-port",
-        port,
-        "--artifacts-dir",
-        path.join(artifacts, "runner-status-smoke"),
-        "--json"
-      ], { cwd: target });
-      if (code === 0) {
-        liveRuntimeOk = true;
-        break;
-      }
-      const deviceNotFound = /"code"[ \t]*:[ \t]*"DEVICE_NOT_FOUND"/u.test(
-        fs.readFileSync(precheckLog, "utf8")
-      );
-      if (attempt < 5 && deviceNotFound) {
-        io.err(`Waiting for Mobile device discovery (${attempt}/5): ${deviceTarget || "configured target"}`);
-        await sleep(1e3);
-        continue;
-      }
-      break;
-    }
-    if (!liveRuntimeOk && autoStart) io.err(AUTO_START_REFUSAL);
-    checks.push(liveRuntimeOk ? { name: "mobile runtime controllable precheck", status: "pass" } : { name: "mobile runtime controllable precheck", status: "fail", detail: "see logs/app-status-precheck.log" });
-    if (!liveRuntimeOk) status = "fail";
     fixtureStatus = mobileFixtureStatus(target);
     fs.writeFileSync(path.join(artifacts, "logs/fixture-status.json"), `${JSON.stringify(fixtureStatus)}
 `);
@@ -423,12 +366,12 @@ async function runMobileVerify(argv, io = defaultIo) {
     portHolder = mobilePortHolder(port);
     fs.writeFileSync(path.join(artifacts, "logs/port-holder.json"), `${JSON.stringify(portHolder)}
 `);
-    if (status !== "fail" && portHolder.listening) {
+    if (!checks.some((check) => check.status === "fail") && portHolder.listening) {
       const waiter = path.join(runnerDir, "adapters/mobile/wait-for-bridge.sh");
       if (!fs.existsSync(waiter)) {
         addNote("Mobile bridge settle skipped: wait-for-bridge.sh not found under the runner adapters; reinstall the runner.");
       } else {
-        const waiterCode = spawnToLog(
+        const waiterCode = await spawnToLog(
           path.join(artifacts, "logs/wait-for-bridge.log"),
           "bash",
           [waiter, "--target", target, "--port", port, "--platform", platform],
@@ -446,34 +389,45 @@ async function runMobileVerify(argv, io = defaultIo) {
     fs.writeFileSync(liveSmokeRecipe, LIVE_SMOKE_RECIPE);
     const iosSimulatorResolved = resolveJsEnvValue(target, "IOS_SIMULATOR");
     const adbSerialResolved = resolveJsEnvValue(target, "ADB_SERIAL");
-    const liveSmokeCode = spawnToLog(
-      path.join(artifacts, "logs/runner-live-smoke.log"),
-      runnerBin,
-      [
-        "run",
-        liveSmokeRecipe,
-        "--adapter",
-        "mobile",
-        "--target",
-        target,
-        ...deviceArgs,
-        "--watcher-port",
-        port,
-        "--artifacts-dir",
-        path.join(artifacts, "runner-live-smoke"),
-        "--json"
-      ],
-      {
-        cwd: target,
-        env: {
-          ...process.env,
-          METAMASK_RECIPE_AUTO_HUD: "0",
-          IOS_SIMULATOR: process.env.IOS_SIMULATOR || iosSimulatorResolved,
-          ADB_SERIAL: process.env.ADB_SERIAL || adbSerialResolved,
-          ANDROID_SERIAL: process.env.ANDROID_SERIAL || adbSerialResolved
+    let liveSmokeCode = 1;
+    for (let attempt = 1; attempt <= 5; attempt += 1) {
+      liveSmokeCode = await spawnToLog(
+        path.join(artifacts, "logs/runner-live-smoke.log"),
+        runnerBin,
+        [
+          "run",
+          liveSmokeRecipe,
+          "--adapter",
+          "mobile",
+          "--target",
+          target,
+          ...deviceArgs,
+          "--watcher-port",
+          port,
+          "--artifacts-dir",
+          path.join(artifacts, "runner-live-smoke"),
+          "--json"
+        ],
+        {
+          cwd: target,
+          env: {
+            ...process.env,
+            METAMASK_RECIPE_AUTO_HUD: "0",
+            IOS_SIMULATOR: process.env.IOS_SIMULATOR || iosSimulatorResolved,
+            ADB_SERIAL: process.env.ADB_SERIAL || adbSerialResolved,
+            ANDROID_SERIAL: process.env.ANDROID_SERIAL || adbSerialResolved
+          }
         }
-      }
-    );
+      );
+      if (liveSmokeCode === 0) break;
+      const deviceNotFound = /"code"[ \t]*:[ \t]*"DEVICE_NOT_FOUND"/u.test(
+        fs.readFileSync(path.join(artifacts, "logs/runner-live-smoke.log"), "utf8")
+      );
+      if (!deviceNotFound || attempt === 5) break;
+      io.err(`Waiting for Mobile device discovery (${attempt}/5): ${deviceTarget || "configured target"}`);
+      await sleep(1e3);
+    }
+    if (liveSmokeCode !== 0 && autoStart) io.err(AUTO_START_REFUSAL);
     if (liveSmokeCode === 0) {
       checks.push({ name: "runner v1 live bridge smoke", status: "pass" });
     } else {
@@ -488,7 +442,7 @@ async function runMobileVerify(argv, io = defaultIo) {
       fs.writeFileSync(evmLog, `Mobile bridge is missing at ${bridge}
 `);
     } else {
-      const evmCode = spawnToLog(evmLog, process.execPath, [bridge, "eval-async", EVM_READINESS_EXPRESSION], {
+      const evmCode = await spawnToLog(evmLog, process.execPath, [bridge, "eval-async", EVM_READINESS_EXPRESSION], {
         timeoutMs: 25e3,
         env: {
           ...process.env,

package/dist/checkout-lock.js

@@ -1,3 +1,4 @@
+import { ensureRuntimeDirectory, processIdentity } from "@farmslot/recipe-harness/runtime/operation";
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
@@ -5,15 +6,19 @@ import { recipeRuntimeDir } from "./paths.js";
 function acquireCheckoutLock(target, operation) {
   const repoRoot = fs.realpathSync(target);
   const lockPath = path.join(repoRoot, recipeRuntimeDir(), "sandbox.lock");
-  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  ensureRuntimeDirectory(path.dirname(lockPath));
   const inheritedToken = process.env.MM_HARNESS_CHECKOUT_LOCK_TOKEN;
   for (let attempt = 0; attempt < 4; attempt += 1) {
     try {
+      const identity = processIdentity(process.pid);
+      if (!identity) throw new Error("Cannot identify checkout lock owner process");
       const fd = fs.openSync(lockPath, "wx", 384);
-      const token = inheritedToken || randomUUID();
+      fs.fchmodSync(fd, 384);
+      const token = randomUUID();
       const owner = {
         schemaVersion: 1,
         pid: process.pid,
+        processStartedAt: identity,
         operation,
         repoRoot,
         token,
@@ -22,30 +27,38 @@ function acquireCheckoutLock(target, operation) {
       fs.writeFileSync(fd, `${JSON.stringify(owner, null, 2)}
 `);
       fs.closeSync(fd);
-      if (!inheritedToken) process.env.MM_HARNESS_CHECKOUT_LOCK_TOKEN = token;
+      process.env.MM_HARNESS_CHECKOUT_LOCK_TOKEN = token;
       return {
         path: lockPath,
         release: () => {
           const current = readOwner(lockPath);
-          if (current?.pid === process.pid && current.token === token) fs.rmSync(lockPath, { force: true });
-          if (!inheritedToken && process.env.MM_HARNESS_CHECKOUT_LOCK_TOKEN === token) {
-            delete process.env.MM_HARNESS_CHECKOUT_LOCK_TOKEN;
+          if (current?.pid === process.pid && current.token === token && !childrenAlive(current)) {
+            fs.rmSync(lockPath, { force: true });
+            fs.rmSync(path.join(path.dirname(lockPath), "lock-members", token), { recursive: true, force: true });
+          }
+          if (process.env.MM_HARNESS_CHECKOUT_LOCK_TOKEN === token) {
+            if (inheritedToken) process.env.MM_HARNESS_CHECKOUT_LOCK_TOKEN = inheritedToken;
+            else delete process.env.MM_HARNESS_CHECKOUT_LOCK_TOKEN;
           }
         }
       };
     } catch (error) {
       if (error.code !== "EEXIST") throw error;
       const owner = readOwner(lockPath);
-      if (inheritedToken && owner?.token === inheritedToken && owner.repoRoot === repoRoot && typeof owner.pid === "number" && processAlive(owner.pid)) {
+      if (inheritedToken && owner?.token === inheritedToken && owner.repoRoot === repoRoot && typeof owner.pid === "number" && ownerAlive(owner)) {
+        trackCheckoutChild(repoRoot, process.pid);
         return { path: lockPath, release: () => void 0 };
       }
-      if (owner && typeof owner.pid === "number" && processAlive(owner.pid)) {
+      if (owner && typeof owner.pid === "number" && ownerAlive(owner)) {
         return {
           path: lockPath,
           owner,
           message: `checkout sandbox is busy with ${String(owner.operation ?? "another operation")} (pid ${owner.pid}).`
         };
       }
+      if (!owner || childrenAlive(owner)) {
+        return { path: lockPath, owner, message: `checkout sandbox owner is unreadable or has surviving child processes. Inspect ${lockPath} and its lock-members directory; remove the lock only after verifying all recorded processes have exited.` };
+      }
       claimStaleLock(lockPath, owner);
     }
   }
@@ -61,12 +74,14 @@ function claimStaleLock(lockPath, expectedOwner) {
   }
   try {
     const claimedOwner = readOwner(claimedPath);
-    if (!sameOwner(claimedOwner, expectedOwner) || claimedOwner && typeof claimedOwner.pid === "number" && processAlive(claimedOwner.pid)) {
+    if (!sameOwner(claimedOwner, expectedOwner) || claimedOwner && typeof claimedOwner.pid === "number" && (ownerAlive(claimedOwner) || childrenAlive(claimedOwner))) {
       try {
         fs.linkSync(claimedPath, lockPath);
       } catch (error) {
         if (error.code !== "EEXIST") throw error;
       }
+    } else if (typeof claimedOwner?.token === "string" && /^[a-f0-9-]{36}$/.test(claimedOwner.token)) {
+      fs.rmSync(path.join(path.dirname(lockPath), "lock-members", claimedOwner.token), { recursive: true, force: true });
     }
   } finally {
     fs.rmSync(claimedPath, { force: true });
@@ -84,6 +99,42 @@ function readOwner(lockPath) {
     return null;
   }
 }
+function ownerAlive(owner) {
+  if (typeof owner.pid !== "number") return true;
+  if (typeof owner.processStartedAt === "string") return processIdentity(owner.pid) === owner.processStartedAt;
+  return processAlive(owner.pid);
+}
+function childrenAlive(owner) {
+  if (typeof owner.repoRoot !== "string" || typeof owner.token !== "string" || !/^[a-f0-9-]{36}$/.test(owner.token)) return false;
+  const directory = path.join(owner.repoRoot, recipeRuntimeDir(), "lock-members", owner.token);
+  if (!fs.existsSync(directory)) return false;
+  return fs.readdirSync(directory).filter((name) => name.endsWith(".json")).some((name) => {
+    const child = readOwner(path.join(directory, name));
+    if (child && typeof child.processGroupId === "number" && child.processGroupId > 0) return processAlive(-child.processGroupId);
+    return !child || typeof child.pid !== "number" || typeof child.processStartedAt !== "string" || child.pid !== owner.pid && processIdentity(child.pid) === child.processStartedAt;
+  });
+}
+function trackCheckoutChild(target, pid, ownsProcessGroup = false) {
+  const repoRoot = fs.realpathSync(target);
+  const lockPath = path.join(repoRoot, recipeRuntimeDir(), "sandbox.lock");
+  const owner = readOwner(lockPath);
+  if (!owner || owner.token !== process.env.MM_HARNESS_CHECKOUT_LOCK_TOKEN || typeof owner.token !== "string" || !/^[a-f0-9-]{36}$/.test(owner.token)) return () => void 0;
+  const identity = processIdentity(pid);
+  if (!identity && !ownsProcessGroup) return () => void 0;
+  const directory = path.join(repoRoot, recipeRuntimeDir(), "lock-members", owner.token);
+  ensureRuntimeDirectory(directory);
+  const file = path.join(directory, `${pid}.json`);
+  const previous = readOwner(file);
+  const group = ownsProcessGroup || previous?.processStartedAt === identity && previous?.processGroupId === pid;
+  const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  fs.writeFileSync(temporary, JSON.stringify({ pid, processStartedAt: identity, ...group ? { processGroupId: pid } : {} }), { mode: 384 });
+  fs.chmodSync(temporary, 384);
+  fs.renameSync(temporary, file);
+  return () => {
+    const current = readOwner(file);
+    if (current?.pid === pid && current.processStartedAt === identity) fs.rmSync(file, { force: true });
+  };
+}
 function processAlive(pid) {
   try {
     process.kill(pid, 0);
@@ -93,5 +144,6 @@ function processAlive(pid) {
   }
 }
 export {
-  acquireCheckoutLock
+  acquireCheckoutLock,
+  trackCheckoutChild
 };

package/dist/command-contract.js

@@ -425,6 +425,7 @@ function validatePublicInvocation(argv, examples = {}) {
   }
   const { name, contract } = resolved;
   const tokens = argv.slice(1);
+  if (name === "checklist" && tokens[0] === "mark" && tokens[1] && !tokens[1].startsWith("-") && tokens[2] === "sub") return null;
   const positionals = [];
   const seenOptions = /* @__PURE__ */ new Set();
   const validOptions = Object.keys(contract.options);

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