@deeeed/metamask-harness 0.50.6 → 0.51.1

package/adapters/extension/live.sh

@@ -228,6 +228,7 @@ NODE
   quoted_check_infura="$(printf '%q' "$SCRIPT_DIR/check-infura-readiness.cjs")"
   quoted_stamp_title="$(printf '%q' "$SCRIPT_DIR/stamp-runtime-title.cjs")"
   quoted_chrome_launcher="$(printf '%q' "$SCRIPT_DIR/launch-browser.cjs")"
+  quoted_build_handoff="$(printf '%q' "$SCRIPT_DIR/build-handoff.cjs")"
   quoted_artifact_state="$(printf '%q' "$SCRIPT_DIR/artifact-runtime-state.cjs")"
   quoted_fixture_state="$(printf '%q' "$FIXTURE_STATE_ABS")"
   quoted_fixture_validation="$(printf '%q' "$FIXTURE_VALIDATION_ABS")"
@@ -352,6 +353,7 @@ NODE
   fi
   prepare_parts+=("$chrome_launch_cmd")
   prepare_parts+=("for i in {1..60}; do curl -fsS --max-time 1 http://127.0.0.1:${CDP_PORT}/json/version >/dev/null 2>&1 && break; sleep 1; done; curl -fsS --max-time 1 http://127.0.0.1:${CDP_PORT}/json/version >/dev/null")
+  prepare_parts+=("node ${quoted_build_handoff} --target ${quoted_target} --runtime-dist ${quoted_runtime_dist} --cdp-port ${CDP_PORT}")
   if [ -n "$WALLET_FIXTURE_ABS" ]; then
     prepare_parts+=("bash ${quoted_seed_fixture} seed-cdp --target ${quoted_target} --fixture ${quoted_wallet_fixture} --state ${quoted_fixture_state} --cdp-port ${CDP_PORT} --extension-dir ${quoted_runtime_dist} --extension-id-file ${quoted_extension_id_file} --out ${quoted_fixture_validation}")
   fi

package/adapters/extension/stop-viewers.sh

@@ -29,6 +29,7 @@ done
 unset _tv_src
 
 runtime_dir="$TARGET/$(recipe_runtime_dir)"
+console_log="$runtime_dir/extension-console.log"
 set +e
 
 if command -v tmux_viewer_close_marker >/dev/null 2>&1; then
@@ -47,7 +48,7 @@ ps -axo pid=,command= 2>/dev/null | while read -r pid command; do
     *) continue ;;
   esac
   case "$command" in
-    *"$runtime_dir/"*) kill "$pid" 2>/dev/null || true ;;
+    *"--log $console_log"*|*"$console_log"*) kill "$pid" 2>/dev/null || true ;;
   esac
 done
 

package/adapters/mobile/open-device.sh

@@ -126,6 +126,31 @@ source() {
   mm_harness_restore_build_target
   return "$status"
 }
+# The harness owns Metro on WATCHER_PORT. Expo's own bundler management
+# re-checks that port after the build with lsof under a 350 ms budget, which a
+# loaded machine misses, and then aborts with "Port became busy". Build only:
+# --no-bundler, which Expo refuses next to --port, so the port argument goes.
+mm_harness_expo_build_args() {
+  local arg skip=false
+  MM_HARNESS_EXPO_ARGS=()
+  for arg in "$@"; do
+    if [ "$skip" = true ]; then skip=false; continue; fi
+    case "$arg" in
+      --port) skip=true; continue ;;
+      --port=*) continue ;;
+    esac
+    MM_HARNESS_EXPO_ARGS+=("$arg")
+  done
+  MM_HARNESS_EXPO_ARGS+=(--no-bundler)
+}
+yarn() {
+  if [ "${1:-}" = expo ] && [ "${2:-}" = run:ios ]; then
+    mm_harness_expo_build_args "$@"
+    command yarn "${MM_HARNESS_EXPO_ARGS[@]}"
+  else
+    command yarn "$@"
+  fi
+}
 mm_harness_restore_build_target
 BUILD_ENV
   } > "$build_env"
