@deeeed/metamask-harness 0.82.1 → 0.84.0

package/dist/mm-harness-cli.js

@@ -1,983 +1,186 @@
 import "./host.js";
+import "./adapters/surface.js";
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { Command } from "commander";
-import { color, withCommandJournal, JsonStreamWriter, detectAdapter, handleCallHelp } from "@farmslot/recipe-cli/harness";
-import { handleUpdate, maybeNudge } from "./commands/update.js";
-import { handlePin } from "./commands/pin.js";
-import { metaMaskEngine } from "./engine.js";
+import {
+  createHarnessCli,
+  detectAdapter,
+  handleActions,
+  handleCall,
+  handleHarness,
+  handleLast,
+  handleLaunch,
+  handleReload,
+  handleRun,
+  handleStop,
+  harnessHost,
+  parseArgs,
+  targetPath
+} from "@farmslot/recipe-cli/harness";
+import { stopProjectCollector } from "../library/actions/shared/analytics/collector.mjs";
+import { adoptPluginAdapter, afterAdapterLoad, configuredLibrarySources } from "./adapters/plugin-surface.js";
+import { adapterRegistry } from "./adapters/registry.js";
+import {
+  explainMissingAdapterLibrary,
+  HIDDEN_COMMANDS,
+  PUBLIC_COMMANDS,
+  REPLACED_OPTIONS
+} from "./command-contract.js";
+import { handleCheck } from "./commands/check.js";
+import { handleChecklist } from "./commands/checklist.js";
+import { handleCompletionCandidates, invalidateCompletionCache } from "./commands/completion-candidates.js";
+import { handleConfig } from "./commands/config.js";
+import { handleDebug } from "./commands/debug.js";
+import { applyDeviceTargeting } from "./commands/device-target.js";
+import { handleDoctor } from "./commands/doctor.js";
+import { handleDomain } from "./commands/domain.js";
+import { handleEnsureReady } from "./commands/ensure-ready.js";
+import { handleExecutionTemplate } from "./commands/execution-template.js";
+import { handleFixtures } from "./commands/fixtures.js";
 import { handleHelp } from "./commands/help.js";
-import { handleTutorial } from "./commands/tutorial.js";
+import { handleLogs } from "./commands/logs.js";
+import { overlayCommandOptions } from "./commands/overlay.js";
+import { handlePin } from "./commands/pin.js";
+import { handlePrBody } from "./commands/pr-body.js";
+import { handlePrepare } from "./commands/prepare.js";
+import { handleProvision } from "./commands/provision.js";
+import { handleRecipeQuality } from "./commands/recipe-quality.js";
+import { handleResolveExtension } from "./commands/resolve-extension.js";
+import { handleReview } from "./commands/review.js";
+import { handleRuntimeDecision } from "./commands/runtime-decision.js";
+import { handleRuntimeHealth } from "./commands/runtime-health.js";
+import { handleRuntimeLaunch } from "./commands/runtime-launch.js";
+import { handleSelfTest } from "./commands/self-test.js";
 import { handleSetupBase } from "./commands/setup-base.js";
-import { loadSelectedAdapter } from "./adapters/plugin-surface.js";
-import { getAdapterSurface } from "./adapters/surface.js";
+import { handleStatus } from "./commands/status.js";
+import { handleTaskInit } from "./commands/task-init.js";
+import { handleTutorial } from "./commands/tutorial.js";
+import { handleUpdate, maybeNudge } from "./commands/update.js";
+import { metaMaskEngine } from "./engine.js";
 import { ActionManifestError } from "./manifest.js";
+import { walletFixturePath } from "./paths.js";
 import { configPath, hydrateLibraryPathEnv, readConfig } from "./review/knowledge.js";
