@deeeed/metamask-harness 0.67.1 → 0.69.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## Unreleased
 
+## 0.69.0 - 2026-09-30
+
+### Changed
+
+- Group and color recipe/action listings by domain, show library origins and paths separately, and support domain/source filters and domain/name/library sorting. Keep recipe parameter details in `--describe` and `--json`.
+
+### Fixed
+
+- Accept repeated `task init --acceptance` flags at the public CLI boundary so Recipe Cook can record authored criteria in the task document and structured handoff.
+- Report Mobile launch dependency blockers once with the dependency repair command; preserve the readiness cause instead of labelling it app logic or adding a conflicting doctor hint.
+
+## 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

@@ -3,6 +3,7 @@ import path from "node:path";
 import { recordDepsBaseline } from "@farmslot/recipe-harness/runtime/deps-readiness";
 import { resolveAndExportMobileToolPaths } from "../../../library/actions/mobile/platform/tool-paths.mjs";
 import { EXIT, spawnScriptStreaming } from "../../commands/shared.js";
+import { shellQuote } from "../../commands/parse-args.js";
 import { runnerDir } from "../../paths.js";
 import {
   decideMobileReadiness,
@@ -51,12 +52,14 @@ async function prepareMobile(target, opts = {}) {
   });
   if (report.decision === "blocked") {
     const reasons = report.reasons.join(" ");
-    const next = report.userAction ?? "fix the bundle error in app code before retrying recipe up.";
+    const next = report.userAction ?? `mm-harness logs --target ${shellQuote(target)} --full`;
     const msg = `mobile prepare blocked: ${reasons}
   Next: ${next}`;
-    if (!json) process.stderr.write(`${msg}
-`);
-    return { status: EXIT.runtime, output: msg };
+    return {
+      status: EXIT.runtime,
+      output: msg,
+      readinessBlock: { reasonCode: report.reasonCode, message: reasons, userAction: next }
+    };
   }
   const iosAccessibilityChanged = platform === "ios" && report.decision !== "unknown" && enableIosAccessibility(json);
   const rebuildNative = preflightMode === "rebuild-native" || preflightMode === "clean";
@@ -270,7 +273,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 +382,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 +400,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

@@ -12,6 +12,7 @@ import {
 } from "@farmslot/recipe-harness/runtime/log-analysis";
 import { probeMetroPackager } from "@farmslot/recipe-harness/runtime/metro-probe";
 import { color } from "../../cli-color.js";
+import { shellQuote } from "../../commands/parse-args.js";
 import { recipeRuntimePath } from "../../paths.js";
 import { resolveMobileToolPath } from "../../../library/actions/mobile/platform/tool-paths.mjs";
 import { mobileProductMarkers } from "./deps-markers.js";
@@ -149,7 +150,7 @@ const launchActions = (target, clearMetro = false) => {
   return actions;
 };
 function depsInstallCommand(resolved) {
-  return fs.existsSync(path.join(resolved, "node_modules")) ? "`yarn setup:expo --no-build-ios --no-build-android`" : "`yarn install --immutable && yarn setup:expo --no-build-ios --no-build-android`";
+  return fs.existsSync(path.join(resolved, "node_modules")) ? "yarn setup:expo --no-build-ios --no-build-android" : "yarn install --immutable && yarn setup:expo --no-build-ios --no-build-android";
 }
 async function decideMobileReadiness(target, options = {}) {
   const resolved = path.resolve(target);
@@ -157,18 +158,15 @@ async function decideMobileReadiness(target, options = {}) {
   const fast = options.preflightMode === "fast";
   const report = await computeMobileReadiness(resolved, options, fast);
   if (fast && report.decision === "install") {
-    const standalone = depsInstallCommand(resolved);
     return {
       ...report,
       decision: "blocked",
       reasonCode: "deps-not-ready",
       reasons: [
-        "Fast preflight found dependencies not ready and does not install them (the orchestrator deps phase owns installation).",
-        ...report.reasons
+        ...report.reasons,
+        "Quick launch does not install dependencies."
       ],
-      userAction: `1. Standalone checkout \u2014 run ${standalone} in the checkout.
-  2. Orchestrated slot \u2014 run its deps/prepare phase.
-  After the selected action succeeds, re-run \`mm-harness launch <platform>\`.`,
+      userAction: `cd ${shellQuote(resolved)} && ${depsInstallCommand(resolved)}`,
       actions: []
     };
   }
@@ -184,12 +182,14 @@ 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) {
+function writeDepsNote() {
   const stream = process.stderr;
-  const body = `package.json/yarn.lock are newer than the node_modules install markers and no install baseline is recorded yet, so the installed node_modules are used as they are. Pulling commits refreshes those timestamps without changing dependencies, and a required-dependency presence check still runs, so this on its own is not evidence that anything drifted. Act only if you know dependencies changed: run ${depsInstallCommand(resolved)} once \u2014 that refreshes the markers, and \`mm-harness prepare\` records a baseline when it runs the install, so this note stops.`;
+  const body = "No install baseline is recorded. Required package checks passed; timestamps alone do not establish dependency drift. Reusing the installed dependencies.";
   stream.write(
     `
 ${color("warn", "mm-harness note (deps):", { stream })} ${color("dim", body, { stream })}
@@ -204,7 +204,6 @@ async function computeMobileReadiness(resolved, options, fast) {
   let deps = rawDeps;
   if (rawDeps.status === "stale" && !rawDeps.hasBaseline) {
     deps = { installed: rawDeps.installed, status: "current", hasBaseline: false };
-    writeDepsNote(resolved);
   }
   if (deps.status === "current") {
     const absent = missingRequiredDeps(resolved);
@@ -323,6 +322,7 @@ async function computeMobileReadiness(resolved, options, fast) {
       actions: installActions(resolved)
     };
   }
+  if (rawDeps.status === "stale" && !rawDeps.hasBaseline) writeDepsNote();
   if (metro.status === "down") {
     return {
       schemaVersion: 1,

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

@@ -168,6 +168,7 @@ const PUBLIC_COMMAND_CONTRACTS = {
       "--title": value(),
       "--task-text": value(),
       "--task-file": value(),
+      "--acceptance": value(),
       "--ticket": value(),
       "--source-ref": value(),
       "--surface": value(),
@@ -241,6 +242,9 @@ const PUBLIC_COMMAND_CONTRACTS = {
   call: {
     options: options(HELP, JSON, TARGET, ADAPTER, MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, RECIPE_RUNTIME, {
       "--list": bool(),
+      "--domain": value(),
+      "--source": value(),
+      "--sort": value(["domain", "name", "library"]),
       "--arg": value()
     }),
     positionals: [{ label: "action" }],
@@ -253,6 +257,9 @@ const PUBLIC_COMMAND_CONTRACTS = {
   run: {
     options: options(HELP, JSON, JSON_STREAM, TARGET, ADAPTER, MOBILE_PLATFORM, DEVICE, RUNTIME_PORTS, RECIPE_RUNTIME, RUN_FUNDING, {
       "--list": bool(),
+      "--domain": value(),
+      "--source": value(),
+      "--sort": value(["domain", "name", "library"]),
       "--plan": bool(),
       "--proof": bool(),
       "--describe": bool(),
@@ -425,6 +432,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);