@deeeed/metamask-harness 0.50.5 → 0.51.0

package/CHANGELOG.md

@@ -2,12 +2,18 @@
 
 ## Unreleased
 
-## 0.50.5 - 2026-09-10
+## 0.51.0 - 2026-09-13
 
-### Fixed
+### Added
+
+- `mm-harness task init` writes the task directory (task document, checklist, mark shim, and inputs) from a shared execution template, with the MetaMask surface, harness-gated mark command, and detected platform applied by default.
+- `mm-harness prepare` runs the readiness chain for a checkout (`doctor --fix`, `status`, launch, fixtures, `verify`), stops at the first failure, and records one readiness record at `<artifacts-dir>/sandbox.json` with a per-step report.
+
+### Changed
 
-- Avoid disabling and re-enabling the Extension after a fresh browser launch, which could cause `No SW` storage errors in reused wallet profiles. Keep build handoff for updates in an already-running browser.
-- Keep the previously focused macOS app in front while Chrome starts, instead of restoring only after CDP is up. Do not let caffeinate declare user activity during that launch.
+- Pin the getting-started iOS simulator to the checkout runtime file, and stop the setup prompt from auto-creating a disposable wallet.
+- Resolve the checklist a mark targets through the agent runtime: a missing `checklist-target.json` now means the default checklist and signal instead of silently disabling the terminal-signal guard, and an invalid one raises its own error.
+- Require `@farmslot/agent-runtime` 0.9.0 and `@farmslot/protocol` 0.26.0.
 
 ## 0.50.4 - 2026-09-10
 

package/README.md

@@ -121,6 +121,37 @@ Mobile and Extension recipes can bracket explicit UI-smoothness windows with
 `app.performance_assert`. Capture is never automatic. See
 [UI smoothness capture](docs/PERFORMANCE-CAPTURE.md).
 
