@deeeed/metamask-harness 0.61.1 → 0.63.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## Unreleased
 
+## 0.63.0 - 2026-09-23
+
+### Added
+
+- Show the task's acceptance criteria and recorded verdicts in `status`, `status --watch`, and `status --task`, using the Farmslot handoff and acceptance ledger.
+- Show the active preparation step and elapsed time in `status --watch` and `status --task` even when the agent buffers preparation output.
+
+### Fixed
+
+- Allow 30 seconds for iOS simulator discovery so a cold CoreSimulator startup does not fail at five seconds.
+
+## 0.62.0 - 2026-09-22
+
+### Added
+
+- `MM_HARNESS_SIMULATOR_APP` can pin a standalone Simulator from another installed Xcode without changing build tools; an invalid preference fails instead of selecting a different viewer.
+
+### Fixed
+
+- iOS launch opens the assigned simulator window through Device Hub on Xcode 27, including when Device Hub is already running. Older Xcode versions keep using Simulator. GUI launch errors stay visible instead of requiring a headless workaround. Explicit foreground opening no longer needs AppleScript permission, and fails the launch if it cannot open the UI.
+
+### Added
+
+- `recipe-quality plan` maps acceptance criteria to existing adapter-supported actions and composable library recipes before authoring; `recipe-quality advise` reviews drafts and supplied evidence. Both offer opt-in semantic assessment through `--advisor <provider>` with configurable `--advisor-model`; TypeSafe is the first provider. Engineer settings and CLI/environment overrides share one resolver exposed by `recipe-quality advisor-status`, defaulting to disabled and planning only. They record provider/model provenance, write separate advisory results, and skip missing keys or report provider unavailability without changing normal execution or canonical quality.
+
 ## 0.61.1 - 2026-09-21
 
 ### Fixed

package/README.md

@@ -237,6 +237,13 @@ mm-harness run --list
 Shared libraries hold durable actions and composable recipes. Task acceptance
 criteria remain task-local. See [Recipes](docs/RECIPES.md).
 
+For optional model advice matching acceptance criteria to library flows and assessing
+drafts or evidence, see [Optional recipe advisor](docs/RECIPES.md#optional-recipe-advisor).
+Select a provider with `--advisor typesafe` or save `advisor.enabled` and
+`advisor.provider` through `mm-harness config`. Inspect the effective policy with
+`mm-harness recipe-quality advisor-status --json`; use `--advisor off` per task.
+Ordinary recipe execution needs no advisor or API key.
+
 Exporting is not required: a library registered with `mm-harness config set
 libraries.<name> <path>`, or checked out beside the product checkout, reaches
 `run`, `actions`, and template discovery too. `mm-harness status` lists what this

package/adapters/mobile/open-device.sh

@@ -14,7 +14,10 @@
 #   --adb-serial <serial>               Android device serial (default: ADB_SERIAL env)
 #   --preflight-mode fast|auto|rebuild-native|clean  (default: fast; env MOBILE_PREFLIGHT_MODE)
 #   --restart                            terminate the selected app before opening it
-#   --ui-only                           iOS only: ensure Simulator.app is visible; do not relaunch the app
+#   --ui-only                           iOS only: show the assigned simulator window without relaunching the app
+#   MM_HARNESS_SIMULATOR_APP             absolute Simulator.app or DeviceHub.app path; GUI only
+#   MM_HARNESS_SHOW_SIMULATOR=0          opt out of automatic GUI opening
+#   MM_HARNESS_FOCUS_SIMULATOR=1         explicitly open/activate the GUI, even with SHOW_SIMULATOR=0
 # Outputs:
 #   Progress on stderr; exit 0 pass; 1 open failed; 2 bad args.
 #
@@ -273,47 +276,71 @@ boot_simulator_if_needed() {
   xcrun simctl bootstatus "$udid" -b >/dev/null
 }
 
-simulator_ui_running() {
-  pgrep -x Simulator >/dev/null 2>&1
+resolve_simulator_ui_app() {
+  local preferred_app="${MM_HARNESS_SIMULATOR_APP:-}"
+  if [ -n "$preferred_app" ]; then
+    preferred_app="${preferred_app%/}"
+    case "$preferred_app" in
+      /*/Simulator.app|/*/DeviceHub.app)
+        if [ -d "$preferred_app" ]; then
+          printf '%s\n' "$preferred_app"
+          return 0
+        fi
+        ;;
+    esac
+    printf 'open-device: MM_HARNESS_SIMULATOR_APP must name an existing absolute Simulator.app or DeviceHub.app path.\nNext: ls -d %q\n' "$preferred_app" >&2
+    return 1
+  fi
+  local developer_dir="${DEVELOPER_DIR:-}"
+  if [ -z "$developer_dir" ]; then
+    developer_dir="$(xcode-select -p)" || return 1
+  fi
+  developer_dir="${developer_dir%/}"
+  case "$developer_dir" in *.app) developer_dir="$developer_dir/Contents/Developer" ;; esac
+  if [ -d "$developer_dir/../Applications/DeviceHub.app" ]; then
+    printf '%s\n' "$developer_dir/../Applications/DeviceHub.app"
+  elif [ -d "$developer_dir/Applications/Simulator.app" ]; then
+    printf '%s\n' "$developer_dir/Applications/Simulator.app"
+  else
+    printf 'open-device: no simulator UI found in the selected Xcode.\nNext: xcode-select -p\n' >&2
+    return 1
+  fi
 }
 