-import {
-  PUBLIC_COMMAND_CONTRACTS,
-  publicCommandNames,
-  validatePublicInvocation
-} from "./command-contract.js";
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-globalThis.__MM_HARNESS_WRAPPER__ = true;
-const { main: recipeMain } = await import("./cli.js");
-const rawArgv = process.argv.slice(2);
-const REAL = [
-  {
-    name: "help",
-    summary: "Load the version-matched recipe guide for a person or agent.",
-    example: "mm-harness help",
-    helpText: `mm-harness help [flags]
-
-  Loads the complete recipe guide shipped with this harness.
-
-  --adapter <mobile|extension|core|terminal>  Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --json                             Load the same guide as structured agent context
-
-  help review [--domain <name>] prints the review guide: the base review every PR
-  gets, plus the team library's anti-pattern families, parity rule, and shared
-  package notes when --domain names a library (see mm-harness review --help).
-
-Example:
-  mm-harness help
-  mm-harness help --json
-  mm-harness help review --domain perps`
-  },
-  {
-    name: "review",
-    summary: "Materialize a review checklist: base review + team library patterns + parity + verdict.",
-    example: "mm-harness review checklist --domain perps",
-    helpText: `mm-harness review checklist [flags]
-
-  Writes a phase-structured checklist (Setup, Base review, Domain patterns,
-  Parity, Verdict) that mm-harness checklist mark can track. Domain patterns are
-  one line per "##" section of the library's review/antipatterns.md; Parity names
-  the other platform's checkout when one resolves and says "not checked" otherwise.
-
-  Library resolution for --domain <name>: RECIPE_LIBRARY_PATH entry \u2192 engineer
-  config (mm-harness config) \u2192 sibling directory beside the checkout \u2192 shallow
-  fetch into <checkout>/.skills-cache/<name> (known libraries only). Reference
-  checkout resolution: MM_HARNESS_REF_<ADAPTER> \u2192 engineer config \u2192 sibling
-  checkout of that adapter.
-
-  --domain <name>   Team library to compose (default: MM_HARNESS_DOMAIN; none = base review only)
-  --since <sha>     Incremental re-review: scope the checklist to <sha>..HEAD
-  --base <ref>      Base ref for the diff range (default: origin/main when present)
-  --out <file>      Also write the checklist to <file>
-  --adapter, --target, --json
-
-Example:
-  mm-harness review checklist --domain perps
-  mm-harness review checklist --domain perps --since 4dd9be9 --out temp/tasks/review/CHECKLIST.md
-  mm-harness review checklist --json`
-  },
-  {
-    name: "domain",
-    summary: "Which team library owns the change: declared value first, else owned-paths.json against the changed files.",
-    example: "mm-harness domain",
-    helpText: `mm-harness domain [flags]
-
-  Prints the domain name (or "none"). A declared --domain / MM_HARNESS_DOMAIN wins;
-  otherwise the changed files (base...HEAD, working tree, untracked) are matched
-  against owned-paths.json in every reachable library (RECIPE_LIBRARY_PATH,
-  mm-harness config, sibling directories, .skills-cache).
-
-  --domain <name>   Declared domain (skips classification)
-  --base <ref>      Base ref for the changed-file range (default: origin/main when present)
-  --adapter, --target, --json
-
-Example:
-  mm-harness domain
-  mm-harness domain --json`
-  },
-  {
-    name: "pr-body",
-    summary: "Render the publishable PR body: the authored description plus the recipe and run log sections built from artifacts.",
-    example: "mm-harness pr-body render temp/tasks/dev/TAT-1",
-    helpText: `mm-harness pr-body render <task-dir> [flags]
-
-  Reads <task-dir>/artifacts/pr-description.md (the PR body the worker wrote in
-  the repository PR template shape) and inserts the machine sections rendered
-  from artifacts: "Validation Recipe" from artifacts/recipe.json, "Validation
-  Logs" from artifacts/recipe-run/report.md, and "Recipe Workflow" from
-  artifacts/workflow.mmd when it exists. Any such section the worker pasted by
-  hand is replaced. The sections go before the first checklist section, else at
-  the end. Fences are always longer than any backtick run in the content and
-  close on their own line. Writes <task-dir>/artifacts/pr-body.md.
-
-  --command <text>  Recipe invocation to show above the run log
-  --out <file>      Write elsewhere than artifacts/pr-body.md
-  --json            Machine-readable result
-
-Example:
-  mm-harness pr-body render temp/tasks/dev/TAT-1 --json`
-  },
-  {
-    name: "config",
-    summary: "Per-engineer locations and optional recipe advisor settings.",
-    example: "mm-harness config set references.extension ~/dev/metamask-extension",
-    helpText: `mm-harness config <list|path|get <key>|set <key> <value>|unset <key>> [--json]
-
-  Stored outside every repo in ~/.mm-harness/config.json (override: MM_HARNESS_CONFIG).
-  Keys: libraries.<name> (team library checkout), references.<mobile|extension|core|terminal>
-  (the checkout used as the parity reference), advisor.enabled (true/false),
-  advisor.provider, advisor.model, advisor.stages (plan,draft,evidence). Advisor
-  settings contain no credentials and default to disabled with planning only.
-  Env always wins over location config:
-  RECIPE_LIBRARY_PATH for libraries, MM_HARNESS_REF_<ADAPTER> for references.
-
-Example:
-  mm-harness config set libraries.perps ~/dev/experimental-metamask-recipe-perps
-  mm-harness config set references.extension ~/dev/metamask-extension
-  mm-harness config set advisor.provider typesafe
-  mm-harness config set advisor.enabled true
-  mm-harness config list`
-  },
-  {
-    name: "tutorial",
-    summary: "Open the protected visual recipe tutorial.",
-    example: "mm-harness tutorial",
-    helpText: `mm-harness tutorial [flags]
-
-  Source checkouts open the local tutorial on port 8765. Installed releases
-  open the protected MetaMask GitHub Pages site.
-
-  --no-open                          Print the tutorial URL without opening it
-  --json                             Print version, URL, and open status as JSON
-
-Example:
-  mm-harness tutorial`
-  },
-  {
-    name: "setup-base",
-    summary: "Bootstrap numbered MetaMask product checkouts and install their dependencies.",
-    example: "mm-harness setup-base --only core --counts core=1",
-    helpText: `mm-harness setup-base [flags]
-
-  Bootstrap numbered MetaMask Extension, Mobile, and Core checkouts under one
-  base directory, then run each checkout's pinned dependency install.
-
-  --dir <base>                       Destination root
-  --counts <repo=n,...>              Copies per selected repository
-  --only <extension,mobile,core>     Repository subset
-  --dry-run                          Print the plan without changing anything
-  --force                            Override the free-space refusal
-  --json                             Machine-readable terminal summary
-  --show-config                      Print saved preferences and exit
-  --reset-config                     Remove saved preferences and exit
-  --skip-harness-update              Skip the installed-version notice
-
-Example:
-  mm-harness setup-base --only core --counts core=1`
-  },
-  {
-    name: "status",
-    aliases: ["health", "home"],
-    summary: "Home dashboard for a checkout: detected adapter, next command, and (mobile) connected devices with the selected target.",
-    example: "mm-harness status",
-    helpText: `mm-harness status [flags]
-
-  Home dashboard for the current checkout \u2014 the detected adapter, the next command
-  to run, and (mobile only) the connected devices with live app state. Aliases: health, home.
-
-  --target <path>                    Checkout path (default: cwd)
-  --json                             Machine-readable envelope { adapter, target, view, devices[], next }
-  --fast                             Skip all live-state probes (instant output, safe for scripts)
-  --all-devices                      Mobile only: show every connected device instead of the slot-scoped target
-  --watch                            Live read-only view of the task this checkout is working through (refreshes every 2s, Ctrl-C to leave)
-  --task <dir>                       Task directory for the view (default: the most recently marked one under temp/tasks/)
-
-  The task view reads task files only \u2014 no probe, no launch, no write \u2014 and shows
-  the same facts whether a skill or a control plane started the run: slot and
-  device isolation, template and flow, fixture and sandbox readiness, then the
-  checklist with the time each row took, how long the current row has been
-  running, and acceptance criteria with recorded verdicts. The home dashboard
-  also shows criteria for an ongoing task. --task without --watch prints it once.
-  With --json, --watch emits one
-  object per change (newline-delimited) instead of redrawing.
-
-  The checkout view (also under "view" in --json, and printed by doctor) is what
-  this checkout is bound to: the runtime-context fields that keep it off other
-  slots' ports and devices, the recipe libraries this machine resolves, and the
-  wallet fixture it last applied.
-
-  Human output: static device list prints immediately; live-state lines append
-  after the ~2s probe window (screen, wallet, account, fixture per device).
-  By default mobile status shows the configured target only; --device <id>
-  switches the active target for that command. Other devices that answer on the
-  same Metro are reported as additional reachable targets.
-
-  The devices[] section carries per device:
-    { platform, id, name, state, selected }   always present
-    { currentScreen, walletState, selectedAccount, fixtureStatus }  when bridge reachable
-    { liveState: 'no-bridge' }   when bridge unreachable or --fast
-
-  All RN targets attached to the checkout's Metro are probed and matched to their
-  devices; a device whose target cannot be confidently matched (Metro's device
-  description matches neither the serial nor the model name) degrades to
-  liveState:'no-bridge'. An attached target whose build predates __AGENTIC__
-  reports liveState:'bridge-absent'.
-  Extension/core live-state probing is V1-pending (use doctor for runtime status).
-
-Example:
-  mm-harness status
-  mm-harness status --json
-  mm-harness status --fast
-  mm-harness status --watch`
-  },
-  {
-    name: "checklist",
-    summary: "Mark checklist progress and close out scrubbed learning packages.",
-    example: "mm-harness checklist mark <task-dir> start",
-    helpText: `mm-harness checklist <mark|closeout> <task-dir> [step] [options]
-
-  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 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
-
-Example:
-  mm-harness checklist mark temp/tasks/recipe-cook/<task> start
-  mm-harness checklist mark temp/tasks/recipe-cook/<task> 1
-  mm-harness checklist mark temp/tasks/recipe-cook/<task> sub start qa-cases --step 2 --from inputs/qa-cases.md
-  mm-harness checklist mark temp/tasks/recipe-cook/<task> sub qa-cases 1
-  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|terminal> Force the platform (auto-detected inside a checkout)
-  --mobile-platform <ios|android>    Mobile target when status cannot decide it
-  --clear-metro                      Mobile only: clear Metro's transform cache in the launch step
-  --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 --template fix-bug/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
-  --acceptance <criterion>          Authored acceptance criterion (repeatable, preserved in order)
-  --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 (optional;
-                                     set by the Farmslot control plane, omit for
-                                     skill/manual runs)
-  --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 \\
-    --template fix-bug/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.",
-    example: "mm-harness execution-template list --package-templates <path> --json",
-    helpText: `mm-harness execution-template <list|materialize|lint|new> [options]
-
-  Shared Markdown checklist catalog used by direct and orchestrated workflows.
-  Sources use the flow-tree shape <root>/<flow>/<variant>.md.
-
-  list        List compatible templates and portable source provenance.
-  materialize Select one template, copy its immutable snapshot, and optionally
-              write a provenance record.
-  lint        Validate one template file or flow-tree directory.
-  new         Create a minimal starter template.
-
-Common source/filter options:
-  --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
-  --flow <flow>                      Exact flow
-  --platform <platform>              Exact platform
-  --run-mode <mode>                  autonomous|interactive|validation (optional;
-                                     set by the Farmslot control plane, omit for
-                                     skill/manual runs)
-  --domain <domain>                  Exact domain
-  --id <id>                          Exact template id
-  --json                             Machine-readable output
-
-Materialize:
-  mm-harness execution-template materialize <output> --flow fix-bug \\
-    --platform mobile --id fix-bug/mobile \\
-    --package-templates <path> --provenance <path> --json`
-  },
-  {
-    name: "actions",
-    summary: "Discover typed single operations and their fields.",
-    example: "mm-harness actions --adapter mobile",
-    helpText: `mm-harness actions [query] [flags]
-
-  Discover typed single operations and their field schemas for this checkout.
-
-  query                              Search names, categories, fields, and descriptions (typo-tolerant)
-  --action <name>                    Describe one action; fuzzy-resolves like call (short or full name)
-  --matrix                           Compare action availability across Mobile, Extension, Core, and Terminal
-  --categories                       List compact action categories and counts
-  --category <name>                  List only one category (for example ui, wallet, or perps)
-  --adapter <mobile|extension|core|terminal>  Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --raw                              Dump raw action registry JSON
-  --json                             Machine-readable output
-
-Example:
-  mm-harness actions --adapter mobile
-  mm-harness actions --matrix --json
-  mm-harness actions positions --adapter mobile
-  mm-harness actions --adapter mobile --categories --json
-  mm-harness actions --adapter mobile --category ui --json
-  mm-harness actions --adapter mobile --action assert_orders
-  mm-harness actions --adapter extension --raw`
-  },
-  {
-    name: "stop",
-    summary: "Stop this checkout runtime (mobile Metro / Extension watcher + owned browser) and close its log windows.",
-    example: "mm-harness stop",
-    helpText: `mm-harness stop [flags]
-
-  Stop the runtime this checkout owns and close its tmux log-tail windows,
-  scoped to this checkout so concurrent slots are untouched. Idempotent \u2014
-  nothing running is success, not an error. Behavior is per platform:
-    mobile     stop the port-scoped Metro dev server
-    extension  stop webpack watcher, owned Chrome/CDP profile processes, viewers, and stale markers
-    core       headless \u2014 no dev server to stop (teaching error)
-
-  --port <port>                      Metro/webpack port override; Extension CDP remains checkout-context scoped
-  --adapter <mobile|extension|core|terminal>  Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --json                             Machine-readable output
-
-Example:
-  mm-harness stop
-  mm-harness stop --port 8061`
-  },
-  {
-    name: "call",
-    summary: "Run one action in isolation as a one-node recipe through the real engine path (fuzzy short names; --arg k=v; same trace/evidence as run).",
-    example: "mm-harness call ensure_unlocked",
-    helpText: `mm-harness call <action> [key=value ...] [--arg k=v ...] [flags]
-
-  Run one action in isolation as a one-node recipe through the real engine path.
-  Fuzzy short-name: 'ensure_unlocked' resolves to 'metamask.wallet.ensure_unlocked'
-  if unique; ambiguous = exit 2. Pass action fields as key=value shorthand or
-  with --arg k=v; numbers, booleans, arrays, and objects are parsed as JSON-like values.
-  Actions differ per adapter \u2014 list this checkout's with:
-  mm-harness actions.
-
-  --list                             List actions accepted by call for this adapter; no <action> needed
-  --domain <name>                    With --list: filter by action domain, e.g. perps or swap-bridge
-  --source <name>                    With --list: filter by origin, e.g. metamask, perps, or official
-  --sort <domain|name|library>       With --list: grouping/order (default: domain; JSON: name)
-  --arg k=v                          Action field value (repeatable; equivalent to key=value shorthand)
-  --device <udid|serial|name>        Mobile only: target this device (sets IOS_SIMULATOR / ADB_SERIAL and updates agentic-runtime.json). Without it, >1 connected mobile device fails fast and lists them. Do not shut down other devices to force selection.
-  --cdp-port <port>                  Extension only: bind the action to this live browser runtime.
-  --adapter <mobile|extension|core|terminal>  Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --artifacts-dir <dir>              Where to write evidence (default: temp dir)
-  --action-manifest <path>           Override the action manifest
-  --library <name=path>              Add/override a recipe-library source (repeatable)
-  --heal <off|infra-only|auto>       Healing policy (default: infra-only); auto-ensures the overlay
-  --json                             Machine-readable output
-
-Example (real actions; run mm-harness actions for this checkout's full set):
-  mm-harness call ensure_unlocked --adapter extension   # a wallet action (extension/mobile)
-  mm-harness call navigate page=perps --adapter mobile
-  mm-harness call command cmd="echo hi" --adapter core   # the universal action (all adapters)
-
-Remote feature flags (mobile applies at runtime; extension pins at launch):
-  mm-harness call metamask.feature_flags.read --adapter mobile
-  mm-harness call metamask.feature_flags.set --adapter mobile \\
-    --arg 'flags={"perpsTAT3938AbtestScreenVsBottomSheet":"treatment"}'
-  mm-harness call metamask.feature_flags.clear --adapter mobile`
-  },
-  {
-    name: "run",
-    summary: "Execute a complete proof and write its evidence.",
-    example: "mm-harness run recipe.json",
-    helpText: `mm-harness run <recipe|recipe.json> [key=value ...] [flags]
-
-  Validate and execute a complete proof, then write summary, trace, diagnostics,
-  and artifacts. Inside a checkout, the adapter, target, ports, and artifact
-  directory are normally detected automatically.
-
-Discovery:
-  --list                             List complete recipes accepted by run for this adapter; no <recipe> needed
-  --domain <name>                    With --list: filter by recipe domain, e.g. perps or swap-bridge
-  --source <name>                    With --list: filter by library origin, e.g. metamask or perps
-  --sort <domain|name|library>       With --list: grouping/order (default: domain; JSON: name)
-  --describe                         Show one recipe's parameters, composed actions/recipes, and runnable command
-  --plan                             Validate + print execution plan, touching nothing. Exit 5 if invalid.
-  --proof                            Preflight behavioral proof bindings before planning/execution; runtime evidence is still required.
-
-Common overrides:
-  --device <udid|serial|name>        Mobile only: target this device (sets IOS_SIMULATOR / ADB_SERIAL and updates agentic-runtime.json). Without it, >1 connected mobile device fails fast and lists them. Do not shut down other devices to force selection.
-  --adapter <mobile|extension|core|terminal>  Target adapter (auto-detected inside a checkout)
-  --platform <ios|android>           Mobile platform preference; use --adapter for the product adapter
-  --target <path>                    Checkout path (default: cwd)
-  --artifacts-dir <dir>              Override evidence output (default: active task/artifacts, otherwise a checkout-local temp/recipe/runs/<run>)
-  --funding-request <absolute-file>  Original consented mutation request for external-mutation actions
-  --funding-preflight <absolute-file> Eligible funding preflight bound to the request bytes
-  --funding-release-proof <absolute-file> Exact release proof independently bound to funding eligibility
-  --funding-balance-proof <absolute-file> Exact balance proof and contained visible evidence chain
-  --library <name=path>              Add/override a recipe-library source (repeatable)
-  --heal <off|infra-only|auto>       Healing policy (default: infra-only); auto-ensures the overlay
-  --json                             Machine-readable output
-  --json-stream                      Line-flushed JSONL progress + terminal event
-  --record-video=full-run            Record a video of the run
-  --hud <auto|show|hide>             Recipe HUD policy (auto shows normal Mobile recipes and a headful terminal browser; hide is explicit)
-
-Advanced integrations:
-  runtime: --cdp-port, --watcher-port/--metro-port, --runtime-dir, --slot,
-           --validation-runtime-dir, --launch-existing-dist
-  managed trust boundary (not needed for normal runs; Farmslot supplies it):
-           --source-trust, --source-kind, --source-name, --source-digest,
-           --approve-plan (binds approval to the exact reviewed plan)
-  schema:  --action-manifest
-
-Example:
-  mm-harness run wallet.smoke --describe
-  mm-harness run perps.release-market-search query=Bitcoin --plan --adapter mobile
-  mm-harness run recipe.json market=ETH --adapter extension`
-  },
-  {
-    name: "last",
-    summary: "Show the last significant command, verdict, timestamps, and evidence paths for this checkout.",
-    example: "mm-harness last --json",
-    helpText: `mm-harness last [flags]
-
-  Read the atomic per-checkout resumability journal. Discovery commands do not
-  replace it, and an interrupted process remains recorded as verdict=running.
-
-  --target <path>                    Checkout path (default: cwd)
-  --runtime-dir <dir>                Runtime dir containing command operation records
-  --json                             Machine-readable envelope
-
-Example:
-  mm-harness last --json`
-  },
-  {
-    name: "doctor",
-    summary: "Readiness check for a checkout \u2014 no app launch. --fix repairs the overlay/runtime without launching.",
-    example: "mm-harness doctor",
-    helpText: `mm-harness doctor [flags]
-
-  Readiness check for a checkout \u2014 no app launch. Reports the same checkout view
-  status does \u2014 runtime-context isolation, resolved recipe libraries, and the last
-  applied wallet fixture \u2014 so there is no hunting for files.
-
-  --fix                              Repair the overlay/runtime-context WITHOUT launching (no fixture reseed); --json adds fixed[]/failed[]
-  --expect-live                      Exit-coded liveness gate only (human verdict on stderr). Use without --print-ready when callers need pass/fail without a Farmslot indicator line
-  --print-ready                      Farmslot health_check mode: implies --expect-live and prints health.ready_indicator on stdout (extension/mobile: OK; core: ready)
-  --cdp-port <port>                  Extension CDP port for the liveness probe (env: CDP_PORT / RECIPE_CDP_PORT)
-  --device <udid|serial|name>        Mobile only: target this device (env: IOS_SIMULATOR / ADB_SERIAL). doctor reports the connected devices; it never gates on ambiguity.
-  --all-devices                      Mobile only: show every connected device instead of the slot-scoped target
-  --adapter <mobile|extension|core|terminal>  Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --runtime-dir <dir>                Runtime dir containing agentic-runtime.json (relative to target)
-  --json                             Machine-readable output (incompatible with --print-ready)
-
-Example:
-  mm-harness doctor
-  mm-harness doctor --fix --json
-  mm-harness doctor --adapter extension --target /path/to/checkout --cdp-port 6662 --print-ready
-  mm-harness doctor --adapter mobile --target /path/to/checkout`
-  },
-  {
-    name: "check",
-    summary: "Run bounded repo-local checks for an active git diff and write validation artifacts.",
-    example: "mm-harness check diff --profile fast",
-    helpText: `mm-harness check diff [flags]
-
-  Run bounded repo-local checks for the active git diff. Fast profile runs changed-file
-  ESLint, Prettier, and changed test files. Full profile also runs repo typecheck
-  when available. Does not launch an app or run a recipe.
-
-  --target <path>                    Checkout path (default: cwd)
-  --adapter <mobile|extension|core|terminal>  Adapter label (auto-detected when possible)
-  --base <ref>                       Diff base (default: PR base, then remote HEAD, then repo fallback)
-  --profile <fast|full>              Validation depth (default: fast)
-  --fix                              Fix changed files, then validate them
-  --artifacts-dir <dir>              Write validation-summary.json/.md and per-check logs
-  --json                             Machine-readable envelope
-
-Example:
-  mm-harness check diff --fix --profile fast --artifacts-dir artifacts/validation
-  mm-harness check diff --profile full --json`
-  },
-  {
-    name: "recipe-quality",
-    summary: "Build canonical recipe quality or request optional recipe advice.",
-    example: "mm-harness recipe-quality build --input compact.json --output artifacts/recipe-quality.json",
-    helpText: `mm-harness recipe-quality build|plan|advise|advisor-status [flags]
-
-  Build artifacts/recipe-quality.json from the compact fields a recipe-quality pass
-  produces (verdict + reasons + optional guidance/dimensions/findings/delta/training).
-  The artifact is validated against the RecipeQualityArtifact schema before it is
-  written \u2014 an invalid input never reaches disk. Shorthand without "build" is
-  also accepted when --input/--output are present.
-
-  Apply the quality bar from mm-harness help to the real graph and
-  evidence, then use this command to build the canonical artifact from that
-  compact verdict. An optional independent reviewer may still critique it.
-
-  --input <compact.json>   Compact verdict JSON: { "verdict": "pass|warn|fail", "reasons": [..],
-                             "betterVersionGuidance"?: [..], "dimensions"?: {..}, "trainingFields"?: {..}, \u2026 }
-  --output <path>          Where to write the built artifact (parent dirs created)
-  --json                   Machine-readable envelope { status, outputPath, artifact }
-
-  Exit: 0 built \xB7 2 missing/unreadable args \xB7 5 invalid input (teaching escape names the invalid field).
-
-Optional advice:
-  advisor-status --json
-    Resolve saved settings and overrides without reading tasks or calling a model.
-  plan --task <task.json> --adapter <mobile|extension|core|terminal> --advisor typesafe
-    Assess each acceptance criterion before a recipe exists. Task JSON contains
-    acceptanceCriteria: ["criterion", "..."] (1\u201320 entries), with optional title/description.
-    Returns known candidate refs for reuse/composition, or an explicit discovery gap.
-  advise --recipe <recipe.json> --task <TASK.md> --adapter <mobile|extension|core|terminal>
-    --advisor <provider|off> Override saved policy for this task (currently: typesafe)
-    --advisor-model <model> Override the provider default model or alias
-    --advisor-stages <csv>   Select plan,draft,evidence (saved/default: plan)
-    --evidence <file.json>    Explicit trace, summary, or evidence metadata to review
-    --params <json>          Root recipe parameter values
-    --library <name=path>    Resolve the same library sources as run (repeatable)
-    --output <advice.json>   Optional separate advisory artifact
-
-  Precedence: explicit CLI > MM_HARNESS_ADVISOR[_MODEL|_STAGES] > advisor settings > disabled.
-  Set MM_HARNESS_ADVISOR to a provider or off for a Farmslot run. A key never enables advice.
-  Saved settings only run selected stages; an explicit --advisor call can request a stage directly.
-  --advisor off disables calls regardless of saved settings. No disabled advice artifact is written.
-  TypeSafe uses TYPESAFE_API_KEY. Missing keys skip advice; provider failures report unavailable.
-  Results record provider, requestedModel, and the model that answered.
-  Advice never changes recipe execution, canonical quality, or existing exit status.
-  Input must be statically valid. Context beyond the bound is skipped, never truncated.
-
-Example:
-  mm-harness recipe-quality build --input compact.json --output artifacts/recipe-quality.json
-  mm-harness recipe-quality --input compact.json --output artifacts/recipe-quality.json
-  mm-harness recipe-quality build --input compact.json --output artifacts/recipe-quality.json --json
-  mm-harness recipe-quality advise --recipe artifacts/recipe.json --task TASK.md --adapter extension --advisor typesafe --output artifacts/recipe-advice.json --json
-  mm-harness recipe-quality plan --task task.json --adapter extension --advisor typesafe --output artifacts/recipe-plan.json --json`
-  },
-  {
-    name: "provision",
-    summary: "Install the cached Runway iOS dev client on a prepared mobile slot (no deps, no Metro).",
-    example: "mm-harness provision runway ios --adapter mobile",
-    helpText: `mm-harness provision [runway ios] [flags]
-
-  Install the cached Runway iOS dev client on the slot simulator. This is a thin
-  provisioning path only: artifact cache + simulator create + simctl install.
-  JavaScript dependencies and Metro remain dispatch-time launch concerns.
-
-  --adapter <mobile|extension|core|terminal>  Target adapter (mobile supported; extension/core/terminal teach)
-  --target <path>                    Slot checkout path (default: cwd)
-  --platform <ios>                   Platform (default ios)
-  --simulator <name|udid>            Override agentic-runtime.json simulator (alias: --device)
-  --device <name|udid>               Alias for --simulator
-  --slot <id>                        Farm slot id recorded in the provision baseline
-  --watcher-port <port>              Farm Metro/watcher port carried through context and Next:
-  --runtime-dir <dir>                Runtime dir containing agentic-runtime.json (relative to target)
-  --runtime <id>                     iOS runtime id used if simulator must be created
-  --device-type <id>                 Device type id used if simulator must be created
-  --branch <ref>                     Probe this ref before default branch
-  --default-branch <ref>             Fallback ref (default main)
-  --run <id>                         Exact GitHub Actions run id
-  --cache-root <dir>                 Override shared runway cache root
-  --force                            Reinstall even when the app is already present
-  --resolve-only                     Resolve artifact metadata only; no simulator/cache/install
-  --json                             Machine-readable envelope; progress stays stderr
-
-Example:
-  mm-harness provision runway ios --adapter mobile --target /path/to/slot
-  mm-harness provision runway ios --adapter mobile --slot scratch-1 --runtime-dir temp/recipe/runtime-8081
-  mm-harness provision runway ios --run 28676856835 --resolve-only --json`
-  },
-  {
-    name: "install",
-    summary: "Install the per-checkout runtime overlay, or --runway to install a cached mobile dev client.",
-    example: "mm-harness install",
-    helpText: `mm-harness install [flags]
-
-  Install the per-checkout runtime overlay (for CI / agents).
-  Add --runway on a mobile slot to install the cached Runway iOS dev client only:
-  artifact cache + simulator create + simctl install. JavaScript dependencies
-  and Metro remain dispatch-time launch concerns.
-
-  --adapter <mobile|extension|core|terminal>  Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --runway                           Thin mobile Runway artifact install instead of overlay install
-  --platform <ios>                   Runway platform (default ios)
-  --simulator <name|udid>            Override agentic-runtime.json simulator
-  --runtime <id>                     iOS runtime id used if simulator must be created
-  --device-type <id>                 Device type id used if simulator must be created
-  --branch <ref>                     Probe this ref before default branch
-  --default-branch <ref>             Fallback ref (default main)
-  --run <id>                         Exact GitHub Actions run id
-  --cache-root <dir>                 Override shared runway cache root
-  --force                            Reinstall even when the app is already present
-  --resolve-only                     Runway metadata only; no simulator/cache/install
-
-Example:
-  mm-harness install
-  mm-harness install --adapter extension --target /path/to/checkout
-  mm-harness install --runway --adapter mobile --target /path/to/slot`
-  },
-  {
-    name: "verify",
-    summary: "Check the overlay/runtime is present and healthy (no launch).",
-    example: "mm-harness verify",
-    helpText: `mm-harness verify [flags]
-
-  Check the runtime overlay is present and healthy (no app launch).
-  Extension live checks infer the checkout CDP port from runtime context,
-  pool, or slot suffix when --cdp-port is omitted.
-
-  --adapter <mobile|extension|core|terminal>  Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --json                             Machine-readable output
-
-Example:
-  mm-harness verify
-  mm-harness verify --adapter core --target /path/to/checkout`
-  },
-  {
-    name: "cleanup",
-    summary: "Remove the installed overlay and restore the checkout.",
-    example: "mm-harness cleanup",
-    helpText: `mm-harness cleanup [flags]
-
-  Remove the installed overlay and restore the checkout.
-
-  --adapter <mobile|extension|core|terminal>  Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-
-Example:
-  mm-harness cleanup
-  mm-harness cleanup --adapter mobile --target /path/to/checkout`
-  },
-  {
-    name: "launch",
-    summary: "Launch the app and adapter dev server, auto-ensuring the runtime overlay first. Mobile: ios|android required.",
-    example: "mm-harness launch ios",
-    helpText: `mm-harness launch [ios|android] [flags]
-
-  Launch the app \u2014 quick relaunch by default; --build for a full native/webpack build.
-  Mobile: target is MANDATORY (ios | android). Extension: no target (--fullscreen default;
-  --sidepanel to override). core is headless (teaching error \u2014 use verify/run).
-  Terminal: starts or reuses the slot browser (visible by default) against the slot dev server.
-  Extension quick launch REUSES a healthy live runtime (reload in place, no rebuild);
-  --build is the escape hatch that always clean-builds + relaunches a fresh runtime.
-
-  --build                            Full production-like build + relaunch (escape hatch; skips extension reuse)
-  --clear-metro                      Mobile only: clear Metro's transform cache before launch
-  --verify                           Launch then poll CDP/bridge until ready (absorbs the old \`live\`)
-  --runway                           Post-launch runway check (mobile only; teaching error elsewhere)
-  --watch                            Persistent webpack watcher then relaunch (extension only)
-  --surface <fullscreen|sidepanel>   Extension display mode (default: fullscreen)
-  --sidepanel | --fullscreen         Legacy aliases for --surface
-  --url <dapp-url>                    Open a dapp beside the sidepanel (default: MetaMask test dapp)
-  --remote-flag <KEY=VALUE[,...]>    Pin remote feature flags. VALUE is a variant name (treatment),
-                                     true/false, or JSON. Mobile applies it through
-                                     RemoteFeatureFlagController once the bridge is ready and fails the
-                                     launch if it does not read back; Extension pins it into the per-run
-                                     dist snapshot manifest (so it skips the reuse fast path).
-  --heal <off|infra-only|auto>       Healing policy (default auto); bounds always enforced
-  --device <udid|name>               Target simulator/device (env: IOS_SIMULATOR / ADB_SERIAL)
-  --cdp-port <port>                  Extension CDP port (env: CDP_PORT / RECIPE_CDP_PORT)
-  --watcher-port <port>              Metro/webpack port (env: WATCHER_PORT / METRO_PORT)
-  --signer <extension|injected>      Terminal: MetaMask extension (default) or the injected test wallet
-  --account <name>                   Terminal: wallet-fixture account (default dev1)
-  --fresh-profile                    Terminal: start from a new browser profile
-  --headless                         Terminal: hide the browser (env: TERMINAL_HEADLESS=1); default is a
-                                     visible window placed per slot (--headful is accepted as the default)
-  --slow-mo <ms>                     Terminal: pause before each UI action (env: TERMINAL_SLOW_MO; default 0)
-  --network <testnet|mainnet>         Terminal: venue the slot dev server serves (default testnet)
-  --mainnet-confirmation <REAL_FUNDS> Terminal: required with --network mainnet (real funds)
-                                     Terminal flags are rejected for other adapters. The terminal launch
-                                     refuses unless the farm next dev server on --watcher-port forces
-                                     Hyperliquid testnet, or --network mainnet --mainnet-confirmation REAL_FUNDS
-                                     is passed (a recipe launch node carries network/mainnet_confirmation).
-  --adapter <mobile|extension|terminal> Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --json                             Machine-readable summary (recovered[] / mutations[] / phase)
-  --json-stream                      Line-flushed JSONL progress + terminal event
-
-Example:
-  mm-harness launch ios
-  mm-harness launch android --clear-metro --verify
-  mm-harness launch ios --build
-  mm-harness launch --verify --json
-  mm-harness launch --remote-flag perpsTAT3938AbtestScreenVsBottomSheet=treatment`
-  },
-  {
-    name: "logs",
-    summary: "Tail Metro/webpack + app logs for the active checkout.",
-    example: "mm-harness logs",
-    helpText: `mm-harness logs [flags]
-
-  Tail Metro/webpack + app logs for the active checkout.
-  Teaching error if nothing is running (points at launch).
-
-  --full                             Raw log tail (default = compact) (env: RECIPE_LOG_UI)
-  --window                           (Re)open the read-only tmux tail window for the resolved dev-server port (leaves the process untouched)
-  --events <n>                       Compact event count (default 10) (env: RECIPE_LOG_EVENTS)
-  --source <label>                   Log source per adapter \u2014 mobile: metro|app;
-                                     extension: extension|dapp|webpack|watcher|rebuild.
-                                     Core is headless (teaching error).
-  --adapter <mobile|extension|core|terminal>  Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --json                             Machine-readable output
-
-Example:
-  mm-harness logs
-  mm-harness logs --full
-  mm-harness logs --window`
-  },
-  {
-    name: "debug",
-    summary: "Open the debug console \u2014 extension: Chrome DevTools via CDP; mobile: RN DevTools.",
-    example: "mm-harness debug",
-    helpText: `mm-harness debug [flags]
-
-  Open the debug console \u2014 extension: Chrome DevTools via CDP; mobile: RN DevTools.
-
-  --worker                           Extension service-worker DevTools
-  --dev-menu                         Mobile RN developer menu
-  --no-open                          Resolve target/method/endpoint without opening a UI
-  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --json                             Machine-readable output
-
-Example:
-  mm-harness debug
-  mm-harness debug --worker`
-  },
-  {
-    name: "reload",
-    summary: "Reload the connected Mobile or Extension runtime without restarting its dev server.",
-    example: "mm-harness reload",
-    helpText: `mm-harness reload [flags]
-
-  Mobile broadcasts the same reload command as Metro's interactive r key.
-  Extension refreshes its loaded UI in place over CDP. Core is headless.
-
-  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --json                             Machine-readable output
-
-Example:
-  mm-harness reload`
-  },
-  {
-    name: "pin",
-    summary: "Copy this installed mm-harness into an immutable, versioned store and print the copy for a task to run, so a later global upgrade cannot change a running task.",
-    example: "mm-harness pin",
-    helpText: `mm-harness pin [flags]
-
-  Copies the installed mm-harness running this command into an immutable,
-  versioned store (~/.local/share/mm-harness/pins/<version>-<hash>/; APFS clone
-  where available) and prints the copy's executable. A task records that path,
-  so \`npm i -g\` upgrading the global install never changes the harness a running
-  task runs. Idempotent: the same install returns the same pin. A source checkout
-  (MM_HARNESS_BIN) or an existing pin is printed as is.
-
-  --json                             Machine-readable { version, source, executable, pinned, created }
-
-  MM_HARNESS_PIN_ROOT overrides the store location.
-
-Example:
-  mm-harness pin
-  mm-harness pin --json`
-  },
-  {
-    name: "update",
-    summary: "Update the installed mm-harness to the published latest (--check reports only; --json = {current, latest, updateAvailable}).",
-    example: "mm-harness update",
-    helpText: `mm-harness update [flags]
-
-  Update the globally-installed mm-harness to the npm registry's latest.
-  Bare form upgrades (npm i -g @deeeed/metamask-harness@latest) and prints old \u2192 new;
-  already-current exits 0.
-
-  --check                            Report only \u2014 exit 0 up-to-date / exit 1 update available (no install)
-  --json                             Machine-readable { current, latest, updateAvailable }
-
-  A passive once-a-day nudge also prints one stderr line when a newer version exists.
-  Silence it with MM_HARNESS_NO_UPDATE_CHECK=1 (auto-off in CI).
-
-Example:
-  mm-harness update
-  mm-harness update --check --json`
-  },
-  {
-    name: "runtime-launch",
-    summary: "Launch and verify an Extension runtime or local Android release artifact.",
-    example: "mm-harness runtime-launch --adapter extension --target <checkout> --cdp-port 9222 --artifact-file <zip> --artifact-version <X.Y.Z> --artifact-sha256 <digest>",
-    helpText: `mm-harness runtime-launch --adapter <extension|mobile> --target <checkout> [flags]
-
-  Verify and run an artifact already downloaded by the validation skill. The
-  harness performs no network acquisition. Extension ZIPs run through the
-  packaged browser/CDP path; Android APKs install to one explicitly named device.
-
-  --artifact-file <path>             Artifact downloaded by the validation skill
-  --artifact-version <X.Y.Z>         Expected manifest or Android version name
-  --artifact-build-id <id>           Android version code
-  --artifact-package-id <id>         Android application ID
-  --artifact-sha256 <digest>         Trusted SHA-256 from the acquisition step
-  --artifact-cache <dir>             Extension artifact cache root
-  --platform <android>               Mobile platform (downloaded iOS is unsupported)
-  --device <serial>                  Explicit Android device serial
-  --cdp-port <port>                  Extension CDP port
-  --chrome-user-data-dir <dir>       Isolated Chrome profile path
-  --reset-profile                    Explicitly clear that profile; default preserves wallet state
-  --artifacts-dir <dir>              Validation evidence directory
-  --start-watch                      Build through the checkout watcher
-  --build-lavamoat                   Build through the production-like path
-  --remote-flag <KEY=VARIANT>        Pin checkout snapshot flags (not allowed for artifacts)
-  --json                             Machine-readable terminal report
-
-Example:
-  mm-harness runtime-launch --adapter extension --target /path/to/checkout --cdp-port 9222 --artifact-file /path/to/metamask-chrome-X.Y.Z.zip --artifact-version X.Y.Z --artifact-sha256 <digest>
-  mm-harness runtime-launch --adapter mobile --platform android --target /path/to/checkout --device <serial> --artifact-file /path/to/app.apk --artifact-version X.Y.Z --artifact-build-id <code> --artifact-package-id io.metamask --artifact-sha256 <digest>`
-  },
-  {
-    name: "fixtures",
-    summary: "Manage the canonical wallet fixture (wallet DATA only) \u2014 init / sync / set / reset / generate / finalize.",
-    example: "mm-harness fixtures set",
-    helpText: `mm-harness fixtures [<init|sync|set|reset|generate|finalize>] [flags]
-
-  Manage the ONE canonical wallet fixture per checkout \u2014 wallet DATA only.
-  With no action, show the current fixture status and safe next command.
-  init       Create it from --from <path>, or explicitly choose --dev for a
-             disposable public test wallet that must never hold real funds.
-  sync       Refresh the wallet fixture files on the target.
-  set        Apply the canonical fixture (SRP/password/accounts); the password is
-             read FROM the fixture, never typed.
-  reset      Delete the current Mobile/Extension wallet, then apply and validate
-             the canonical fixture from a clean state.
-  generate   Render the extension fixture-state.json from a wallet fixture, for
-             pre-launch profile prefill (extension-only). Requires --fixture and --out.
-  finalize   Seed account labels/selection into the LIVE extension over CDP and
-             validate parity (extension-only, post-launch). Requires --fixture,
-             --state, --cdp-port, --extension-dir.
-  Want different accounts? Edit the fixture file directly:
-    <checkout>/temp/recipe/runtime/wallet-fixture.json
-
-  --from <path>                       Existing wallet fixture source (init)
-  --dev                               Create a disposable public test wallet (init)
-  --force                             Replace an existing canonical fixture (init)
-  --fixture <path>                   Wallet fixture path (generate/finalize input; agent override for set/sync \u2014 env: RECIPE_WALLET_FIXTURE)
-  --out <path>                       generate: output fixture-state.json; finalize: optional validation report
-  --state <path>                     finalize: the pre-launch fixture-state.json to seed
-  --cdp-port <port>                  finalize: CDP port of the running extension
-  --extension-dir <path>             finalize: loaded extension dist (e.g. dist/chrome)
-  --extension-id-file <path>         finalize: optional file to read/write the resolved extension id
-  --action-manifest <path>           Extension set: override the wallet action manifest
-  --remote-flag <KEY=VALUE[,...]>    set/reset: one-run override layered over the fixture's remoteFeatureFlags
-  --adapter <mobile|extension>       Target adapter (auto-detected inside a checkout)
-  --target <path>                    Checkout path (default: cwd)
-  --device <udid|serial|name>        Mobile only: target this device for sync/set
-  --json                             Machine-readable output
-
-Example:
-  mm-harness fixtures init --from /secure/path/wallet-fixture.json
-  mm-harness fixtures init --dev
-  mm-harness fixtures sync
-  mm-harness fixtures set
-  mm-harness fixtures reset
-  mm-harness fixtures generate --fixture wallet-fixture.json --out fixture-state.json
-  mm-harness fixtures finalize --fixture wallet-fixture.json --state fixture-state.json --cdp-port 6661 --extension-dir dist/chrome`
+function hostVersion() {
+  return JSON.parse(fs.readFileSync(path.join(harnessHost().packageRoot, "package.json"), "utf8")).version;
+}
+const stopOptions = {
+  companions: async (target) => {
+    const collector = await stopProjectCollector(target);
+    return collector.stopped && collector.pid !== null ? [{ label: "analytics collector", pid: collector.pid }] : [];
   }
-];
-const PUBLIC_COMMAND_EXAMPLES = Object.fromEntries(
-  REAL.map((command) => [command.name, command.example])
-);
-function assertPublicContractMatchesSurface() {
-  const registered = REAL.map((command) => command.name).sort();
-  const contracted = publicCommandNames().sort();
-  if (registered.join("\n") !== contracted.join("\n")) {
-    throw new Error(
-      `public command contract drift: registered=[${registered.join(", ")}], contracted=[${contracted.join(", ")}]`
-    );
+};
+const targetDevice = (command, adapter, options) => applyDeviceTargeting(command, adapter, options, { gate: true, rerun: "" });
+const runOptions = {
+  engine: metaMaskEngine,
+  targetDevice,
+  plan: {
+    // The wallet fixture `fixtures set` seeds.
+    steps: (target) => [{
+      step: "fixture.file",
+      confidence: "static",
+      status: "ok",
+      detail: fs.existsSync(walletFixturePath(target)) ? `present: ${walletFixturePath(target)}` : `absent: ${walletFixturePath(target)} (fixtures set to seed)`
+    }],
+    launchDetail: "would launch/attach the app + heal transport (Metro/Chrome/CDP) before executing"
   }
-  for (const command of REAL) {
-    const registeredAliases = [...command.aliases ?? []].sort();
-    const contractedAliases = [...PUBLIC_COMMAND_CONTRACTS[command.name]?.aliases ?? []].sort();
-    if (registeredAliases.join("\n") !== contractedAliases.join("\n")) {
-      throw new Error(
-        `public command alias contract drift for ${command.name}: registered=[${registeredAliases.join(", ")}], contracted=[${contractedAliases.join(", ")}]`
-      );
+};
+const callOptions = {
+  engine: metaMaskEngine,
+  targetDevice,
+  // A wallet action makes the most useful first example.
+  exampleAction: (names) => names.find((name) => /wallet|unlock/u.test(name))
+};
+function overlay(command) {
+  return async (args) => {
+    if (command === "verify" && process.env.MM_HARNESS_SKIP_OVERLAY_ENSURE !== "1") {
+      try {
+        const { options } = parseArgs(args);
+        const target = targetPath(options);
+        const adapterRaw = (typeof options["adapter"] === "string" ? options["adapter"] : void 0) ?? (typeof options["platform"] === "string" ? options["platform"] : void 0) ?? detectAdapter(target);
+        if (adapterRaw && adapterRegistry.has(adapterRaw)) {
+          await handleHarness(["install", "--platform", adapterRaw, "--target", target, "--quiet"]);
+        }
+      } catch {
+      }
     }
-  }
+    const code = await handleHarness([command, ...args], overlayCommandOptions);
+    if (code === 0 && command === "install") {
+      try {
+        invalidateCompletionCache(targetPath(parseArgs(args).options));
+      } catch {
+      }
+    }
+    return code;
+  };
 }
-assertPublicContractMatchesSurface();
+function withManifestEnvelope(command, run) {
+  return async (args) => {
+    try {
+      return await run(args);
+    } catch (error) {
+      const own = args.includes("--") ? args.slice(0, args.indexOf("--")) : args;
+      if (!(error instanceof ActionManifestError) || !own.includes("--json")) throw error;
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        command,
+        status: "fail",
+        exitCode: 1,
+        error: { code: error.code, message: error.message, userAction: error.userAction }
+      }, null, 2));
+      return 1;
+    }
+  };
+}
+const PUBLIC_RUN = {
+  help: { run: (args) => handleHelp(args, { packageRoot, harnessVersion: hostVersion() }), nudge: false },
+  review: { run: handleReview },
+  domain: { run: handleDomain },
+  "pr-body": { run: handlePrBody },
+  config: { run: handleConfig },
+  tutorial: { run: (args) => handleTutorial(args, { harnessVersion: hostVersion() }), exit: "now", nudge: false },
+  "setup-base": { run: handleSetupBase, raw: true, exit: "now", nudge: false },
+  status: { run: (args) => handleStatus(parseArgs(args)) },
+  checklist: { run: handleChecklist },
+  prepare: { run: handlePrepare },
+  task: { run: handleTaskInit },
+  "execution-template": { run: handleExecutionTemplate },
+  actions: { run: (args) => handleActions(parseArgs(args), { catalog: metaMaskEngine }) },
+  stop: { run: (args) => handleStop(args, stopOptions) },
+  call: { run: (args) => handleCall(args, callOptions) },
+  run: { run: (args) => handleRun(args, runOptions) },
+  last: { run: (args) => handleLast(parseArgs(args)) },
+  doctor: { run: (args) => handleDoctor(parseArgs(args)) },
+  check: { run: handleCheck },
+  "recipe-quality": { run: handleRecipeQuality },
+  provision: { run: (args) => handleProvision(parseArgs(args)) },
+  install: { run: overlay("install") },
+  verify: { run: overlay("verify") },
+  cleanup: { run: overlay("cleanup") },
+  launch: { run: handleLaunch },
+  "runtime-launch": { run: (args) => handleRuntimeLaunch(parseArgs(args)) },
+  logs: { run: handleLogs },
+  debug: { run: handleDebug },
+  reload: { run: handleReload },
+  update: { run: handleUpdate, exit: "now", nudge: false },
+  pin: { run: handlePin, exit: "now", nudge: false },
+  fixtures: { run: handleFixtures }
+};
+const HIDDEN_RUN = {
+  "completion-candidates": { run: handleCompletionCandidates, nudge: false },
+  "runtime-health": { run: (args) => handleRuntimeHealth(parseArgs(args)) },
+  "runtime-decision": { run: (args) => handleRuntimeDecision(parseArgs(args, { recordIsFlag: true })) },
+  "resolve-extension": { run: (args) => handleResolveExtension(parseArgs(args)) },
+  "ensure-ready": { run: (args) => handleEnsureReady(parseArgs(args)) },
+  "self-test": { run: (args) => handleSelfTest(parseArgs(args)) },
+  // Installs/prints the bundled zsh + bash tab completion: shell tooling, no engine.
+  completions: {
+    run: (args) => spawnSync("bash", [path.join(packageRoot, "scripts", "install-completions.sh"), ...args], { stdio: "inherit" }).status ?? 1,
+    nudge: false
+  }
+};
 const HELP_GROUPS = [
   {
     title: "DAILY LOOP",
@@ -1005,249 +208,64 @@ const HELP_GROUPS = [
     commands: ["setup-base", "update", "pin"]
   }
 ];
-function commandMeta(name) {
-  const real = REAL.find((command) => command.name === name);
-  if (real) return { summary: real.summary, example: real.example, planned: false };
-  return { summary: "", example: "", planned: false };
-}
-function adapterFromRuntimeContext(ctx) {
-  const raw = typeof ctx.platform === "string" ? ctx.platform : void 0;
-  if (!raw) return void 0;
-  if (raw === "mobile" || raw === "ios" || raw === "android") return "mobile";
-  if (raw === "extension" || raw === "chrome-extension") return "extension";
-  if (raw === "core") return "core";
-  if (raw === "terminal") return "terminal";
+function slotAdapter(platform) {
+  if (platform === "mobile" || platform === "ios" || platform === "android") return "mobile";
+  if (platform === "extension" || platform === "chrome-extension") return "extension";
+  if (platform === "core") return "core";
+  if (platform === "terminal") return "terminal";
   return void 0;
 }
-function detectedSlotLine(out) {
-  const ctxPath = path.join(
-    process.cwd(),
-    process.env.RECIPE_RUNTIME_DIR || "temp/recipe/runtime",
-    "agentic-runtime.json"
-  );
-  try {
-    const ctx = JSON.parse(fs.readFileSync(ctxPath, "utf8"));
-    const adapter = adapterFromRuntimeContext(ctx) ?? detectAdapter(process.cwd());
-    const parts = [];
-    if (ctx.slotId) parts.push(`slot ${out("ok", String(ctx.slotId))}`);
-    if (ctx.simulator) parts.push(`device ${out("ok", String(ctx.simulator))}`);
-    const devServerPort = ctx.watcherPort ?? ctx.devServerPort ?? ctx.metroPort;
-    const surface = adapter ? getAdapterSurface(adapter) : void 0;
-    if (surface && !surface.headless && devServerPort) {
-      parts.push(`${surface.devServer.label} :${out("ok", String(devServerPort))}`);
-    }
-    if (ctx.gitBranch) parts.push(`branch ${out("info", String(ctx.gitBranch))}`);
-    if (parts.length === 0) return null;
-    return `${out("label", "SLOT")} \u2014 this checkout is a prepared slot: ${parts.join(" \xB7 ")}`;
-  } catch {
-    return null;
-  }
-}
-function groupedHelp() {
-  const out = (style, text) => color(style, text, { stream: process.stdout });
-  const lines = [];
-  lines.push(`${out("bold", "mm-harness")} \u2014 one front door for the MetaMask recipe loop: launch the app, prove behavior, manage the runtime overlay.`);
-  lines.push("Run it from inside a MetaMask checkout; the platform (mobile | extension | core | terminal) is auto-detected.");
-  lines.push(`Grammar: ${out("cmd", "mm-harness <command> [target] [flags]")}   (target is a positional: ios | android; flags add agent depth; --json is the agent contract)`);
-  if (process.env.MM_HARNESS_BIN) {
-    lines.push("");
-    lines.push(`${out("warn", "DEV OVERRIDE ACTIVE")} \u2014 this run is served by MM_HARNESS_BIN=${out("path", process.env.MM_HARNESS_BIN)} (unset it to return to the installed/global bin).`);
-  }
-  if (process.env.MM_HARNESS_BIN && process.env.MM_HARNESS_RUN_MODE) {
-    lines.push(`${out("label", "running from:")} ${out("path", process.env.MM_HARNESS_RUN_MODE)} (source checkout; dist shadows src when both exist)`);
-  }
-  const slotLine = detectedSlotLine(out);
-  if (slotLine) {
-    lines.push("");
-    lines.push(slotLine);
-  }
-  for (const group of HELP_GROUPS) {
-    lines.push("");
-    lines.push(`${out("label", group.title)} \u2014 ${group.blurb}:`);
-    for (const name of group.commands) {
-      const meta = commandMeta(name);
-      const planned = meta.planned ? "   (planned)" : "";
-      lines.push(`  ${out("cmd", name.padEnd(10))} ${meta.summary}${planned}`);
-      lines.push(`               ${out("comment", meta.example)}`);
-    }
-  }
-  lines.push("");
-  lines.push("ONE bin: mm-harness is the only command. Platform is auto-detected; the positional target forces it");
-  lines.push("(mm-harness launch ios); platform-specific needs are FLAGS on the same command. Human happy path = the bare");
-  lines.push("command; agents add depth via flags (--json, --target, ports).");
-  lines.push("");
-  lines.push("SETUP \u2014 tab-completion (zsh + bash), sourced from the bundled scripts:");
-  lines.push("  mm-harness completions install   # print the lines to add to ~/.zshrc / ~/.bashrc");
-  lines.push("");
-  lines.push("DEV/PROD \u2014 the global npm install is prod; set MM_HARNESS_BIN to a dev checkout to override:");
-  lines.push("  MM_HARNESS_BIN=/path/to/checkout/bin/mm-harness   # unset = the installed/global bin");
-  lines.push("");
-  lines.push("See README.md for the workflow and docs/RECIPES.md for proof authoring.");
-  return `${lines.join("\n")}
-`;
-}
-async function delegate(argv) {
-  try {
-    return await recipeMain(argv);
-  } catch (error) {
-    const own = argv.includes("--") ? argv.slice(0, argv.indexOf("--")) : argv;
-    if (error instanceof ActionManifestError && own.includes("--json")) {
-      console.log(JSON.stringify({
-        schemaVersion: 1,
-        command: argv[0],
-        status: "fail",
-        exitCode: 1,
-        error: { code: error.code, message: error.message, userAction: error.userAction }
-      }, null, 2));
-      return 1;
-    }
-    console.error(error instanceof Error ? error.message : String(error));
-    return error !== null && typeof error === "object" && "exitCode" in error && typeof error.exitCode === "number" ? error.exitCode : 1;
-  }
-}
-const pkgVersion = (() => {
-  try {
-    return JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version ?? "unknown";
-  } catch {
-    return "unknown";
-  }
-})();
-const program = new Command();
-program.name("mm-harness").description("the MetaMask recipe harness: launch the app, prove behavior, manage the runtime overlay").version(pkgVersion, "-v, --version", "Print the mm-harness version").addHelpCommand(false).helpOption("-h, --help", "Show grouped help").showHelpAfterError("(run `mm-harness --help` for the full surface)").configureHelp({ formatHelp: () => groupedHelp() });
-for (const command of REAL) {
-  const registered = program.command(command.name).description(command.summary).allowUnknownOption().helpOption("-h, --help", "Show command help");
-  if (command.aliases?.length) registered.aliases(command.aliases);
-  registered.configureHelp({ formatHelp: () => `${command.helpText}
-` }).argument("[args...]").action(async () => {
-    if (command.name === "update") {
-      process.exit(await handleUpdate(rawArgv.slice(1)));
-    }
-    if (command.name === "pin") {
-      process.exit(handlePin(rawArgv.slice(1)));
-    }
-    if (command.name === "help") {
-      process.exitCode = handleHelp(rawArgv.slice(1), { packageRoot, harnessVersion: pkgVersion });
-      return;
-    }
-    if (command.name === "tutorial") {
-      process.exit(handleTutorial(rawArgv.slice(1), { harnessVersion: pkgVersion }));
-    }
-    process.exitCode = await withCommandJournal(command.name, rawArgv, () => delegate(rawArgv));
-  });
-}
-const HIDDEN = [
-  "completion-candidates",
-  "runtime-health",
-  "runtime-decision",
-  "resolve-extension",
-  "ensure-ready",
-  "self-test"
-];
-for (const name of HIDDEN) {
-  program.command(name, { hidden: true }).allowUnknownOption().helpOption(false).argument("[args...]").action(async () => {
-    process.exit(await delegate(rawArgv));
-  });
-}
-program.command("completions").description("Install/print bundled shell tab-completion (zsh + bash)").allowUnknownOption().helpOption(false).argument("[args...]").action(() => {
-  const script = path.join(packageRoot, "scripts", "install-completions.sh");
-  const result = spawnSync("bash", [script, ...rawArgv.slice(1)], { stdio: "inherit" });
-  process.exit(result.status ?? 1);
-});
-const NUDGE_SKIP = ["help", "tutorial", "setup-base", "update", "pin", "completions", "completion-candidates"];
-if (rawArgv.length > 0 && !NUDGE_SKIP.includes(rawArgv[0])) {
-  maybeNudge();
-}
-function targetFromArgv(argv) {
-  const index = argv.indexOf("--target");
-  const separate = index !== -1 ? argv[index + 1] : void 0;
-  const inline = argv.find((argument) => argument.startsWith("--target="))?.slice("--target=".length);
-  return path.resolve(separate ?? inline ?? process.cwd());
-}
-function hasPassthroughHelp(argv) {
-  const divider = argv.indexOf("--");
-  if (divider === -1) return false;
-  return argv.slice(divider + 1).some((arg) => arg === "-h" || arg === "--help");
-}
-function isCallActionHelp(argv) {
-  if (argv[0] !== "call") return false;
-  if (!argv[1] || argv[1].startsWith("-")) return false;
-  const divider = argv.indexOf("--");
-  const scope = divider === -1 ? argv : argv.slice(0, divider);
-  return scope.includes("--help") || scope.includes("-h");
-}
-function jsonRequestedBeforePassthrough(argv) {
-  const divider = argv.indexOf("--");
-  const scope = divider === -1 ? argv : argv.slice(0, divider);
-  return scope.some((argument) => argument === "--json" || argument.startsWith("--json="));
-}
-function jsonStreamRequestedBeforePassthrough(argv) {
-  const divider = argv.indexOf("--");
-  const scope = divider === -1 ? argv : argv.slice(0, divider);
-  return scope.includes("--json-stream");
-}
-function emitUsageError(error, json, jsonStream) {
-  if (jsonStream) {
-    const stream = new JsonStreamWriter(error.command, true);
-    stream.error({ code: error.code, message: error.message, userAction: error.userAction });
-    stream.complete("fail", 2);
-  } else if (json) {
-    process.stdout.write(
-      `${JSON.stringify(
-        {
-          schemaVersion: 1,
-          command: error.command,
-          status: "fail",
-          error: {
-            code: error.code,
-            message: error.message,
-            userAction: error.userAction
-          },
-          exitCode: 2
-        },
-        null,
-        2
-      )}
-`
-    );
-  } else {
-    const scope = error.command === "mm-harness" ? "" : ` ${error.command}`;
-    process.stderr.write(`\u2717 mm-harness${scope}: ${error.message}
-  Next: ${error.userAction}
-`);
-  }
-  process.exit(2);
-}
-if (rawArgv.length === 0) {
-  process.stdout.write(groupedHelp());
-  process.exit(0);
-}
-if (rawArgv[0] === "setup-base") {
-  process.exit(handleSetupBase(rawArgv.slice(1)));
-}
-const preflightBypass = /* @__PURE__ */ new Set([
-  ...HIDDEN,
-  "completions"
-]);
-if (!preflightBypass.has(rawArgv[0] ?? "")) {
-  const usageError = validatePublicInvocation(rawArgv, PUBLIC_COMMAND_EXAMPLES);
-  if (usageError) {
-    emitUsageError(
-      usageError,
-      jsonRequestedBeforePassthrough(rawArgv),
-      jsonStreamRequestedBeforePassthrough(rawArgv)
-    );
-  }
-}
-await hydrateLibraryPathEnv({ target: targetFromArgv(rawArgv), config: readConfig(configPath()) });
-{
-  const refused = await loadSelectedAdapter(rawArgv[0] ?? "", rawArgv.slice(1));
-  if (refused !== void 0) process.exit(refused);
-}
-if (hasPassthroughHelp(rawArgv)) {
-  process.exit(await delegate(rawArgv));
-}
-if (isCallActionHelp(rawArgv)) {
-  const callHelp = REAL.find((command) => command.name === "call")?.helpText ?? "";
-  process.exit(await handleCallHelp(rawArgv.slice(1), callHelp, { catalog: metaMaskEngine }));
-}
-await program.parseAsync(process.argv);
+await createHarnessCli({
+  host: harnessHost(),
+  adapters: adapterRegistry,
+  // Every location this machine resolves a library from reaches recipe, action
+  // and template discovery, which only reads RECIPE_LIBRARY_PATH, so no command
+  // sees a narrower set than `mm-harness domain` reports.
+  libraries: { hydrate: (target) => hydrateLibraryPathEnv({ target, config: readConfig(configPath()) }) },
+  adopt: adoptPluginAdapter,
+  // A library plugin's venue policy is fenced once it loads, before any help or dispatch.
+  afterAdapterLoad,
+  // `mm-harness config set libraries.<name>` libraries, read before hydration.
+  configuredLibraries: configuredLibrarySources,
+  commands: [
+    ...PUBLIC_COMMANDS.map((command) => ({
+      ...command,
+      ...PUBLIC_RUN[command.name],
+      run: withManifestEnvelope(command.name, PUBLIC_RUN[command.name].run)
+    })),
+    ...HIDDEN_COMMANDS.map((name) => ({
+      name,
+      hidden: true,
+      ...HIDDEN_RUN[name],
+      run: withManifestEnvelope(name, HIDDEN_RUN[name].run)
+    }))
+  ],
+  help: {
+    description: "the MetaMask recipe harness: launch the app, prove behavior, manage the runtime overlay",
+    intro: (out) => [
+      `${out("bold", "mm-harness")} \u2014 one front door for the MetaMask recipe loop: launch the app, prove behavior, manage the runtime overlay.`,
+      "Run it from inside a MetaMask checkout; the platform (mobile | extension | core | terminal) is auto-detected.",
+      `Grammar: ${out("cmd", "mm-harness <command> [target] [flags]")}   (target is a positional: ios | android; flags add agent depth; --json is the agent contract)`
+    ],
+    groups: HELP_GROUPS,
+    footer: () => [
+      "ONE bin: mm-harness is the only command. Platform is auto-detected; the positional target forces it",
+      "(mm-harness launch ios); platform-specific needs are FLAGS on the same command. Human happy path = the bare",
+      "command; agents add depth via flags (--json, --target, ports).",
+      "",
+      "SETUP \u2014 tab-completion (zsh + bash), sourced from the bundled scripts:",
+      "  mm-harness completions install   # print the lines to add to ~/.zshrc / ~/.bashrc",
+      "",
+      "DEV/PROD \u2014 the global npm install is prod; set MM_HARNESS_BIN to a dev checkout to override:",
+      "  MM_HARNESS_BIN=/path/to/checkout/bin/mm-harness   # unset = the installed/global bin",
+      "",
+      "See README.md for the workflow and docs/RECIPES.md for proof authoring."
+    ],
+    slotAdapter
+  },
+  // Passive update nudge: one cached stderr line if a newer version is published.
+  beforeDispatch: () => maybeNudge(),
+  catalog: metaMaskEngine,
+  replacedOptions: REPLACED_OPTIONS,
+  explainInvalidChoice: explainMissingAdapterLibrary
+}).run();