+## Work a task
+
+```bash
+# Pick a checklist from the shared catalog.
+mm-harness execution-template list --package-templates <catalog> --json
+
+# Write the task directory the agent works from.
+mm-harness task init temp/tasks/fix/TAT-1 \
+  --flow fix-bug --run-mode autonomous --template fix-bug/autonomous.mobile \
+  --package-templates <catalog> --title "Wrong total on the receipt" --ticket TAT-1
+
+# Bring the checkout to a proven-ready state before the first step.
+mm-harness prepare --artifacts-dir temp/tasks/fix/TAT-1/artifacts --json
+
+# Mark progress; the task's own ./mark shim routes here.
+mm-harness checklist mark temp/tasks/fix/TAT-1 start
+mm-harness checklist mark temp/tasks/fix/TAT-1 1
+mm-harness checklist mark temp/tasks/fix/TAT-1 complete --mark-last
+```
+
+`task init` writes `TASK.md`, `CHECKLIST.md`, the `mark` shim, and `inputs/`.
+`CHECKLIST.md` is the only file whose boxes count as steps. It writes no
+`checklist-target.json`; absent means `CHECKLIST.md` + `SIGNAL.json`.
+
+`prepare` runs `doctor --fix`, `status`, `launch --verify`, `fixtures set`, and
+`verify` in order, stops at the first failure, and records one readiness record
+at `<artifacts-dir>/sandbox.json`. Core skips launch and fixtures; Mobile takes
+`ios`/`android` from the checkout's configured target, then from the devices
+`status` reports, and asks when that is ambiguous. Exit 0 means
+ready. See [the task directory](site/task-dir.html).
+
 ## Discover and prove
 
 ```bash

package/adapters/extension/ensure-browser.sh

@@ -301,7 +301,7 @@ const {
   runtimeIdentityArgs,
   writeRuntimeIdentity,
 } = require(path.join('${SCRIPT_DIR}', 'lib/chrome-args.cjs'));
-const { captureMacFrontmostProcess, preserveMacFrontmostProcess } = require(path.join('${SCRIPT_DIR}', 'lib/macos-focus.cjs'));
+const { captureMacFrontmostProcess, restoreMacFrontmostProcess } = require(path.join('${SCRIPT_DIR}', 'lib/macos-focus.cjs'));
 
 const SLOT_ID = '${SLOT_ID}';
 const AGENT_DIR = '${AGENT_DIR}';
@@ -345,9 +345,7 @@ const resumeWebpack = () => {
 
   const chromiumApp = path.dirname(path.dirname(path.dirname(chromium.executablePath())));
   const previousFrontmostPid = captureMacFrontmostProcess();
-  const holdOperatorFocus = () => preserveMacFrontmostProcess(previousFrontmostPid);
   execFileSync('open', ['-g', '-n', '-a', chromiumApp, '--args', ...args], { stdio: 'ignore' });
-  holdOperatorFocus();
   for (let i = 0; i < 60; i++) {
     try {
       const version = await new Promise((resolve, reject) => {
@@ -360,7 +358,6 @@ const resumeWebpack = () => {
       });
       if (version) break;
     } catch {}
-    holdOperatorFocus();
     await new Promise(r => setTimeout(r, 1000));
   }
   const browser = await chromium.connectOverCDP('http://127.0.0.1:' + CDP_PORT);
@@ -501,7 +498,7 @@ const resumeWebpack = () => {
   if (process.env.MM_HARNESS_FOCUS_BROWSER === '1') {
     await page.bringToFront().catch(() => {});
   } else {
-    holdOperatorFocus();
+    restoreMacFrontmostProcess(previousFrontmostPid);
   }
 
   fs.writeFileSync(path.join(AGENT_DIR, 'extension.id'), extId);

package/adapters/extension/launch-browser.cjs

@@ -42,7 +42,7 @@ const {
   validationLaunchQuarantineError,
   writeRuntimeIdentity,
 } = require('./lib/chrome-args.cjs');
-const { captureMacFrontmostProcess, preserveMacFrontmostProcess } = require('./lib/macos-focus.cjs');
+const { captureMacFrontmostProcess, restoreMacFrontmostProcess } = require('./lib/macos-focus.cjs');
 
 if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log(
@@ -165,7 +165,6 @@ const chromeArgs = [
 ];
 const logFd = fs.openSync(args['chrome-log'], 'a');
 const previousFrontmostPid = captureMacFrontmostProcess();
-const holdOperatorFocus = () => preserveMacFrontmostProcess(previousFrontmostPid);
 let browserPid;
 try {
   const application = process.platform === 'darwin' ? macApplicationForExecutable(args['chrome-bin']) : null;
@@ -175,8 +174,7 @@ try {
       env: sanitizedChildEnv(),
       stdio: ['ignore', logFd, logFd],
     });
-    holdOperatorFocus();
-    browserPid = waitForOwnedCdpPid(cdpPort, args.profile, args['extension-dir'], holdOperatorFocus);
+    browserPid = waitForOwnedCdpPid(cdpPort, args.profile, args['extension-dir']);
     if (browserPid === null) {
       throw new Error(`Chrome launched but did not expose CDP on 127.0.0.1:${cdpPort}`);
     }
@@ -188,8 +186,7 @@ try {
       stdio: ['ignore', logFd, logFd],
     });
     child.unref();
-    holdOperatorFocus();
-    browserPid = waitForOwnedCdpPid(cdpPort, args.profile, args['extension-dir'], holdOperatorFocus);
+    browserPid = waitForOwnedCdpPid(cdpPort, args.profile, args['extension-dir']);
     if (browserPid === null) {
       if (child.pid) terminatePids([child.pid]);
       throw new Error(
@@ -223,13 +220,15 @@ try {
   );
 }
 if (process.platform === 'darwin') {
-  const wake = spawn('caffeinate', ['-dims', '-w', String(browserPid)], {
+  const wake = spawn('caffeinate', ['-dimsu', '-w', String(browserPid)], {
     detached: true,
     stdio: 'ignore',
   });
   wake.unref();
 }
-holdOperatorFocus();
+if (process.env.MM_HARNESS_FOCUS_BROWSER !== '1') {
+  restoreMacFrontmostProcess(previousFrontmostPid);
+}
 
 function sanitizedChildEnv() {
   return {
@@ -265,13 +264,12 @@ function macApplicationForExecutable(executable) {
   return null;
 }
 
-function waitForOwnedCdpPid(port, profile, extensionDir, onWait) {
+function waitForOwnedCdpPid(port, profile, extensionDir) {
   for (let i = 0; i < 300; i += 1) {
     const pid = cdpListenerPids(port).find((candidate) =>
       processIsOwnedHarnessBrowser(candidate, profile, extensionDir),
     );
     if (pid !== undefined) return pid;
-    if (typeof onWait === 'function' && i % 10 === 0) onWait();
     spawnSync('sleep', ['0.1']);
   }
   return null;

package/adapters/extension/lib/macos-focus.cjs

@@ -29,13 +29,4 @@ function restoreMacFrontmostProcess(pid) {
   }
 }
 
-function preserveMacFrontmostProcess(pid) {
-  if (process.env.MM_HARNESS_FOCUS_BROWSER === '1') return false;
-  return restoreMacFrontmostProcess(pid);
-}
-
-module.exports = {
-  captureMacFrontmostProcess,
-  preserveMacFrontmostProcess,
-  restoreMacFrontmostProcess,
-};
+module.exports = { captureMacFrontmostProcess, restoreMacFrontmostProcess };

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/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
+};

package/dist/doctor.js

@@ -8,7 +8,7 @@ import {
 } from "../library/actions/mobile/platform/tool-paths.mjs";
 import { mobilePerpsEnvironment } from "./adapters/mobile/perps-env.js";
 import { readRuntimeContextField, resolveRuntimeContextPath } from "./harness.js";
-import { manifestPath, readJson, recipeHarnessRoot, recipeRuntimeDir, runnerDir } from "./paths.js";
+import { harnessExecutable, manifestPath, readJson, recipeHarnessRoot, recipeRuntimeDir, runnerDir } from "./paths.js";
 function requiredDoctorCheckSummary(checks) {
   const required = checks.filter((check) => check.required);
   const failed = required.filter((check) => check.status === "fail").map((check) => check.id);
@@ -246,9 +246,7 @@ function runnerProvenance(actionManifestPath) {
   if (typeof version !== "string" || !version) {
     throw new Error(`Expected package version in ${packagePath}`);
   }
-  const executablePath = path.resolve(
-    process.env.MM_HARNESS_EXECUTABLE ?? path.join(runnerDir, "bin/mm-harness")
-  );
+  const executablePath = harnessExecutable();
   const invokedPath = path.resolve(process.env.MM_HARNESS_INVOKED_AS ?? executablePath);
   const installKind = runnerInstallKind(runnerDir, invokedPath, executablePath);
   const packageSource = runnerDir.includes(`${path.sep}node_modules${path.sep}`) ? "node_modules" : "source-checkout";
@@ -286,5 +284,6 @@ export {
   repoShape,
   requiredDoctorCheckSummary,
   runnerInstallKind,
+  runnerProvenance,
   runtimeContextSummary
 };

package/dist/mm-harness-cli.js

@@ -123,7 +123,9 @@ Example:
   mark delegates checklist state to @farmslot/agent-runtime. Successful complete
   and no-change marks stage a learning package through @farmslot/handoff.
   closeout exposes that same Handoff boundary directly; --share remains explicit.
-  The task directory must contain CHECKLIST.md and checklist-target.json.
+  The task directory is the one mm-harness task init wrote. Without a
+  checklist-target.json it marks CHECKLIST.md and writes SIGNAL.json; only a
+  role switch writes that manifest, to point at its own checklist.
 
   Steps: start | 1 | 2 | ... | complete | no-change | blocked
 
@@ -133,6 +135,84 @@ Example:
   mm-harness checklist mark temp/tasks/recipe-cook/<task> complete --mark-last
   mm-harness checklist closeout temp/tasks/recipe-cook/<task> --share`
   },