-open_simulator_in_background_if_needed() {
-  local target="$1" udid=""
-  [ "${MM_HARNESS_SHOW_SIMULATOR:-1}" != "0" ] || return 0
-  simulator_ui_running && return 0
-  printf 'Opening Simulator UI in the background\n' >&2
-  if [ "$target" = "booted" ]; then
-    open -g -a Simulator >/dev/null 2>&1 || {
-      printf 'open-device: failed to open Simulator UI.\n' >&2
+open_simulator_ui() {
+  local target="$1" app="$2" background="$3"
+  local open_args=(-a "$app")
+  [ "$background" != "true" ] || open_args=(-g "${open_args[@]}")
+  if [[ "$app" == */DeviceHub.app ]]; then
+    # Device Hub routes device windows through URLs, including when already open.
+    # Simulator's CurrentDeviceUDID launch argument does not select its window.
+    open "${open_args[@]}" "devices://device/open?id=$target" >&2 || {
+      printf 'open-device: failed to open Device Hub for %s.\nNext: open -a %q %q\n' "$target" "$app" "devices://device/open?id=$target" >&2
       return 1
     }
   else
-    udid="$(sim_udid_for_target "$target")"
-    if [ -n "$udid" ]; then
-      open -g -a Simulator --args -CurrentDeviceUDID "$udid" >/dev/null 2>&1 || {
-        printf 'open-device: failed to open Simulator UI for %s.\n' "$target" >&2
-        return 1
-      }
-    else
-      open -g -a Simulator >/dev/null 2>&1 || {
-        printf 'open-device: failed to open Simulator UI.\n' >&2
-        return 1
-      }
-    fi
+    open "${open_args[@]}" --args -CurrentDeviceUDID "$target" >&2 || {
+      printf 'open-device: failed to open Simulator for %s.\nNext: open -a %q --args -CurrentDeviceUDID %q\n' "$target" "$app" "$target" >&2
+      return 1
+    }
   fi
 }
 
-focus_simulator() {
-  local target="$1" udid=""
-  if [ "$target" != "booted" ]; then
-    udid="$(sim_udid_for_target "$target")"
-  fi
-  if [ -n "$udid" ]; then
-    open -a Simulator --args -CurrentDeviceUDID "$udid" >/dev/null 2>&1 || true
-  else
-    open -a Simulator >/dev/null 2>&1 || true
+open_simulator_in_background_if_needed() {
+  local target="$1" app=""
+  [ "${MM_HARNESS_SHOW_SIMULATOR:-1}" != "0" ] || return 0
+  app="$(resolve_simulator_ui_app)" || return 1
+  if [[ "$app" == */Simulator.app ]] && [ -z "${MM_HARNESS_SIMULATOR_APP:-}" ] && pgrep -x Simulator >/dev/null 2>&1; then
+    return 0
   fi
-  osascript -e 'tell application "Simulator" to activate' >/dev/null 2>&1 || true
+  printf 'Opening %s for %s in the background\n' "$(basename "$app" .app)" "$target" >&2
+  open_simulator_ui "$target" "$app" true
+}
+
+focus_simulator() {
+  local app=""
+  app="$(resolve_simulator_ui_app)" || return 1
+  open_simulator_ui "$1" "$app" false
 }
 
 # --- Android helpers ----------------------------------------------------------
@@ -507,9 +534,10 @@ if [ "$PLATFORM" = "ios" ]; then
   DEV_CLIENT_SCHEME="${IOS_DEV_CLIENT_SCHEME:-expo-metamask}"
 
   boot_simulator_if_needed "$SIM_TARGET" || exit 1
-  open_simulator_in_background_if_needed "$SIM_TARGET" || exit 1
   if [ "${MM_HARNESS_FOCUS_SIMULATOR:-0}" = "1" ]; then
-    focus_simulator "$SIM_TARGET"
+    focus_simulator "$SIM_TARGET" || exit 1
+  else
+    open_simulator_in_background_if_needed "$SIM_TARGET" || exit 1
   fi
   if $UI_ONLY; then
     exit 0

package/dist/advisor-policy.js

@@ -0,0 +1,40 @@
+import { assessmentProvider } from "./assessment-providers.js";
+import { optionString, usageError } from "./commands/parse-args.js";
+import { configPath, parseAdvisorSettings, readConfig } from "./review/knowledge.js";
+function resolveAdvisorPolicy(options, env = process.env, config) {
+  const saved = (config ?? readConfig(configPath(env))).advisor ?? {};
+  const cliAdvisor = optionString(options, "advisor");
+  const configuredAdvisor = cliAdvisor ?? env.MM_HARNESS_ADVISOR;
+  if (configuredAdvisor !== void 0 && !configuredAdvisor.trim()) throw usageError("Advisor override must name a provider or off. Next: unset MM_HARNESS_ADVISOR or select --advisor off.");
+  const enabled = configuredAdvisor !== void 0 ? configuredAdvisor !== "off" : saved.enabled === true;
+  const source = cliAdvisor !== void 0 ? "cli" : env.MM_HARNESS_ADVISOR !== void 0 ? "env" : saved.enabled !== void 0 ? "config" : "default";
+  const providerName = configuredAdvisor && configuredAdvisor !== "off" ? configuredAdvisor : saved.provider;
+  const cliModel = optionString(options, "advisorModel");
+  const overrideStages = optionString(options, "advisorStages") ?? env.MM_HARNESS_ADVISOR_STAGES;
+  const stages = enabled && overrideStages !== void 0 ? parseAdvisorSettings({ stages: overrideStages.split(",").map((stage) => stage.trim()) }).stages : saved.stages ?? ["plan"];
+  const sources = {
+    enabled: source,
+    provider: configuredAdvisor && configuredAdvisor !== "off" ? source : saved.provider ? "config" : "default",
+    model: cliModel !== void 0 ? "cli" : env.MM_HARNESS_ADVISOR_MODEL !== void 0 ? "env" : saved.model ? "config" : "default",
+    stages: enabled && options.advisorStages !== void 0 ? "cli" : enabled && env.MM_HARNESS_ADVISOR_STAGES !== void 0 ? "env" : saved.stages ? "config" : "default"
+  };
+  if (!enabled) {
+    if (cliModel !== void 0 && configuredAdvisor !== "off") throw usageError("A model alone does not enable advice. Next: select --advisor <provider> or enable advisor settings.");
+    return { policy: { enabled: false, status: "disabled", stages, sources }, selection: void 0 };
+  }
+  const provider = providerName ? assessmentProvider(providerName) : void 0;
+  if (!provider) throw usageError("Enabled advice requires a supported provider. Next: use --advisor typesafe or --advisor off.");
+  const savedModel = !configuredAdvisor || configuredAdvisor === saved.provider ? saved.model : void 0;
+  const model = cliModel ?? env.MM_HARNESS_ADVISOR_MODEL ?? savedModel ?? provider.defaultModel;
+  if (!model.trim()) throw usageError("Advisor model must be non-empty. Next: unset the model override to use the provider default.");
+  if (!cliModel && env.MM_HARNESS_ADVISOR_MODEL === void 0 && !savedModel) sources.model = "default";
+  const keyAvailable = Boolean(env[provider.apiKeyEnv]?.trim());
+  const selection = { provider, model: model.trim() };
+  return {
+    policy: { enabled: true, status: keyAvailable ? "ready" : "skipped", ...keyAvailable ? {} : { reason: "missing_key" }, provider: provider.id, model: model.trim(), stages, keyAvailable, sources },
+    selection
+  };
+}
+export {
+  resolveAdvisorPolicy
+};

package/dist/assessment-providers.js

@@ -0,0 +1,12 @@
+const providers = [{
+  id: "typesafe",
+  apiKeyEnv: "TYPESAFE_API_KEY",
+  defaultModel: "jev-1.13.0",
+  assess: async (request, options) => (await import("./typesafe-client.js")).requestTypeSafe(request, options)
+}];
+function assessmentProvider(name) {
+  return providers.find((provider) => provider.id === name);
+}
+export {
+  assessmentProvider
+};

package/dist/cli-commands.js

@@ -12,7 +12,7 @@ const SPEC = {
     { name: "review", desc: "Materialize a review checklist composed from the base review and a team library", args: ["checklist"], flags: ["--domain", "--since", "--base", "--out", "--adapter", "--target", "--json"] },
     { name: "domain", desc: "Which team library owns the change (declared value, else owned-paths.json)", flags: ["--domain", "--base", "--adapter", "--target", "--json"] },
     { name: "pr-body", desc: "Render the publishable PR body: pr-description.md plus the recipe and run sections built from artifacts", args: ["render", "<task-dir>"], flags: ["--command", "--out", "--json"] },
-    { name: "config", desc: "Per-engineer locations: libraries.<name>, references.<adapter>", args: ["list", "path", "get", "set", "unset"], flags: ["--json"] },
+    { name: "config", desc: "Per-engineer locations and optional advisor settings", args: ["list", "path", "get", "set", "unset"], flags: ["--json"] },
     { name: "tutorial", desc: "Open the visual recipe tutorial", flags: ["--json", "--no-open"] },
     { name: "setup-base", desc: "Bootstrap numbered product checkouts", flags: ["--dir", "--counts", "--only", "--dry-run", "--force", "--json", "--show-config", "--reset-config", "--skip-harness-update"] },
     { name: "status", aliases: ["health", "home"], desc: "Home status + next commands", flags: ["--json", "--fast", "--watch", "--task"] },
@@ -27,7 +27,7 @@ const SPEC = {
     { name: "doctor", desc: "Check harness/orchestration health", flags: ["--json", "--target", "--adapter", "--runtime-dir", "--expect-live", "--print-ready", "--cdp-port", "--device"] },
     { name: "run", desc: "Execute a proof recipe (path or library name, e.g. run perps.smoke)", args: ["recipe.json|name"], flags: ["--list", "--device"] },
     { 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: "recipe-quality", desc: "Build canonical quality or request optional recipe planning/advice", args: ["build", "plan", "advise", "advisor-status"], flags: ["--input", "--output", "--recipe", "--task", "--evidence", "--params", "--adapter", "--library", "--advisor", "--advisor-model", "--advisor-stages", "--json"] },
     { name: "interactive", aliases: ["menu"], desc: "Interactive command menu" },
     { 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"] },

package/dist/command-contract.js

@@ -289,11 +289,19 @@ const PUBLIC_COMMAND_CONTRACTS = {
     minimumPositionals: 1
   },
   "recipe-quality": {
-    options: options(HELP, JSON, {
+    options: options(HELP, JSON, ADAPTER, {
       "--input": value(),
-      "--output": value()
+      "--output": value(),
+      "--recipe": value(),
+      "--task": value(),
+      "--evidence": value(),
+      "--params": value(),
+      "--library": value(),
+      "--advisor": value(),
+      "--advisor-model": value(),
+      "--advisor-stages": value()
     }),
-    positionals: [{ label: "action", choices: ["build"] }]
+    positionals: [{ label: "action", choices: ["build", "plan", "advise", "advisor-status"] }]
   },
   provision: {
     options: options(HELP, JSON, TARGET, ADAPTER, DEVICE, RUNWAY, {

package/dist/commands/config.js

@@ -2,11 +2,12 @@ import path from "node:path";
 import {
   configPath,
   readConfig,
+  parseAdvisorSettings,
   REVIEW_ADAPTERS,
   writeConfig
 } from "../review/knowledge.js";
 import { optionFlag, parseArgs, usageError } from "./parse-args.js";
-const USAGE = "Usage: mm-harness config <list|path|get <key>|set <key> <path>|unset <key>> [--json]\n  keys: libraries.<name>, references.<mobile|extension|core>";
+const USAGE = "Usage: mm-harness config <list|path|get <key>|set <key> <value>|unset <key>> [--json]\n  keys: libraries.<name>, references.<mobile|extension|core>, advisor.<enabled|provider|model|stages>";
 function parseKey(raw) {
   if (!raw) throw usageError(USAGE);
   const dot = raw.indexOf(".");
@@ -14,21 +15,23 @@ function parseKey(raw) {
   const name = dot === -1 ? "" : raw.slice(dot + 1);
   if (!name) throw usageError(`Config key must be libraries.<name> or references.<adapter> (got ${raw}).`);
   if (section === "libraries") return { section, name };
+  if (section === "advisor" && ["enabled", "provider", "model", "stages"].includes(name)) return { section, name };
   if (section === "references") {
     if (!REVIEW_ADAPTERS.includes(name)) {
       throw usageError(`references.<adapter> must be one of ${REVIEW_ADAPTERS.join(", ")} (got ${name}).`);
     }
     return { section, name };
   }
-  throw usageError(`Config key must start with libraries. or references. (got ${raw}).`);
+  throw usageError(`Unknown config key ${raw}. Next: use libraries.<name>, references.<adapter> or advisor.<enabled|provider|model|stages>.`);
 }
 function getValue(config, key) {
-  return key.section === "libraries" ? config.libraries?.[key.name] : config.references?.[key.name];
+  return config[key.section]?.[key.name];
 }
 function setValue(config, key, value) {
   const section = config[key.section] ?? {};
   if (value === void 0) delete section[key.name];
   else section[key.name] = value;
+  if (key.section === "advisor") parseAdvisorSettings(section);
   if (Object.keys(section).length === 0) delete config[key.section];
   else config[key.section] = section;
 }
@@ -56,7 +59,8 @@ async function handleConfig(argv) {
     }
     const lines = [
       ...Object.entries(config.libraries ?? {}).map(([name, root]) => `libraries.${name}=${root}`),
-      ...Object.entries(config.references ?? {}).map(([name, root]) => `references.${name}=${root}`)
+      ...Object.entries(config.references ?? {}).map(([name, root]) => `references.${name}=${root}`),
+      ...Object.entries(config.advisor ?? {}).map(([name, value]) => `advisor.${name}=${Array.isArray(value) ? value.join(",") : value}`)
     ];
     process.stdout.write(lines.length > 0 ? `${lines.join("\n")}
 ` : `(empty) ${file}
@@ -71,17 +75,18 @@ async function handleConfig(argv) {
       return 0;
     }
     if (value === void 0) return 1;
-    process.stdout.write(`${value}
+    process.stdout.write(`${Array.isArray(value) ? value.join(",") : value}
 `);
     return 0;
   }
   if (action === "set") {
     const key = parseKey(rawKey);
-    if (!rawValue) throw usageError(`mm-harness config set ${rawKey} <path>`);
-    setValue(config, key, path.resolve(rawValue));
+    if (!rawValue) throw usageError(`mm-harness config set ${rawKey} <value>`);
+    const value = key.section !== "advisor" ? path.resolve(rawValue) : key.name === "enabled" ? rawValue === "true" ? true : rawValue === "false" ? false : rawValue : key.name === "stages" ? rawValue.split(",").map((stage) => stage.trim()) : rawValue.trim();
+    setValue(config, key, value);
     writeConfig(file, config);
-    process.stdout.write(json ? `${JSON.stringify({ command: "config", key: rawKey, value: path.resolve(rawValue), path: file })}
-` : `${rawKey}=${path.resolve(rawValue)}
+    process.stdout.write(json ? `${JSON.stringify({ command: "config", key: rawKey, value, path: file })}
+` : `${rawKey}=${Array.isArray(value) ? value.join(",") : value}
 `);
     return 0;
   }

package/dist/commands/prepare.js

@@ -7,7 +7,7 @@ import {
 import { color, stripAnsi } from "../cli-color.js";
 import { runnerProvenance } from "../doctor.js";
 import { detectAdapter } from "../harness.js";
-import { harnessExecutable, manifestPath, recipeRuntimeDir } from "../paths.js";
+import { harnessExecutable, manifestPath, PREPARE_PROGRESS_ARTIFACT, recipeRuntimeDir } from "../paths.js";
 import { optionFlag, optionString, parseArgs, targetPath, usageError } from "./parse-args.js";
 import { EXIT } from "./shared.js";
 import { formatDuration } from "./status-watch.js";
@@ -336,13 +336,32 @@ async function handlePrepare(argv) {
   const remoteFlagArgs = remoteFlag === void 0 ? [] : ["--remote-flag", remoteFlag];
   let mobilePlatform = mobilePlatformOption(optionString(options, "mobilePlatform"));
   const recordPath = path.join(artifactsDir, READINESS_RECORD);
+  const progressPath = path.join(artifactsDir, PREPARE_PROGRESS_ARTIFACT);
   const chain = stepChain(platform);
   const view = json ? void 0 : createStepView(chain, stepHints(chain, lastRunDurations(recordPath)));
   view?.begin();
   const steps = [];
+  let activeStep;
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const writeProgress = () => {
+    fs.mkdirSync(path.dirname(progressPath), { recursive: true });
+    const temporaryPath = `${progressPath}.${process.pid}.tmp`;
+    fs.writeFileSync(temporaryPath, `${JSON.stringify({
+      schemaVersion: 1,
+      startedAt,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      total: chain.length,
+      steps: steps.filter(({ id }) => chain.includes(id)).map(({ id, status, durationMs }) => ({ id, status, durationMs })),
+      ...activeStep ? { active: activeStep } : {}
+    })}
+`);
+    fs.renameSync(temporaryPath, progressPath);
+  };
   const failed = () => steps.some((step) => step.status === "fail");
   const addStep = (step) => {
     steps.push(step);
+    activeStep = void 0;
+    writeProgress();
     view?.finish(step);
     return step;
   };
@@ -352,10 +371,17 @@ async function handlePrepare(argv) {
     }
     const step = await runStep(executable, target, artifactsDir, id, args, {
       json,
-      onSpawn: (startedAt) => view?.start(id, startedAt)
+      onSpawn: (stepStartedAt) => {
+        activeStep = { id, startedAt: new Date(stepStartedAt).toISOString() };
+        writeProgress();
+        view?.start(id, stepStartedAt);
+      }
     });
     return addStep(step);
   };
+  const heartbeat = setInterval(() => {
+    if (activeStep) writeProgress();
+  }, 1e4);
   try {
     await run("doctor", ["doctor", "--fix", "--json", "--adapter", platform, ...targetArgs]);
     await run("status", ["status", "--json", ...targetArgs]);
@@ -384,6 +410,7 @@ async function handlePrepare(argv) {
     }
     await run("verify", ["verify", "--json", "--adapter", platform, ...targetArgs]);
   } finally {
+    clearInterval(heartbeat);
     view?.end();
   }
   const provenance = runnerProvenance(manifestPath(platform));
@@ -404,6 +431,7 @@ async function handlePrepare(argv) {
   fs.mkdirSync(artifactsDir, { recursive: true });
   fs.writeFileSync(recordPath, `${JSON.stringify(record, null, 2)}
 `);
+  fs.rmSync(progressPath, { force: true });
   if (json) {
     console.log(JSON.stringify(record, null, 2));
   } else {

package/dist/commands/recipe-advice.js

@@ -0,0 +1,76 @@
+import fs from "node:fs";
+import path from "node:path";
+import { adviseRecipe } from "../recipe-assistance.js";
+import { resolveAdvisorPolicy } from "../advisor-policy.js";
+import { RECIPE_ADVICE_RUBRIC, RECIPE_PLANNING_RUBRIC } from "../recipe-assistance-rubric.js";
+import { CliError, isRecord, optionFlag, optionString, usageError } from "./parse-args.js";
+import { EXIT } from "./shared.js";
+async function handleRecipeAdvice(options, mode = "review") {
+  try {
+    return await runRecipeAdvice(options, mode);
+  } catch (error) {
+    if (!(error instanceof CliError)) throw error;
+    const userAction = "mm-harness recipe-quality --help";
+    if (optionFlag(options, "json")) console.log(JSON.stringify({ schemaVersion: 1, command: "recipe-quality", action: mode === "status" ? "advisor-status" : mode === "plan" ? "plan" : "advise", status: "fail", exitCode: error.exitCode, error: { code: error.exitCode === EXIT.validation ? "RECIPE_ADVICE_INVALID" : "RECIPE_ADVICE_USAGE", message: error.message, userAction } }, null, 2));
+    else console.error(`\u2717 mm-harness recipe-quality: ${error.message}
+  Next: ${userAction}`);
+    return error.exitCode;
+  }
+}
+async function runRecipeAdvice(options, mode) {
+  const { policy, selection } = resolveAdvisorPolicy(options);
+  if (mode === "status") {
+    if (optionFlag(options, "json")) console.log(JSON.stringify({ schemaVersion: 1, command: "recipe-quality", action: "advisor-status", ...policy }, null, 2));
+    else console.log(`Recipe advisor: ${policy.status}${policy.enabled ? ` (${policy.provider}, ${policy.model}; stages: ${policy.stages.join(", ")})` : ""}.`);
+    return EXIT.ok;
+  }
+  const recipe = optionString(options, "recipe");
+  const task = optionString(options, "task");
+  const adapter = optionString(options, "adapter");
+  const output = optionString(options, "output");
+  const evidence = optionString(options, "evidence");
+  if (mode === "review" && !recipe || !task || !["mobile", "extension", "core"].includes(adapter ?? "")) {
+    throw usageError("Use recipe-quality plan --task <task.json>, or advise --recipe <recipe.json> --task <TASK.md>, with --adapter <adapter> [--advisor <provider>].");
+  }
+  if (mode === "plan" && (recipe || evidence || optionString(options, "params"))) throw usageError("Planning runs before a recipe exists. Next: use advise to review a draft or evidence.");
+  if (optionString(options, "input")) throw usageError("--input belongs to recipe-quality build. Next: use --recipe and --task for advise.");
+  let params;
+  if (optionString(options, "params")) {
+    try {
+      const parsed = JSON.parse(optionString(options, "params"));
+      if (!isRecord(parsed)) throw usageError("--params must be a JSON object.");
+      params = parsed;
+    } catch (error) {
+      if (error instanceof SyntaxError) throw usageError("--params must be a JSON object.");
+      throw error;
+    }
+  }
+  if (output) {
+    const resolved = path.resolve(output);
+    if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) throw usageError("Advice output must be a file. Next: use artifacts/recipe-advice.json.");
+    const canonical = fs.existsSync(resolved) ? fs.realpathSync(resolved) : resolved;
+    const inputs = [recipe, task, evidence].filter((file) => Boolean(file)).map((file) => fs.existsSync(file) ? fs.realpathSync(file) : path.resolve(file));
+    if ([resolved, canonical].some((file) => /^recipe(?:-quality(?:-input)?)?\.json$/iu.test(path.basename(file))) || inputs.includes(canonical) || inputs.includes(resolved)) {
+      throw usageError("Advice output must be separate from recipes, task inputs, and recipe-quality.json. Next: use artifacts/recipe-advice.json.");
+    }
+  }
+  const stage = mode === "plan" ? "plan" : evidence ? "evidence" : "draft";
+  const explicitCall = options.advisor !== void 0 && options.advisor !== "off" && options.advisorStages === void 0;
+  const stageDisabled = policy.enabled && !explicitCall && !policy.stages.includes(stage);
+  const artifact = stageDisabled ? { schemaVersion: 1, advisory: true, rubric: mode === "plan" ? RECIPE_PLANNING_RUBRIC : RECIPE_ADVICE_RUBRIC, status: "skipped", reason: "stage_disabled" } : await adviseRecipe({ recipe, task, mode, adapter, evidence, params, options }, selection);
+  if (output && artifact.status !== "disabled") {
+    fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
+    fs.writeFileSync(path.resolve(output), `${JSON.stringify(artifact, null, 2)}
+`);
+  }
+  if (optionFlag(options, "json")) console.log(JSON.stringify({ schemaVersion: 1, command: "recipe-quality", action: mode === "plan" ? "plan" : "advise", ...artifact, policy, ...output && artifact.status !== "disabled" ? { outputPath: output } : {} }, null, 2));
+  else {
+    console.log(`Recipe advice: ${artifact.status}${"reason" in artifact ? ` (${artifact.reason})` : ""}.`);
+    if (artifact.status === "completed" && "checks" in artifact) for (const check of artifact.checks) console.log(`  ${check.id}: ${check.outcome}${check.suggestion ? `. ${check.suggestion}` : ""}`);
+    if (artifact.status === "completed" && "assessments" in artifact) for (const assessment of artifact.assessments) console.log(`  ${assessment.id}: ${assessment.classification}${assessment.candidate ? ` (${assessment.candidate.ref})` : ""}`);
+  }
+  return EXIT.ok;
+}
+export {
+  handleRecipeAdvice
+};

package/dist/commands/recipe-quality.js

@@ -37,11 +37,18 @@ async function handleRecipeQuality(argv) {
   const { positional, options } = parseArgs(argv, "recipe-quality");
   const json = optionFlag(options, "json");
   const action = positional[0];
+  if (action === "advise" || action === "plan" || action === "advisor-status") {
+    const { handleRecipeAdvice } = await import("./recipe-advice.js");
+    return handleRecipeAdvice(options, action === "advisor-status" ? "status" : action === "plan" ? "plan" : "review");
+  }
+  if (["advisor", "advisorModel", "advisorStages", "recipe", "task", "evidence", "adapter", "library", "params"].some((key) => options[key] !== void 0)) {
+    return usageOut(json, "recipe-quality", "advice options require the advise subcommand", "mm-harness recipe-quality advise --recipe <recipe.json> --task <TASK.md> --adapter <adapter> --advisor <provider>");
+  }
   if (!action && (optionString(options, "input") || optionString(options, "output"))) {
     return buildArtifact(options, json);
   }
   if (action !== "build") {
-    const message = action ? `unknown action '${action}'` : "missing action: use build, or pass --input and --output";
+    const message = action ? `unknown action '${action}'` : "missing action: use build, plan, or advise";
     return usageOut(json, "recipe-quality", message, SHORTHAND_USAGE);
   }
   return buildArtifact(options, json);

package/dist/commands/run-engine.js

@@ -1470,6 +1470,7 @@ export {
   preflightRecipe,
   prepareHeal,
   prepareRuntimeIfNeeded,
+  recipeComposition,
   resolveMetaMaskLibrarySources,
   resolveRunRecipeArg,
   runOneNode,

package/dist/commands/status-watch.js

@@ -103,9 +103,13 @@ function renderTaskView(view, title, explicitTask = false) {
   const contextLine = joinParts([
     view.libraries.length > 0 && `libraries ${out("info", view.libraries.map(libraryLabel).join(" "))}`,
     showTask && view.fixture && `fixture ${out("info", path.basename(view.fixture.fixture ?? "unknown"))} ${statusWord(out, view.fixture.status)}${view.fixture.walletReset ? out("warn", " reset") : ""}`,
-    showTask && view.sandbox?.ready !== void 0 && `sandbox ${view.sandbox.ready ? out("ok", "ready") : out("warn", "not ready")}`
+    showTask && (view.prepare ? `sandbox ${out("info", "preparing")}` : view.sandbox?.ready !== void 0 && `sandbox ${view.sandbox.ready ? out("ok", "ready") : out("warn", "not ready")}`)
   ]);
   if (contextLine) lines.push(contextLine);
+  if (showTask && view.acceptance?.length) lines.push("", ...renderAcceptanceLines(view));
+  if (showTask && view.prepare) {
+    lines.push(`prepare ${out("info", view.prepare.step)} \xB7 ${view.prepare.completed}/${view.prepare.total} steps \xB7 ${formatDuration(view.prepare.elapsedMs)} elapsed`);
+  }
   const last = view.lastCommand;
   if (showTask && last) {
     lines.push(joinParts([
@@ -148,6 +152,19 @@ function renderTaskView(view, title, explicitTask = false) {
   }
   return lines;
 }
+function renderAcceptanceLines(view) {
+  if (!view.acceptance?.length) return [];
+  const out = (style, text) => color(style, text, { stream: process.stdout });
+  const proven = view.acceptance.filter((row) => row.status?.verdict === "proven").length;
+  return [
+    `acceptance criteria ${proven}/${view.acceptance.length} proven`,
+    ...view.acceptance.map((row) => {
+      const verdict = row.status?.verdict ?? "no verdict";
+      const style = verdict === "proven" ? "ok" : verdict === "weak" ? "warn" : verdict === "no verdict" ? "dim" : "err";
+      return `  ${row.id} [${out(style, verdict)}] ${row.text}`;
+    })
+  ];
+}
 function idleReason(view) {
   if (!view.taskDir) return "no task directory under temp/tasks";
   const { reason, idleMs, branchCarriesTicket } = view.activity;
@@ -161,15 +178,33 @@ function idleReason(view) {
 }
 function changedLines(previous, next) {
   if (!previous || previous.taskDir !== next.taskDir) {
-    return [joinParts([
-      path.basename(next.checkout.target),
-      next.taskDir ? path.basename(next.taskDir) : "no-task-dir",
-      `status=${next.signal?.status ?? "unknown"}`,
-      `step=${next.signal?.step ? stepLabel(next.signal.step) : "none"}`
-    ], " ")];
+    return [
+      joinParts([
+        path.basename(next.checkout.target),
+        next.taskDir ? path.basename(next.taskDir) : "no-task-dir",
+        `status=${next.signal?.status ?? "unknown"}`,
+        `step=${next.signal?.step ? stepLabel(next.signal.step) : "none"}`
+      ], " "),
+      ...(next.acceptance ?? []).map((row) => `${row.id} ${row.status?.verdict ?? "no verdict"} ${row.text}`),
+      ...next.prepare ? [`prepare ${next.prepare.step} started (${next.prepare.completed}/${next.prepare.total} steps)`] : []
+    ];
   }
   const lines = [];
+  for (const step of next.prepare?.steps ?? []) {
+    if (!previous.prepare?.steps.some((prior) => prior.id === step.id && prior.status === step.status)) {
+      lines.push(`prepare ${step.id} ${step.status} (${formatDuration(step.durationMs)})`);
+    }
+  }
+  if (next.prepare && (previous.prepare?.step !== next.prepare.step || previous.prepare.startedAt !== next.prepare.startedAt)) {
+    lines.push(`prepare ${next.prepare.step} started (${next.prepare.completed}/${next.prepare.total} steps)`);
+  }
   const before = new Map(previous.checklist.map((row) => [row.number, row.checked]));
+  const beforeAcceptance = new Map(previous.acceptance?.map((row) => [row.id, row.status?.verdict]));
+  for (const row of next.acceptance ?? []) {
+    if (beforeAcceptance.get(row.id) !== row.status?.verdict || !beforeAcceptance.has(row.id)) {
+      lines.push(`${row.id} ${row.status?.verdict ?? "no verdict"} ${row.text}`);
+    }
+  }
   for (const row of next.checklist) {
     if (!row.checked || before.get(row.number) === true) continue;
     lines.push(`checked ${row.number} ${row.label}${row.durationMs !== void 0 ? ` (${formatDuration(row.durationMs)})` : ""}`);
@@ -254,6 +289,7 @@ export {
   changedLines,
   formatDuration,
   handleStatusTaskView,
+  renderAcceptanceLines,
   renderTaskView,
   runStatusWatch
 };