@@ -317,9 +342,24 @@ source() {
   mm_harness_restore_android_build_target
   return "$status"
 }
+# --no-bundler without --port: the harness owns Metro on WATCHER_PORT (see the
+# iOS build env for why).
+mm_harness_expo_build_args() {
+  local arg skip=false
+  MM_HARNESS_EXPO_ARGS=()
+  for arg in "$@"; do
+    if [ "$skip" = true ]; then skip=false; continue; fi
+    case "$arg" in
+      --port) skip=true; continue ;;
+      --port=*) continue ;;
+    esac
+    MM_HARNESS_EXPO_ARGS+=("$arg")
+  done
+}
 yarn() {
   if [ "${1:-}" = expo ] && [ "${2:-}" = run:android ]; then
-    command yarn "$@" "$MM_HARNESS_BUILD_ANDROID_EXPO_DEVICE"
+    mm_harness_expo_build_args "$@"
+    command yarn "${MM_HARNESS_EXPO_ARGS[@]}" "$MM_HARNESS_BUILD_ANDROID_EXPO_DEVICE" --no-bundler
   else
     command yarn "$@"
   fi

package/adapters/mobile/verify.sh

@@ -414,6 +414,30 @@ if [ "$STATIC_ONLY" = false ]; then
 
   port_holder_json "$port" > "$ARTIFACTS/logs/port-holder.json"
 
+  # Right after a launch or a fixture unlock the app's JS thread can stay busy
+  # for a while (account hydration); a single CDP probe then times out although
+  # the runtime is healthy. When Metro holds the port, let wait-for-bridge
+  # absorb that settle before the smoke. Best effort and bounded: the smoke
+  # below is the check that counts. The installed overlay carries only this
+  # script, so the waiter is resolved from the runner source it was installed
+  # from.
+  if [ "$status" != "fail" ] && node -e 'process.exit(JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).listening ? 0 : 1)' "$ARTIFACTS/logs/port-holder.json" 2>/dev/null; then
+    wait_sh=""
+    for candidate in "$SCRIPT_DIR/wait-for-bridge.sh" "$(cat "$HARNESS_DIR/runner/.runner-source" 2>/dev/null || true)/adapters/mobile/wait-for-bridge.sh"; do
+      [ -f "$candidate" ] && { wait_sh="$candidate"; break; }
+    done
+    if [ -z "$wait_sh" ]; then
+      add_note "Mobile bridge settle skipped: wait-for-bridge.sh not found beside verify.sh or under runner/.runner-source; reinstall the runner."
+    elif MOBILE_BRIDGE_READY_TIMEOUT_MS="${MOBILE_BRIDGE_READY_TIMEOUT_MS:-90000}" \
+      MOBILE_BRIDGE_UNRESPONSIVE_GRACE_MS="${MOBILE_BRIDGE_UNRESPONSIVE_GRACE_MS:-90000}" \
+      bash "$wait_sh" --target "$TARGET" --port "$port" --platform "$PLATFORM" \
+      > "$ARTIFACTS/logs/wait-for-bridge.log" 2>&1; then
+      add_note "Mobile bridge settled before the live smoke (logs/wait-for-bridge.log)."
+    else
+      add_note "Mobile bridge settle did not complete (waiter exit $?); running the live smoke anyway (logs/wait-for-bridge.log)."
+    fi
+  fi
+
   cat > "$ARTIFACTS/mobile-v1-live-smoke.recipe.json" <<'JSON'
 {
   "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",

package/dist/adapters/extension/validation-process-ownership.js

@@ -3,9 +3,8 @@ const require2 = createRequire(import.meta.url);
 const processOwnership = require2(
   "../../../adapters/extension/lib/validation-process-ownership.cjs"
 );
-const { profileProcessPids, stopProfileProcesses, stopProfileProcessesSync } = processOwnership;
+const { profileProcessPids, stopProfileProcesses } = processOwnership;
 export {
   profileProcessPids,
-  stopProfileProcesses,
-  stopProfileProcessesSync
+  stopProfileProcesses
 };

package/dist/adapters/slot-ports.js

@@ -1,6 +1,5 @@
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { recipeRuntimeDir } from "../paths.js";
 import {
@@ -132,53 +131,11 @@ function stopExtensionWatcher(target) {
   }
   return ownedPids.length;
 }
-function commandFlagValue(command, flag) {
-  const escaped = escapeRegex(flag);
-  const patterns = [
-    new RegExp(`(?:^|\\s)${escaped}=([^\\s"]+)`, "u"),
-    new RegExp(`(?:^|\\s)${escaped}="([^"]+)"`, "u"),
-    new RegExp(`(?:^|\\s)${escaped}='([^']+)'`, "u"),
-    new RegExp(`(?:^|\\s)${escaped}\\s+([^\\s"]+)`, "u")
-  ];
-  for (const pattern of patterns) {
-    const match = pattern.exec(command);
-    if (match?.[1]) return match[1];
-  }
-  return null;
-}
-function pathIsInsideDir(candidate, root) {
-  const resolved = path.resolve(candidate);
-  const base = path.resolve(root);
-  return resolved === base || resolved.startsWith(`${base}${path.sep}`);
-}
-function chromeUserDataDirOwnedByCheckout(command, runtimeAbs) {
-  const value = commandFlagValue(command, "--user-data-dir");
-  if (!value) return false;
-  return pathIsInsideDir(value, runtimeAbs);
-}
-function commandLoadsCheckoutExtension(command, targetAbs) {
-  const loaded = commandFlagValue(command, "--load-extension") ?? commandFlagValue(command, "--disable-extensions-except");
-  if (!loaded) return false;
-  return pathIsInsideDir(loaded, targetAbs);
-}
-function isSharedOrDefaultBrowserProfile(profile) {
-  const resolved = path.resolve(profile);
-  const home = os.homedir();
-  const osDefaults = [
-    path.join(home, "Library/Application Support/Google/Chrome"),
-    path.join(home, "Library/Application Support/Chromium"),
-    path.join(home, "Library/Application Support/Microsoft Edge"),
-    path.join(home, ".config/google-chrome"),
-    path.join(home, ".config/chromium"),
-    path.join(home, ".config/microsoft-edge")
-  ];
-  const underDefault = (dir) => resolved === dir || resolved.startsWith(`${dir}${path.sep}`);
-  return resolved === home || resolved.includes(`${path.sep}.chrome-farmslot`) || osDefaults.some(underDefault);
-}
 function stopExtensionRuntime(target) {
   const resolved = path.resolve(target);
   const runtimeAbs = path.join(resolved, recipeRuntimeDir());
-  const extraProfile = process.env.CHROME_USER_DATA_DIR ? path.resolve(process.env.CHROME_USER_DATA_DIR) : null;
+  const configuredProfile = process.env.CHROME_USER_DATA_DIR || path.join(runtimeAbs, process.env.RECIPE_CHROME_PROFILE_NAME || "chrome-profile");
+  const profiles = process.env.CHROME_USER_DATA_DIR ? [path.resolve(configuredProfile)] : [configuredProfile, path.join(runtimeAbs, "chrome-profile-recipe"), path.join(runtimeAbs, "chrome-profile-pw")].map((value) => path.resolve(value));
   let signalled = stopExtensionWatcher(resolved);
   const ownedBrowserPids = /* @__PURE__ */ new Set();
   try {
@@ -187,16 +144,7 @@ function stopExtensionRuntime(target) {
       const match = /^\s*(\d+)\s+(.*)$/u.exec(line);
       if (!match) continue;
       const pid = Number(match[1]);
-      if (pid === process.pid) continue;
-      if (chromeUserDataDirOwnedByCheckout(match[2], runtimeAbs)) {
-        ownedBrowserPids.add(pid);
-        continue;
-      }
-      if (!extraProfile || pathIsInsideDir(extraProfile, runtimeAbs) || isSharedOrDefaultBrowserProfile(extraProfile)) continue;
-      const configured = commandFlagValue(match[2], "--user-data-dir");
-      if (configured && path.resolve(configured) === extraProfile && commandLoadsCheckoutExtension(match[2], resolved)) {
-        ownedBrowserPids.add(pid);
-      }
+      if (pid !== process.pid && profiles.some((profile) => commandHasExactArg(match[2], "--user-data-dir", profile))) ownedBrowserPids.add(pid);
     }
   } catch {
   }
@@ -255,16 +203,22 @@ function processAlive(pid) {
     return error.code === "EPERM";
   }
 }
+function commandHasExactArg(command, flag, value) {
+  const escapedFlag = escapeRegex(flag);
+  const escapedValue = escapeRegex(value);
+  return [
+    new RegExp(`(?:^|\\s)${escapedFlag}=${escapedValue}(?=\\s|$)`, "u"),
+    new RegExp(`(?:^|\\s)${escapedFlag}="${escapedValue}"(?=\\s|$)`, "u"),
+    new RegExp(`(?:^|\\s)${escapedFlag}='${escapedValue}'(?=\\s|$)`, "u"),
+    new RegExp(`(?:^|\\s)${escapedFlag}\\s+${escapedValue}(?=\\s|$)`, "u")
+  ].some((pattern) => pattern.test(command));
+}
 function escapeRegex(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
 export {
   applyKVLines,
-  chromeUserDataDirOwnedByCheckout,
-  commandFlagValue,
   isExtensionWatcherLive,
-  isSharedOrDefaultBrowserProfile,
-  pathIsInsideDir,
   resolveExtensionSlotPorts,
   resolveMobileSlotPorts,
   stopExtensionRuntime,

package/dist/cli-commands.js

@@ -25,7 +25,8 @@ const SPEC = {
     { name: "execution-template", desc: "Discover and materialize shared agent checklists", args: ["list", "materialize", "lint", "new"], flags: ["--dir", "--domain-dir", "--project-worker", "--project-name", "--package-templates", "--package-id", "--flow", "--run-mode", "--platform", "--domain", "--id", "--provenance", "--include-shadowed", "--no-include-shadowed", "--title", "--force", "--json"] },
     { name: "recipe-quality", desc: "Build the recipe-quality artifact from compact JSON", args: ["build"], flags: ["--input", "--output", "--json"] },
     { name: "interactive", aliases: ["menu"], desc: "Interactive command menu" },
-    { name: "prepare", desc: "Install harness (+ optional validate)", flags: ["--target", "--runtime-dir", "--json"] },
+    { name: "prepare", desc: "Run the readiness chain and write the readiness record", flags: ["--target", "--platform", "--mobile-platform", "--artifacts-dir", "--runtime-dir", "--json"] },
+    { name: "task", desc: "Create a task directory from a shared execution template", args: ["init"], flags: ["--flow", "--run-mode", "--platform", "--template", "--title", "--task-text", "--task-file", "--ticket", "--source-ref", "--surface", "--project", "--repo", "--attempt-id", "--var", "--task-dir-label", "--mode-preamble", "--addendum-file", "--mark-command", "--dir", "--domain-dir", "--project-worker", "--project-name", "--package-templates", "--package-id", "--domain", "--json"] },
     { name: "runtime-status", desc: "Structured runtime status JSON", flags: ["--json", "--target", "--cdp-port", "--runtime-dir"] }
   ],
   extension: [

package/dist/cli.js

@@ -22,6 +22,8 @@ import { handleStatus } from "./commands/status.js";
 import { handleCheck } from "./commands/check.js";
 import { handleChecklist } from "./commands/checklist.js";
 import { handleExecutionTemplate } from "./commands/execution-template.js";
+import { handlePrepare } from "./commands/prepare.js";
+import { handleTaskInit } from "./commands/task-init.js";
 import { handleLast } from "./commands/last.js";
 import { parseArgs, targetPath } from "./commands/parse-args.js";
 const COMMANDS = {
@@ -127,6 +129,8 @@ async function main(argv) {
   if (command === "check") return handleCheck(argv.slice(1));
   if (command === "checklist") return handleChecklist(argv.slice(1));
   if (command === "execution-template") return handleExecutionTemplate(argv.slice(1));
+  if (command === "task") return handleTaskInit(argv.slice(1));
+  if (command === "prepare") return handlePrepare(argv.slice(1));
   if (command === "last") return handleLast(parseArgs(argv.slice(1), command));
   const handler = COMMANDS[command];
   if (!handler) throw new Error(`Unknown command: ${command}`);

package/dist/command-contract.js

@@ -113,6 +113,49 @@ const PUBLIC_COMMAND_CONTRACTS = {
     ],
     minimumPositionals: 2
   },
+  prepare: {
+    usage: "mm-harness prepare [--target <checkout>] [--platform mobile|extension|core] [--mobile-platform ios|android] [--artifacts-dir <dir>] [--json]",
+    options: options(HELP, JSON, TARGET, {
+      "--platform": value(["mobile", "extension", "core"]),
+      "--mobile-platform": value(["ios", "android"]),
+      "--artifacts-dir": value()
+    })
+  },
+  task: {
+    usage: "mm-harness task init <task-dir> --flow f --run-mode m --template id --title t [options]",
+    options: options(HELP, JSON, {
+      "--flow": value(),
+      "--run-mode": value(["autonomous", "interactive", "validation"]),
+      "--platform": value(),
+      "--template": value(),
+      "--title": value(),
+      "--task-text": value(),
+      "--task-file": value(),
+      "--ticket": value(),
+      "--source-ref": value(),
+      "--surface": value(),
+      "--project": value(),
+      "--repo": value(),
+      "--attempt-id": value(),
+      "--var": value(),
+      "--task-dir-label": value(),
+      "--mode-preamble": value(),
+      "--addendum-file": value(),
+      "--mark-command": value(),
+      "--dir": value(),
+      "--domain-dir": value(),
+      "--project-worker": value(),
+      "--project-name": value(),
+      "--package-templates": value(),
+      "--package-id": value(),
+      "--domain": value()
+    }),
+    positionals: [
+      { label: "action", choices: ["init"] },
+      { label: "task-dir" }
+    ],
+    minimumPositionals: 2
+  },
   "execution-template": {
     usage: "mm-harness execution-template <list|materialize|lint|new> [target] [options]",
     options: options(HELP, JSON, {

package/dist/commands/checklist.js

@@ -7,6 +7,9 @@ const require2 = createRequire(import.meta.url);
 const MARK_SCRIPT = require2.resolve(
   "@farmslot/agent-runtime/scripts/mark-checklist-step.cjs"
 );
+const { resolveChecklistPaths } = require2(
+  "@farmslot/agent-runtime/scripts/checklist-target.cjs"
+);
 const USAGE = "mm-harness checklist <mark <task-dir> <step> | closeout <task-dir>> [options]";
 const CHECKLIST_VALUE_OPTIONS = /* @__PURE__ */ new Set([
   "--reason",
@@ -98,16 +101,14 @@ function stageLearningPackage(taskDir, step, markArgs) {
   );
 }
 function terminalSignalStatus(taskDir) {
+  const { signalPath } = resolveChecklistPaths(taskDir);
+  let signal;
   try {
-    const target = JSON.parse(
-      fs.readFileSync(path.join(taskDir, "checklist-target.json"), "utf8")
-    );
-    const signalPath = path.resolve(taskDir, target.signal ?? "SIGNAL.json");
-    const signal = JSON.parse(fs.readFileSync(signalPath, "utf8"));
-    return signal.status === "complete" || signal.status === "blocked" ? signal.status : null;
+    signal = JSON.parse(fs.readFileSync(signalPath, "utf8"));
   } catch {
     return null;
   }
+  return signal.status === "complete" || signal.status === "blocked" ? signal.status : null;
 }
 function preserveTerminalSignal(taskDir, step) {
   if (step !== "start" && numericMarkStep(step) === null) return false;
@@ -122,16 +123,6 @@ function numericMarkStep(step) {
   const stepNumber = Number(step);
   return Number.isInteger(stepNumber) && stepNumber >= 1 ? stepNumber : null;
 }
-function checklistPath(taskDir) {
-  try {
-    const target = JSON.parse(
-      fs.readFileSync(path.join(taskDir, "checklist-target.json"), "utf8")
-    );
-    return path.resolve(taskDir, target.checklist ?? "CHECKLIST.md");
-  } catch {
-    return path.join(taskDir, "CHECKLIST.md");
-  }
-}
 function checklistStepRequiresDiffPass(checklist, stepNumber) {
   let inFence = false;
   let seen = 0;
@@ -151,9 +142,10 @@ function checklistStepRequiresDiffPass(checklist, stepNumber) {
 function checkDiffGateReady(taskDir, step) {
   const stepNumber = numericMarkStep(step);
   if (stepNumber === null) return true;
+  const { taskPath } = resolveChecklistPaths(taskDir);
   let checklist = "";
   try {
-    checklist = fs.readFileSync(checklistPath(taskDir), "utf8");
+    checklist = fs.readFileSync(taskPath, "utf8");
   } catch {
     return true;
   }

package/dist/commands/prepare.js

@@ -0,0 +1,236 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import {
+  READINESS_RECORD
+} from "@farmslot/protocol";
+import { runnerProvenance } from "../doctor.js";
+import { detectAdapter } from "../harness.js";
+import { harnessExecutable, manifestPath, recipeRuntimeDir } from "../paths.js";
+import { optionFlag, optionString, parseArgs, targetPath, usageError } from "./parse-args.js";
+import { EXIT } from "./shared.js";
+const USAGE = "mm-harness prepare [--target <checkout>] [--platform mobile|extension|core] [--mobile-platform ios|android] [--artifacts-dir <dir>] [--json]";
+const REPORT_DIR = "prepare";
+const SKIPPED_AFTER_FAILURE = "previous step failed";
+function reportPathFor(id) {
+  return path.join(REPORT_DIR, `${id}.json`);
+}
+function reportedError(stdout) {
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout ?? "");
+  } catch {
+    return void 0;
+  }
+  const message = parsed?.error?.message;
+  return typeof message === "string" && message ? message : void 0;
+}
+function skippedStep(id, command, reason) {
+  return { id, command, status: "skipped", exitCode: 0, reason };
+}
+const STEP_MARK = { pass: "\u2713", fail: "\u2717", skipped: "\u2013" };
+function stepLine(step) {
+  return `${STEP_MARK[step.status]} ${step.id}: ${step.status}${step.reason ? ` \u2014 ${step.reason}` : ""}`;
+}
+function runStep(executable, target, artifactsDir, id, args, { json }) {
+  const command = [executable, ...args].join(" ");
+  const result = spawnSync(executable, [...args], {
+    cwd: target,
+    encoding: "utf8",
+    // The update nudge is an interactive courtesy; it has no place in the
+    // stream a recorded readiness step captures.
+    env: { ...process.env, MM_HARNESS_NO_UPDATE_CHECK: "1" }
+  });
+  if (result.error) {
+    return { id, command, status: "fail", exitCode: 1, reason: result.error.message };
+  }
+  const report = reportPathFor(id);
+  const file = path.join(artifactsDir, report);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, result.stdout ?? "");
+  const exitCode = result.status ?? 1;
+  if (exitCode === 0) {
+    return { id, command, status: "pass", exitCode, reportPath: report };
+  }
+  if (!json && result.stderr) process.stderr.write(result.stderr);
+  return {
+    id,
+    command,
+    status: "fail",
+    exitCode,
+    reportPath: report,
+    reason: reportedError(result.stdout) ?? `exited ${exitCode}`
+  };
+}
+function readDevices(artifactsDir) {
+  const file = path.join(artifactsDir, reportPathFor("status"));
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return [];
+  }
+  const devices = parsed?.devices;
+  return Array.isArray(devices) ? devices : [];
+}
+function readRuntimeContextTarget(target) {
+  const file = path.join(target, recipeRuntimeDir(), "agentic-runtime.json");
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return {};
+  }
+  const record = parsed ?? {};
+  const str = (key) => typeof record[key] === "string" ? record[key] : void 0;
+  return { simulator: str("simulator"), simulatorUdid: str("simulatorUdid"), adbSerial: str("adbSerial") };
+}
+function mobilePlatformFromConfiguredTarget(env, context) {
+  const ios = Boolean(env.IOS_SIMULATOR || env.SIM_UDID || context.simulator || context.simulatorUdid);
+  const android = Boolean(
+    env.ADB_SERIAL || env.ANDROID_SERIAL || env.ANDROID_TARGET_DEVICE_NAME || env.ANDROID_DEVICE || context.adbSerial
+  );
+  if (ios === android) return void 0;
+  return ios ? "ios" : "android";
+}
+function mobilePlatformFromDevices(devices) {
+  const selected = devices.filter((device) => device?.selected === true);
+  const candidates = selected.length > 0 ? selected : devices;
+  const platforms = [
+    ...new Set(
+      candidates.map((device) => device?.platform).filter((value) => value === "ios" || value === "android")
+    )
+  ];
+  return platforms.length === 1 ? platforms[0] : void 0;
+}
+function mobileTargetAmbiguityError() {
+  const choices = [
+    "1. iOS     mm-harness prepare --platform mobile --mobile-platform ios",
+    "2. Android mm-harness prepare --platform mobile --mobile-platform android"
+  ];
+  return {
+    code: "PREPARE_MOBILE_TARGET_AMBIGUOUS",
+    message: "could not infer the mobile target from the connected devices",
+    userAction: `choose the mobile target, then rerun this command:
+${choices.join("\n")}`
+  };
+}
+function ambiguousMobileTarget(json) {
+  const { code, message, userAction } = mobileTargetAmbiguityError();
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          command: "prepare",
+          status: "fail",
+          exitCode: EXIT.runtime,
+          error: { code, message, userAction }
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    console.error(`\u2717 mm-harness prepare: ${message}`);
+    console.error(`  Next: ${userAction}`);
+  }
+  return EXIT.runtime;
+}
+function mobilePlatformOption(value) {
+  if (value === void 0) return void 0;
+  if (value === "ios") return "ios";
+  if (value === "android") return "android";
+  throw usageError(
+    `--mobile-platform must be ios or android; received '${value}'
+  Next: ${USAGE}`
+  );
+}
+function resolvePlatform(requested, target) {
+  const platform = requested ?? detectAdapter(target);
+  if (platform === "mobile" || platform === "extension" || platform === "core") {
+    return platform;
+  }
+  throw usageError(
+    `could not detect the platform of ${target}
+  Next: ${USAGE}`
+  );
+}
+async function handlePrepare(argv) {
+  const { options } = parseArgs(argv, "prepare");
+  const json = optionFlag(options, "json");
+  const target = targetPath(options);
+  const platform = resolvePlatform(optionString(options, "platform"), target);
+  const artifactsDir = path.resolve(
+    optionString(options, "artifactsDir") ?? path.join(target, recipeRuntimeDir())
+  );
+  const executable = harnessExecutable();
+  const targetArgs = ["--target", target];
+  let mobilePlatform = mobilePlatformOption(optionString(options, "mobilePlatform"));
+  const steps = [];
+  const failed = () => steps.some((step) => step.status === "fail");
+  const addStep = (step) => {
+    steps.push(step);
+    if (!json) console.log(stepLine(step));
+    return step;
+  };
+  const run = (id, args) => addStep(
+    failed() ? skippedStep(id, [executable, ...args].join(" "), SKIPPED_AFTER_FAILURE) : runStep(executable, target, artifactsDir, id, args, { json })
+  );
+  run("doctor", ["doctor", "--fix", "--json", "--adapter", platform, ...targetArgs]);
+  run("status", ["status", "--json", ...targetArgs]);
+  if (platform === "mobile" && !mobilePlatform && !failed()) {
+    mobilePlatform = mobilePlatformFromConfiguredTarget(process.env, readRuntimeContextTarget(target)) ?? mobilePlatformFromDevices(readDevices(artifactsDir));
+    if (!mobilePlatform) return ambiguousMobileTarget(json);
+  }
+  if (platform === "core") {
+    const reason = "core is headless: no app surface to launch or seed";
+    addStep(skippedStep("launch", `${executable} launch`, reason));
+    addStep(skippedStep("fixtures", `${executable} fixtures set`, reason));
+  } else if (platform === "mobile") {
+    const device = mobilePlatform ? [mobilePlatform] : [];
+    run("launch", ["launch", ...device, "--verify", "--json", ...targetArgs]);
+    run("fixtures", [
+      "fixtures",
+      "set",
+      ...mobilePlatform ? ["--platform", mobilePlatform] : [],
+      "--json",
+      ...targetArgs
+    ]);
+  } else {
+    run("launch", ["launch", "--verify", "--json", ...targetArgs]);
+    run("fixtures", ["fixtures", "set", "--json", ...targetArgs]);
+  }
+  run("verify", ["verify", "--json", "--adapter", platform, ...targetArgs]);
+  const provenance = runnerProvenance(manifestPath(platform));
+  const record = {
+    schemaVersion: 1,
+    harness: {
+      name: provenance.packageName,
+      version: provenance.version,
+      source: `${provenance.installKind}/${provenance.packageSource}`,
+      executable: provenance.executablePath
+    },
+    platform,
+    ...mobilePlatform ? { mobilePlatform } : {},
+    steps,
+    ready: steps.every((step) => step.status !== "fail"),
+    recordedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  const recordPath = path.join(artifactsDir, READINESS_RECORD);
+  fs.mkdirSync(artifactsDir, { recursive: true });
+  fs.writeFileSync(recordPath, `${JSON.stringify(record, null, 2)}
+`);
+  if (json) {
+    console.log(JSON.stringify(record, null, 2));
+  } else {
+    console.log(`readiness record: ${recordPath}`);
+  }
+  return record.ready ? EXIT.ok : EXIT.runtime;
+}
+export {
+  handlePrepare,
+  mobilePlatformFromConfiguredTarget,
+  mobilePlatformFromDevices,
+  mobileTargetAmbiguityError
+};

package/dist/commands/task-init.js

@@ -0,0 +1,51 @@
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { detectAdapter } from "../harness.js";
+import { harnessExecutable } from "../paths.js";
+import { EXIT } from "./shared.js";
+const require2 = createRequire(import.meta.url);
+const USAGE = "mm-harness task init <task-dir> --flow f --run-mode m --template id --title t [options]";
+function hasOption(argv, name) {
+  return argv.some((arg) => arg === name || arg.startsWith(`${name}=`));
+}
+function metamaskDefaults(argv) {
+  const defaults = [];
+  if (!hasOption(argv, "--surface")) defaults.push("--surface", "skill");
+  if (!hasOption(argv, "--mark-command")) {
+    defaults.push("--mark-command", `${harnessExecutable()} checklist mark`);
+  }
+  if (!hasOption(argv, "--platform")) {
+    const adapter = detectAdapter(process.cwd());
+    if (adapter) defaults.push("--platform", adapter);
+  }
+  return defaults;
+}
+async function handleTaskInit(argv) {
+  if (argv[0] !== "init") {
+    console.error(`usage: ${USAGE}`);
+    return EXIT.usage;
+  }
+  const forwarded = argv.slice(1);
+  let entrypoint;
+  try {
+    entrypoint = require2.resolve("@farmslot/agent-runtime/scripts/task-init-cli.mjs");
+  } catch (error) {
+    console.error(
+      `mm-harness task init: installed @farmslot/agent-runtime does not expose the task-directory command: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return EXIT.runtime;
+  }
+  const result = spawnSync(
+    process.execPath,
+    [entrypoint, ...forwarded, ...metamaskDefaults(forwarded)],
+    { env: process.env, stdio: "inherit" }
+  );
+  if (result.error) {
+    console.error(`mm-harness task init: ${result.error.message}`);
+    return EXIT.runtime;
+  }
+  return result.status ?? EXIT.runtime;
+}
+export {
+  handleTaskInit
+};