+  {
+    name: "prepare",
+    summary: "Bring this checkout to a proven-ready state and write the readiness record.",
+    example: "mm-harness prepare --platform extension",
+    helpText: `mm-harness prepare [flags]
+
+  Run the readiness chain for this checkout and record what it did as one
+  protocol readiness record (sandbox.json). Steps run in order and stop at the
+  first failure; later steps are recorded as skipped.
+
+    doctor --fix   status   launch --verify   fixtures set   verify
+
+  Core skips launch and fixtures (headless; verify is its readiness gate).
+  Mobile infers ios|android from the connected devices reported by status and
+  refuses with the numbered choice when that is ambiguous.
+
+  --target <path>                    Checkout path (default: cwd)
+  --platform <mobile|extension|core> Force the platform (auto-detected inside a checkout)
+  --mobile-platform <ios|android>    Mobile target when status cannot decide it
+  --artifacts-dir <dir>              Where sandbox.json and the per-step reports land
+                                     (default: <target>/temp/recipe/runtime)
+  --json                             Print the readiness record
+
+  Exit 0 when the record is ready, 1 otherwise.
+
+Example:
+  mm-harness prepare
+  mm-harness prepare --platform mobile --mobile-platform ios --json
+  mm-harness prepare --artifacts-dir temp/tasks/fix/TAT-1/artifacts --json`
+  },
+  {
+    name: "task",
+    summary: "Create the task directory an agent works from, out of a shared execution template.",
+    example: 'mm-harness task init temp/tasks/fix/TAT-1 --flow fix-bug --run-mode autonomous --template fix-bug/autonomous.mobile --title "Wrong total"',
+    helpText: `mm-harness task init <task-dir> [options]
+
+  Write the task directory from a selected execution template: TASK.md, the
+  CHECKLIST.md whose boxes are the steps, a mark shim routed through
+  mm-harness checklist mark, and inputs/ (handoff.json, worker-terminal-contract.json).
+  checklist-target.json is NOT written \u2014 absent means CHECKLIST.md + SIGNAL.json.
+
+  Applied when you do not pass them: --surface skill, --mark-command for this
+  executable, and --platform from the detected checkout.
+
+Task:
+  --title <t>                        Task title (required)
+  --task-text <s> | --task-file <p>  Task description, inline or from a file
+  --ticket <key>                     Ticket key
+  --source-ref <url>                 Where the task came from
+
+Selection (same catalog as execution-template):
+  --flow <flow>                      Exact flow (required)
+  --run-mode <mode>                  autonomous|interactive|validation (required)
+  --platform <platform>              Exact platform
+  --template <id>                    Exact template id (required)
+  --domain <domain>                  Exact domain
+  --dir <path>                       Custom flow-tree source (repeatable)
+  --domain-dir <domain=path>         Domain-scoped team source (repeatable)
+  --package-templates <path>         Canonical package flow-tree root
+  --package-id <id>                  Source label for the package root
+  --project-worker <path>            Project template directory
+  --project-name <name>              Source label for project templates
+
+Identity and rendering:
+  --surface <s>                      Handoff surface (default: skill)
+  --project <name>  --repo <owner/name>  --attempt-id <id>
+  --var KEY=VALUE                    Template placeholder value (repeatable)
+  --task-dir-label <label>           Task directory as written into the documents
+  --mode-preamble <text>             Run-mode preamble for TASK.md
+  --addendum-file <path>             Extra task-document section
+  --mark-command <cmd>               Override the recorded mark command
+  --json                             Machine-readable output
+
+Example:
+  mm-harness task init temp/tasks/fix/TAT-1 --flow fix-bug --run-mode autonomous \\
+    --template fix-bug/autonomous.mobile --package-templates <path> \\
+    --title "Wrong total on the receipt" --ticket TAT-1 --json`
+  },
   {
     name: "execution-template",
     summary: "Discover, validate, and materialize shared agent checklists.",
@@ -698,7 +778,7 @@ const HELP_GROUPS = [
   {
     title: "DAILY LOOP",
     blurb: "what a teammate runs many times a day (auto-ensures the overlay; --heal owns recovery)",
-    commands: ["status", "launch", "stop", "logs", "debug", "reload", "fixtures"]
+    commands: ["status", "task", "prepare", "launch", "stop", "logs", "debug", "reload", "fixtures"]
   },
   {
     title: "DISCOVER",

package/dist/paths.js

@@ -11,6 +11,9 @@ function recipeRuntimeDir() {
 function recipeHarnessRoot() {
   return validateRelativeRecipePath("RECIPE_HARNESS_ROOT", process.env.RECIPE_HARNESS_ROOT || DEFAULT_RECIPE_HARNESS_ROOT);
 }
+function harnessExecutable() {
+  return path.resolve(process.env.MM_HARNESS_EXECUTABLE ?? path.join(runnerDir, "bin/mm-harness"));
+}
 function readPathDefaults() {
   const defaultsPath = path.join(runnerDir, "adapters/shared/path-defaults.json");
   const parsed = JSON.parse(fs.readFileSync(defaultsPath, "utf8"));
@@ -170,6 +173,7 @@ export {
   DEFAULT_RECIPE_RUNTIME_DIR,
   assertAdapter,
   extensionIdPath,
+  harnessExecutable,
   importMetaMaskNativeUiProvider,
   importRecipeHarness,
   importRecipeHarnessAppLifecycle,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.50.5",
+  "version": "0.51.0",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -20,11 +20,11 @@
     "check:syntax": "find . -name '*.mjs' -print0 | xargs -0 -n1 node --check"
   },
   "dependencies": {
-    "@farmslot/agent-runtime": "0.8.1",
-    "@farmslot/expo-recipe": "0.9.0",
+    "@farmslot/agent-runtime": "0.9.0",
+    "@farmslot/expo-recipe": "0.9.1",
     "@farmslot/handoff": "^0.3.1",
-    "@farmslot/protocol": "0.21.0",
-    "@farmslot/recipe-harness": "0.16.1",
+    "@farmslot/protocol": "0.26.0",
+    "@farmslot/recipe-harness": "0.16.2",
     "agent-device": "0.19.3",
     "commander": "^12.0.0",
     "es-module-lexer": "2.3.1",