@deeeed/metamask-harness 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.3.2 - 2026-07-04
+
+### Fixed
+- **IMP-21: FORCE_COLOR-safe pod install** — the mobile pod-triggering leaves (`yarn-setup.sh` running `yarn setup`, and `open-device.sh` running the native `yarn start:ios|android` build) now run with `FORCE_COLOR=0` / `NO_COLOR=1`. VisionCamera's podspec probes `node --print require.resolve('react-native-worklets-core')` and treats any output other than the exact string `undefined` as "found"; an inherited `FORCE_COLOR` made node emit a colorized `undefined`, enabling FrameProcessors and hard-failing on the missing worklets pod. Setup/native builds are now reliable from a `FORCE_COLOR` shell.
+- **IMP-22: `--watcher-port` beats `.js.env WATCHER_PORT`** — `verify.sh` port resolution now honors an explicit `WATCHER_PORT` in the process env (which carries `mm-harness launch --watcher-port N`) over the target's `.js.env`. Precedence is flag > process env > `.js.env` > `8081` default, so a run can be pointed at an alternate Metro/CDP port without editing a shared slot's `.js.env`.
+
+## 0.3.1 - 2026-07-03
+
+### Fixed
+- **Customization compose-by-ref**: recipes with `{action:"call",ref:"<lib>.<flow>"}` + `--library <lib>=<dir>` now pass pre-run schema validation AND execute at runtime. `validateRecipeAdapterAware` threads `externalFlowIds` into both `validateRecipeDocument` and `validateRecipeWithManifest`; library resolution also runs at `run` time.
+- **IMP-14: stale metro.log guard** — if `metro.log` is older than the install markers (`node_modules/.yarn-state.yml`, `.yarn/install-state.gz`), it is treated as absent so a stale log cannot drive a false native-module-mismatch decision at launch.
+- **IMP-15: stale overlay shim auto-repair (two modes)** — `ensureOverlay` detects (1) a `.runner-source` pointing to a nonexistent runner dir, and (2) a `.runner-source` whose dir exists but whose `bin/mm-harness` was removed. Both re-install automatically before launch.
+- **IMP-17: deps-staleness fallback (two-layer)** — (1) mtime comparison when no baseline exists: manifest files newer than install markers → `install`; (2) required-dep absence: a top-level `package.json` dep absent from `node_modules` is caught at pre-flight as `deps-partial` → `install`, before Metro discovers it during a long bundle run.
+- **IMP-18: iOS sim scheme-approval pre-write** — `open-device.sh` writes `com.apple.launchservices.schemeapproval` via `xcrun simctl spawn … defaults write` before the first `openurl`, eliminating the "Open in \<App\>?" dialog hang. Scheme derives from `DEV_CLIENT_SCHEME` (overridable via `IOS_DEV_CLIENT_SCHEME`).
+
 ## 0.3.0 - 2026-07-03
 
 ### Changed
@@ -13,8 +28,15 @@
 
 ## Unreleased
 
+### Added
+
+- **`mm-harness update`**: checks the npm registry `dist-tags.latest` for `@deeeed/metamask-harness` and, when newer, runs `npm i -g @deeeed/metamask-harness@latest` and prints `old → new`; already-current exits 0. `--check` reports only (exit 0 up-to-date, exit 1 update available); `--json` carries `{ current, latest, updateAvailable }`. Every failure path (no npm, registry unreachable, permission-denied global dir) exits 3 with the exact escape.
+- **Passive update nudge**: on invocation (throttled to once/day via a cache file, bounded fetch, skipped in CI and when `MM_HARNESS_NO_UPDATE_CHECK=1`), a single `stderr` line announces a newer published version — never on stdout, never blocking, never auto-updating.
+- **`MM_HARNESS_BIN` dev/prod switch**: the entrypoint honors `MM_HARNESS_BIN` as the single override point — when set, the invocation is handed to that dev checkout's `bin/mm-harness`; unset resolves the installed/global bin (prod). A self-path guard prevents an exec loop, and a non-executable value teaches its fix. Documented in `--help` and README.
+
 ### Changed
 
+- **Teaching errors are type-enforced**: `usageOut` now requires a `userAction` escape argument, so a teaching error without a reachable next step no longer compiles. The repo-type detection failure teaches BOTH escapes (`cd into a checkout / pass --target <path>` and `--adapter <mobile|extension|core>`) consistently across `doctor`, `launch`, `verify`, and the overlay path.
 - **Repository reorganized into `src/`, `adapters/`, `library/` domains**: all TypeScript now lives under `src/` (shared CLI/core plus typed per-adapter logic in `src/adapters/<adapter>/`); everything that executes against or is injected into the app runtime lives under `adapters/` (`adapters/<adapter>/` per-app glue, `adapters/shared/` cross-adapter OS-glue, `adapters/porcelain/` composed entrypoints, `adapters/*/overlay/` the only injected payload); `library/` holds composable vocabulary only. The `runner/` and `orchestration/` trees no longer exist. The surface doctor moved to `scripts/adapter-surface-doctor.mjs` with its index at `adapters/manifest.json`. Placement rules (R1–R11) are documented in `AGENTS.md`. This is a path-only reorganization; runtime behavior is unchanged.
 
 ## 0.2.0 - 2026-07-03

package/README.md

@@ -84,8 +84,17 @@ mm-harness launch ios                           # launch (mobile: ios | android)
 mm-harness logs                                 # tail Metro/webpack + app logs
 mm-harness debug                                # open the debug console
 mm-harness fixtures sync                        # sync fixtures; `fixtures set` seeds the wallet
+
+# Keep the install current
+mm-harness update                               # upgrade to the published latest (prints old → new)
+mm-harness update --check --json                # report only — { current, latest, updateAvailable }
 ```
 
+A passive once-a-day nudge prints one `stderr` line when a newer version is
+published (`mm-harness <cur> → <latest> available · run: mm-harness update`). It
+never blocks and never auto-updates. Silence it with `MM_HARNESS_NO_UPDATE_CHECK=1`
+(auto-off in CI).
+
 Set `RECIPE_LOG_UI=compact|full|quiet` (default `compact`) and `RECIPE_LOG_EVENTS=10`
 to tune the compact log view during launch and Metro/webpack startup.
 
@@ -123,6 +132,24 @@ and shell launch in `adapters/porcelain/mm-recipe` / `adapters/porcelain/mme-rec
 primitives into `adapters/shared/`. CI installs harness from npm — publish
 `@farmslot/recipe-harness` before bumping the dependency here.
 
+## Dev/prod harness (`MM_HARNESS_BIN`)
+
+The global npm install owns the `mm-harness` on `PATH` — that is the **prod**
+harness. To run a **dev** checkout with active pre-release changes alongside it,
+set `MM_HARNESS_BIN` to that checkout's `bin/mm-harness`:
+
+```bash
+export MM_HARNESS_BIN=/path/to/checkout/bin/mm-harness   # dev: this checkout owns the run
+unset MM_HARNESS_BIN                                       # prod: the installed/global bin
+```
+
+`MM_HARNESS_BIN` is the single override point: when set, the entrypoint hands the
+whole invocation to that path before doing any dependency work; when unset it
+resolves the installed bin. A dev checkout is never installed globally, so there is
+no `PATH` collision — dev is reached only through `MM_HARNESS_BIN` (or a shell
+alias). A per-farm environment can export it so the dev farm dispatches through the
+dev harness while the prod farm leaves it unset.
+
 ## Runtime notes
 
 - `tmux` is recommended for long-lived Metro/webpack processes; standalone use

package/adapters/mobile/open-device.sh

@@ -176,6 +176,8 @@ ANDROID_PKGS=("${ANDROID_PACKAGE_ID:-io.metamask}" "io.metamask.flask" "io.metam
 
 if [ "$PLATFORM" = "ios" ]; then
   SIM_TARGET="$SIMULATOR"
+  # Expo dev-client URL scheme — drives both the deep link and the scheme-approval key.
+  DEV_CLIENT_SCHEME="${IOS_DEV_CLIENT_SCHEME:-expo-metamask}"
 
   boot_simulator_if_needed "$SIM_TARGET"
   show_simulator "$SIM_TARGET"
@@ -188,10 +190,18 @@ if [ "$PLATFORM" = "ios" ]; then
     xcrun simctl spawn "$SIM_TARGET" defaults write "$BUNDLE_ID" \
       EXDevMenuIsOnboardingFinished -bool YES 2>/dev/null || true
 
+    # Pre-approve the dev-client deep-link scheme so openurl never pauses on the
+    # "Open in <App>?" dialog. The key encodes the CoreSimulator bridge + scheme;
+    # the value is the bundle ID of the approved handler.
+    xcrun simctl spawn "$SIM_TARGET" defaults write \
+      com.apple.launchservices.schemeapproval \
+      "com.apple.CoreSimulator.CoreSimulatorBridge-->${DEV_CLIENT_SCHEME}" \
+      -string "$BUNDLE_ID" 2>/dev/null || true
+
     # Open via expo-development-client deep link so the app connects to our Metro.
     ENCODED_URL="$(urlencode "http://localhost:${PORT}?disableOnboarding=1" 2>/dev/null \
       || printf 'http%%3A%%2F%%2Flocalhost%%3A%s%%3FdisableOnboarding%%3D1' "$PORT")"
-    DEEP_LINK="expo-metamask://expo-development-client/?url=${ENCODED_URL}"
+    DEEP_LINK="${DEV_CLIENT_SCHEME}://expo-development-client/?url=${ENCODED_URL}"
 
     printf 'Launching iOS dev client %s on %s\n' "$BUNDLE_ID" "$SIM_TARGET" >&2
     if xcrun simctl openurl "$SIM_TARGET" "$DEEP_LINK" 2>/dev/null; then

package/adapters/mobile/verify.sh

@@ -174,14 +174,21 @@ watcher_port() {
 const fs = require('fs');
 const path = require('path');
 const target = process.env.TARGET_FOR_WATCHER_PORT;
-let port = process.env.WATCHER_PORT || '8081';
-for (const file of ['.js.env', '.env', '.env.local']) {
-  const full = path.join(target, file);
-  if (!fs.existsSync(full)) continue;
-  const text = fs.readFileSync(full, 'utf8');
-  const match = text.match(/^\s*(?:export\s+)?WATCHER_PORT=(["']?)([0-9]+)\1/m);
-  if (match) { port = match[2]; break; }
+// Precedence: an explicit WATCHER_PORT in the process env (which carries the
+// --watcher-port flag applied by launch) wins over the slot's .js.env, which wins
+// over the 8081 default. This lets a run be pointed at an alternate Metro without
+// editing a shared slot .js.env.
+let port = process.env.WATCHER_PORT || '';
+if (!port) {
+  for (const file of ['.js.env', '.env', '.env.local']) {
+    const full = path.join(target, file);
+    if (!fs.existsSync(full)) continue;
+    const text = fs.readFileSync(full, 'utf8');
+    const match = text.match(/^\s*(?:export\s+)?WATCHER_PORT=(["']?)([0-9]+)\1/m);
+    if (match) { port = match[2]; break; }
+  }
 }
+if (!port) port = '8081';
 console.log(port);
 NODE
 }

package/bin/mm-harness

@@ -18,6 +18,38 @@ done
 SCRIPT_DIR="$(cd "$(dirname "$SOURCE")" && pwd -P)"
 RUNNER_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
+# Dev/prod switch (the single override point). MM_HARNESS_BIN, when set, is the
+# authoritative path to a dev checkout's bin/mm-harness with active pre-release
+# changes; unset resolves the installed/global mm-harness (prod). Handing the
+# invocation over here, before any dependency work, lets the dev checkout fully
+# own the run. The self-path guard prevents an exec loop when MM_HARNESS_BIN
+# already points at this script — including via a symlink (both sides are resolved
+# to their real paths before comparing).
+if [ -n "${MM_HARNESS_BIN:-}" ]; then
+  self_real="$SCRIPT_DIR/$(basename "$SOURCE")"
+  # Resolve MM_HARNESS_BIN through any symlink chain so a symlink-to-self is caught.
+  mm_bin_src="$MM_HARNESS_BIN"
+  while [ -L "$mm_bin_src" ]; do
+    mm_bin_dir="$(cd "$(dirname "$mm_bin_src")" && pwd -P)"
+    mm_bin_target="$(readlink "$mm_bin_src")"
+    if [[ "$mm_bin_target" == /* ]]; then
+      mm_bin_src="$mm_bin_target"
+    else
+      mm_bin_src="$mm_bin_dir/$mm_bin_target"
+    fi
+  done
+  bin_real_dir="$(cd "$(dirname "$mm_bin_src")" 2>/dev/null && pwd -P || true)"
+  bin_real="${bin_real_dir:+$bin_real_dir/$(basename "$mm_bin_src")}"
+  if [ "$bin_real" != "$self_real" ]; then
+    if [ ! -x "$MM_HARNESS_BIN" ]; then
+      echo "mm-harness: MM_HARNESS_BIN is not an executable: $MM_HARNESS_BIN" >&2
+      echo "  Next: point MM_HARNESS_BIN at a checkout's bin/mm-harness, or unset it to use the global install" >&2
+      exit 1
+    fi
+    exec "$MM_HARNESS_BIN" "$@"
+  fi
+fi
+
 ENSURE_DEPS="$RUNNER_DIR/adapters/shared/ensure-runner-deps.sh"
 if [ -f "$ENSURE_DEPS" ]; then
   # shellcheck disable=SC1090

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"

package/src/adapters/mobile/prepare.ts

@@ -18,6 +18,14 @@ import {
 
 export { type MobileRuntimeDecisionReport };
 
+// Pod install (run by `yarn setup` and by the native `yarn start:ios|android`
+// build) shells `node --print require.resolve('react-native-worklets-core')` and
+// treats any output other than the exact string `undefined` as "module found".
+// An inherited FORCE_COLOR makes node emit a colorized `undefined`, so VisionCamera
+// misdetects the worklets pod, enables FrameProcessors, and fails on the missing
+// pod. Force plain output for pod-triggering spawns so the probe reads `undefined`.
+const POD_PROBE_ENV: Record<string, string> = { FORCE_COLOR: '0', NO_COLOR: '1' };
+
 export interface PrepareMobileOptions extends MobileRuntimeDecisionOptions {
   /** Pass through to leaf-script spawnScript calls so output is suppressed in --json mode. */
   json?: boolean;
@@ -159,9 +167,9 @@ function dispatchAction(
   const cwd = action.cwd ?? target;
   switch (action.id) {
     case 'yarn-setup': {
-      // Leaf: install node_modules (deps missing or stale).
+      // Leaf: install node_modules (deps missing or stale); `yarn setup` runs pods.
       const leaf = path.join(runnerDir, 'adapters/mobile/yarn-setup.sh');
-      return spawnScript(leaf, ['--target', cwd], target, json);
+      return spawnScript(leaf, ['--target', cwd], target, json, POD_PROBE_ENV);
     }
     case 'start-metro': {
       // Leaf: ensure Metro is running; argv may carry --clear for cache reset.
@@ -185,13 +193,16 @@ function dispatchAction(
       return spawnScript(leaf, ['--target', cwd, '--clear'], target, json);
     }
     case 'launch-mobile-runtime': {
-      // Leaf: open the MetaMask Mobile dev client on the simulator/device.
+      // Leaf: open the MetaMask Mobile dev client on the simulator/device. In
+      // auto/rebuild modes this runs the native build (`yarn start:*`), which
+      // triggers pod install — pass the pod-probe env so it stays FORCE_COLOR-safe.
       const leaf = path.join(runnerDir, 'adapters/mobile/open-device.sh');
       return spawnScript(
         leaf,
         ['--platform', platform, '--target', cwd, '--preflight-mode', preflightMode],
         target,
         json,
+        POD_PROBE_ENV,
       );
     }
     case 'rebuild-native-dev-client': {

package/src/adapters/mobile/runtime-decision.ts

@@ -68,9 +68,31 @@ function resolveMetroLog(target: string, metroLog?: string): string | null {
   return fs.existsSync(abs) ? abs : null;
 }
 
+// A metro.log is stale when the yarn install markers are newer — a yarn install
+// happened after the last bundle run, so the log describes a now-superseded module
+// tree. Ignoring it lets launch start fresh instead of deciding off stale content.
+function isMetroLogStale(target: string, logAbs: string): boolean {
+  try {
+    const logMtime = fs.statSync(logAbs).mtimeMs;
+    // Check against the same install markers as depsCheck; they are updated by
+    // yarn on every successful install, making them a reliable freshness signal.
+    const INSTALL_MARKERS = ['node_modules/.yarn-state.yml', '.yarn/install-state.gz'];
+    return INSTALL_MARKERS.some((rel) => {
+      try {
+        return logMtime < fs.statSync(path.join(target, rel)).mtimeMs;
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return false;
+  }
+}
+
 function metroLogCheck(target: string, metroLog?: string): MetroLogCheck {
   const abs = resolveMetroLog(target, metroLog);
   if (!abs) return { status: 'no-log' };
+  if (isMetroLogStale(target, abs)) return { status: 'no-log' };
   const logText = fs.readFileSync(abs, 'utf8');
   return analyzeBundleLog({
     target,
@@ -80,6 +102,54 @@ function metroLogCheck(target: string, metroLog?: string): MetroLogCheck {
   });
 }
 
+// Returns names of top-level package.json dependencies absent from node_modules.
+// Catches the case where a dep was added in a branch merge but yarn install was not
+// re-run — install markers and fingerprint may both be satisfied while a required
+// package directory is simply missing (real case: 249s Metro bundle discovers it
+// too late).
+function missingRequiredDeps(target: string): string[] {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(target, 'package.json'), 'utf8')) as {
+      dependencies?: Record<string, unknown>;
+      devDependencies?: Record<string, unknown>;
+    };
+    const all = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    return Object.keys(all).filter(
+      (name) => !fs.existsSync(path.join(target, 'node_modules', name)),
+    );
+  } catch {
+    return [];
+  }
+}
+
+// Returns true when any manifest input (package.json or yarn.lock) is newer than
+// the install markers written by yarn on a successful install. A reliable signal
+// that deps changed since the last install, even when depsCheck found no recorded
+// baseline drift (e.g. git checkout preserved an old author-date mtime on the
+// manifest, then a new dep was committed, making the manifest newer than markers).
+function depsStaleByMtime(target: string): boolean {
+  // Use the same install markers as depsCheck: the files yarn writes on install.
+  const INSTALL_MARKERS = ['node_modules/.yarn-state.yml', '.yarn/install-state.gz'];
+  let markerMtime = 0;
+  for (const rel of INSTALL_MARKERS) {
+    try {
+      const mt = fs.statSync(path.join(target, rel)).mtimeMs;
+      if (mt > markerMtime) markerMtime = mt;
+    } catch {
+      // marker absent; keep searching
+    }
+  }
+  if (markerMtime === 0) return false; // no markers → depsCheck already handles via 'missing'
+  for (const file of ['package.json', 'yarn.lock']) {
+    try {
+      if (fs.statSync(path.join(target, file)).mtimeMs > markerMtime) return true;
+    } catch {
+      // manifest absent; skip
+    }
+  }
+  return false;
+}
+
 const installActions = (target: string): MobileRuntimeDecisionAction[] => [
   { id: 'yarn-setup', argv: ['yarn', 'setup'], cwd: target },
 ];
@@ -108,9 +178,28 @@ export async function decideMobileReadiness(
   const resolved = path.resolve(target);
   if (options.record) recordDepsBaseline(resolved);
 
-  const deps = depsCheck(resolved, {
+  const rawDeps = depsCheck(resolved, {
     productMarkers: mobileProductMarkers(options.platform),
   });
+  // Mtime-based fallback: when depsCheck found no recorded baseline, supplement
+  // with a direct mtime comparison — if package.json or yarn.lock is newer than
+  // node_modules, a dep change landed after the last install. Fail fast at
+  // pre-flight rather than launching a doomed Metro bundle. Skip when a baseline
+  // was found (hasBaseline=true) so fingerprint-verified 'current' is trusted.
+  let deps: DepsCheck =
+    rawDeps.status === 'current' && !rawDeps.hasBaseline && depsStaleByMtime(resolved)
+      ? { installed: rawDeps.installed, status: 'stale', hasBaseline: rawDeps.hasBaseline }
+      : rawDeps;
+  // Required-dep absence: even when fingerprint + mtime reports 'current', a
+  // top-level dependency could be absent from node_modules (e.g. added in a
+  // branch merge but install not re-run). Catch at pre-flight before Metro
+  // discovers it during a 249s bundle run.
+  if (deps.status === 'current') {
+    const absent = missingRequiredDeps(resolved);
+    if (absent.length > 0) {
+      deps = { installed: deps.installed, status: 'partial', hasBaseline: deps.hasBaseline, missingProducts: absent };
+    }
+  }
   const metroLog = metroLogCheck(resolved, options.metroLog);
   const metro = options.watcherPort
     ? await probeMetroPackager(options.watcherPort)
@@ -163,7 +252,10 @@ export async function decideMobileReadiness(
   }
 
   const metroLogAbs = resolveMetroLog(resolved, options.metroLog);
-  const metroLogText = metroLogAbs ? fs.readFileSync(metroLogAbs, 'utf8') : '';
+  const metroLogText =
+    metroLogAbs && !isMetroLogStale(resolved, metroLogAbs)
+      ? fs.readFileSync(metroLogAbs, 'utf8')
+      : '';
   const staleNativeModule = supersededErrorCapture(metroLogText, {
     errorPattern: NATIVE_MODULE_STALE,
     okPattern: BUNDLE_OK,

package/src/cli.ts

@@ -57,7 +57,7 @@ import type {
   RecipeValidationResult,
 } from '@farmslot/protocol';
 import type { MetaMaskRecipeAdapter } from './types.ts';
-import { usageOut } from './commands/shared.ts';
+import { ADAPTER_DETECT_NEXT, usageOut } from './commands/shared.ts';
 
 type CliOptionValue = string | boolean;
 type CliOptions = Record<string, CliOptionValue>;
@@ -455,11 +455,7 @@ async function handleDoctor({ options }: ParsedArgs): Promise<number> {
   const explicitAdapter = optionString(options, 'adapter') ?? optionString(options, 'platform');
   const adapter = explicitAdapter ?? detectAdapter(target);
   if (!adapter) {
-    return usageOut(
-      json,
-      'doctor',
-      `could not detect the MetaMask repo type for ${target}\n  Next: pass --adapter mobile|extension|core`,
-    );
+    return usageOut(json, 'doctor', `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   }
   assertAdapter(adapter);
   const actionManifestPath = actionManifestPathOption(options, adapter);
@@ -853,9 +849,7 @@ function resolveAdapter(options: CliOptions): { adapter: MetaMaskRecipeAdapter;
   const explicit = optionString(options, 'adapter') ?? optionString(options, 'platform');
   const adapter = explicit ?? detectAdapter(target);
   if (!adapter) {
-    throw usageError(
-      `could not detect the MetaMask repo type for ${target}\n  Next: pass --adapter mobile|extension|core`,
-    );
+    throw usageError(`could not detect the MetaMask repo type for ${target}\n  Next: ${ADAPTER_DETECT_NEXT}`);
   }
   try {
     assertAdapter(adapter);
@@ -867,20 +861,24 @@ function resolveAdapter(options: CliOptions): { adapter: MetaMaskRecipeAdapter;
 
 // Adapter-aware recipe validation: schema (validateRecipeDocument) + action
 // existence/platform against the adapter's manifest (validateRecipeWithManifest).
-// This is the "run validates first" contract, shared by `run --plan` and `call`.
-//
-// NOTE (pinned deps): recipes that reference library flows by `call.ref` need
-// `externalFlowIds` sourced from resolveRecipeLibrarySources, which lands with
-// @farmslot/recipe-harness >= 0.3.3 (pending publish). Until then, self-contained
-// recipes (all in-repo recipes + every one-node `call` recipe) validate fully;
-// library-ref recipes would surface their refs here. Extends when 0.3.3 lands.
+// When librarySources are provided (resolved from --library / personal / team
+// tiers), external flow IDs from those sources are declared so `call.ref` nodes
+// targeting library-defined flows pass schema validation.
 async function validateRecipeAdapterAware(
   recipe: unknown,
   manifest: RecipeActionManifestDocument,
+  librarySources?: MetaMaskLibrarySource[],
 ): Promise<RecipeValidationResult> {
   const { validateRecipeDocument, validateRecipeWithManifest } = await importRecipeProtocol();
-  const schema = validateRecipeDocument(recipe);
-  const withManifest = validateRecipeWithManifest(recipe, manifest);
+  let externalFlowIds: ReadonlySet<string> | undefined;
+  if (librarySources && librarySources.length > 0) {
+    const harness = await importRecipeHarness();
+    const resolution = await harness.loadRecipeLibraries(librarySources);
+    externalFlowIds = new Set(resolution.flows.keys());
+  }
+  const validationOptions = externalFlowIds !== undefined ? { externalFlowIds } : undefined;
+  const schema = validateRecipeDocument(recipe, validationOptions);
+  const withManifest = validateRecipeWithManifest(recipe, manifest, validationOptions);
   const findings = [...schema.findings, ...withManifest.findings];
   const errors = findings.filter((finding) => finding.severity === 'error').length;
   const warnings = findings.length - errors;
@@ -905,9 +903,10 @@ function countRecipeNodes(recipe: unknown): number | undefined {
 // Static, adapter-aware recipe validation shared by `run --plan` and the `run`
 // execute path so both "validate first" the same way: read the file (missing /
 // unparseable → usage error, nothing to validate), check the manifest, then run
-// the adapter-aware schema + action-existence validation. Touches nothing and
-// resolves no libraries, so it never emits the engine's "Recipe libraries: …"
-// log — safe to call before the machine-contract JSON is written.
+// the adapter-aware schema + action-existence validation. Loads library flow IDs
+// from --library (so `call.ref` nodes to external flows resolve correctly), but
+// never emits the engine's "Recipe libraries: …" log — safe to call before the
+// machine-contract JSON is written.
 interface RunRecipeStaticValidation {
   recipe: unknown;
   recipeFile: string;
@@ -958,8 +957,10 @@ async function validateRunRecipeStatic(
   }
 
   // validate.schema + validate.actions (static) — adapter-aware recipe validation.
+  // Library sources are resolved here so external `call.ref` flows validate correctly.
+  const librarySources = await resolveMetaMaskLibrarySources(optionString(options, 'library'));
   const validation = manifestOk
-    ? await validateRecipeAdapterAware(recipe, manifest)
+    ? await validateRecipeAdapterAware(recipe, manifest, librarySources)
     : { status: 'invalid' as const, findings: [], summary: { errors: 1, warnings: 0 } };
   findings.push(...validation.findings);
 

package/src/commands/debug.ts

@@ -5,7 +5,7 @@
 import path from 'node:path';
 
 import { runnerDir } from '../paths.ts';
-import { EXIT, flag, parseFlags, resolveAdapter, spawnScript, targetOf, usageOut } from './shared.ts';
+import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, spawnScript, targetOf, usageOut } from './shared.ts';
 
 const DEBUG_BOOLEANS = new Set(['worker', 'devMenu', 'json']);
 
@@ -15,8 +15,8 @@ export async function handleDebug(argv: string[]): Promise<number> {
   const target = targetOf(options);
   const adapter = resolveAdapter(options, target);
 
-  if (!adapter) return usageOut(json, 'debug', `could not detect the MetaMask repo type for ${target}`);
-  if (adapter === 'core') return usageOut(json, 'debug', 'core is headless; there is no debug console.');
+  if (!adapter) return usageOut(json, 'debug', `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
+  if (adapter === 'core') return usageOut(json, 'debug', 'core is headless; there is no debug console.', 'mm-harness verify');
 
   const worker = flag(options, 'worker');
   const devMenu = flag(options, 'devMenu');
@@ -24,14 +24,16 @@ export async function handleDebug(argv: string[]): Promise<number> {
     return usageOut(
       json,
       'debug',
-      '--worker is extension-only (service-worker DevTools). Use --dev-menu on mobile.\n  Next: mm-harness debug --dev-menu',
+      '--worker is extension-only (service-worker DevTools). Use --dev-menu on mobile.',
+      'mm-harness debug --dev-menu',
     );
   }
   if (adapter === 'extension' && devMenu) {
     return usageOut(
       json,
       'debug',
-      '--dev-menu is mobile-only (RN developer menu). Use --worker on the extension.\n  Next: mm-harness debug --worker',
+      '--dev-menu is mobile-only (RN developer menu). Use --worker on the extension.',
+      'mm-harness debug --worker',
     );
   }
 

package/src/commands/fixtures.ts

@@ -7,7 +7,7 @@ import path from 'node:path';
 
 import { runnerDir, walletFixturePath } from '../paths.ts';
 import type { MetaMaskRecipeAdapter } from '../types.ts';
-import { EXIT, flag, parseFlags, resolveAdapter, spawnScript, str, targetOf, usageOut } from './shared.ts';
+import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, spawnScript, str, targetOf, usageOut } from './shared.ts';
 
 // One node injected from cli.ts so `fixtures set` can reuse the real engine path
 // (`call`'s one-node machinery) without a circular import.
@@ -48,18 +48,14 @@ export async function handleFixtures(argv: string[], deps: CommandDeps): Promise
   const json = flag(options, 'json');
   const sub = positional[0];
   if (sub !== 'sync' && sub !== 'set') {
-    return usageOut(json, 'fixtures', 'fixtures requires a subcommand: mm-harness fixtures <sync|set>\n  Next: mm-harness fixtures sync   or   mm-harness fixtures set');
+    return usageOut(json, 'fixtures', 'fixtures requires a subcommand: mm-harness fixtures <sync|set>', 'mm-harness fixtures sync   or   mm-harness fixtures set');
   }
   const target = targetOf(options);
   const adapter = resolveAdapter(options, target);
   if (!adapter) {
-    return usageOut(
-      json,
-      'fixtures',
-      `could not detect the MetaMask repo type for ${target}\n  Next: pass --target <checkout>   or   cd into the checkout, then re-run: mm-harness fixtures ${sub}`,
-    );
+    return usageOut(json, 'fixtures', `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   }
-  if (adapter === 'core') return usageOut(json, 'fixtures', 'core is headless; it has no wallet fixture.\n  Next: mm-harness run <recipe>   # run recipes against the headless core');
+  if (adapter === 'core') return usageOut(json, 'fixtures', 'core is headless; it has no wallet fixture.', 'mm-harness run <recipe>   # run recipes against the headless core');
 
   const canonicalFixture = walletFixturePath(target);
 
@@ -117,7 +113,8 @@ export async function handleFixtures(argv: string[], deps: CommandDeps): Promise
       return usageOut(
         json,
         'fixtures',
-        `no wallet fixture at ${fixturePath}.\n  Next: create it (or pass --fixture <path>), then re-run: mm-harness fixtures set`,
+        `no wallet fixture at ${fixturePath}.`,
+        'create it (or pass --fixture <path>), then re-run: mm-harness fixtures set',
       );
     }
     const previousFixtureEnv = process.env.RECIPE_WALLET_FIXTURE;

package/src/commands/launch.ts

@@ -13,6 +13,7 @@ import { recipeHarnessPath, recipeRuntimeDir, recipeRuntimePath, runnerDir } fro
 import type { MetaMaskRecipeAdapter } from '../types.ts';
 import { prepareMobile } from '../adapters/mobile/prepare.ts';
 import {
+  ADAPTER_DETECT_NEXT,
   EXIT,
   flag,
   parseFlags,
@@ -60,7 +61,7 @@ export async function handleLaunch(argv: string[]): Promise<number> {
   const target = targetOf(options);
 
   const heal = parseHeal(options, 'auto');
-  if (typeof heal !== 'string') return usageOut(json, 'launch', heal.error);
+  if (typeof heal !== 'string') return usageOut(json, 'launch', heal.error, 'use --heal off|infra-only|auto');
 
   // Grammar: mobile requires an ios|android positional (also disambiguates the
   // adapter); extension takes no positional; core is headless (teaching error).
@@ -74,20 +75,17 @@ export async function handleLaunch(argv: string[]): Promise<number> {
   const adapter = resolveAdapter(options, target, adapterHint);
 
   if (!adapter) {
-    return usageOut(
-      json,
-      'launch',
-      `could not detect the MetaMask repo type for ${target}\n  Next: pass --adapter mobile|extension, or run inside a checkout.`,
-    );
+    return usageOut(json, 'launch', `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   }
   if (adapter === 'core') {
-    return usageOut(json, 'launch', 'core is headless; there is nothing to launch. Use: mm-harness verify');
+    return usageOut(json, 'launch', 'core is headless; there is nothing to launch.', 'mm-harness verify');
   }
   if (adapter === 'mobile' && !mobileTarget) {
     return usageOut(
       json,
       'launch',
-      'target is required for mobile.\n  Run: mm-harness launch ios   or   mm-harness launch android',
+      'target is required for mobile.',
+      'mm-harness launch ios   or   mm-harness launch android',
     );
   }
 
@@ -98,7 +96,7 @@ export async function handleLaunch(argv: string[]): Promise<number> {
 
   // --runway is mobile-only.
   if (wantRunway && adapter !== 'mobile') {
-    return usageOut(json, 'launch', 'runway is mobile-only. Drop --runway for the extension.');
+    return usageOut(json, 'launch', 'runway is mobile-only.', 'drop --runway for the extension');
   }
   // --fullscreen is the explicit override when both display flags are passed.
   const displayMode =
@@ -111,7 +109,12 @@ export async function handleLaunch(argv: string[]): Promise<number> {
   for (const portFlag of ['cdpPort', 'watcherPort'] as const) {
     const value = str(options, portFlag);
     if (value !== undefined && !/^\d+$/u.test(value)) {
-      return usageOut(json, 'launch', `--${portFlag === 'cdpPort' ? 'cdp-port' : 'watcher-port'} must be numeric (got: ${value}).`);
+      return usageOut(
+        json,
+        'launch',
+        `--${portFlag === 'cdpPort' ? 'cdp-port' : 'watcher-port'} must be numeric (got: ${value}).`,
+        `pass a numeric port, e.g. --${portFlag === 'cdpPort' ? 'cdp-port 6663' : 'watcher-port 8081'}`,
+      );
     }
   }
   applyLaunchEnvOverrides(options, adapter, mobileTarget, target);
@@ -125,9 +128,8 @@ export async function handleLaunch(argv: string[]): Promise<number> {
     return usageOut(
       json,
       'launch',
-      `native build inputs changed since last build — run: mm-harness launch ${
-        adapter === 'mobile' ? `${mobileTarget} ` : ''
-      }--build`,
+      'native build inputs changed since last build.',
+      `mm-harness launch ${adapter === 'mobile' ? `${mobileTarget} ` : ''}--build`,
     );
   }
 

package/src/commands/logs.ts

@@ -6,7 +6,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { recipeRuntimePath, runnerDir } from '../paths.ts';
-import { EXIT, flag, parseFlags, resolveAdapter, spawnScript, str, targetOf, usageOut } from './shared.ts';
+import { ADAPTER_DETECT_NEXT, EXIT, flag, parseFlags, resolveAdapter, spawnScript, str, targetOf, usageOut } from './shared.ts';
 
 const LOGS_BOOLEANS = new Set(['full', 'json']);
 
@@ -17,19 +17,15 @@ export async function handleLogs(argv: string[]): Promise<number> {
   const adapter = resolveAdapter(options, target);
 
   if (!adapter) {
-    return usageOut(
-      json,
-      'logs',
-      `could not detect the MetaMask repo type for ${target}\n  Next: pass --target <checkout>   or   cd into the checkout, then re-run: mm-harness logs`,
-    );
+    return usageOut(json, 'logs', `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   }
   if (adapter === 'core') {
-    return usageOut(json, 'logs', 'core is headless; there are no app/Metro logs.\n  Next: mm-harness run <recipe>   # run recipes against the headless core');
+    return usageOut(json, 'logs', 'core is headless; there are no app/Metro logs.', 'mm-harness run <recipe>   # run recipes against the headless core');
   }
 
   const source = str(options, 'source') ?? 'metro';
   if (source !== 'metro' && source !== 'app') {
-    return usageOut(json, 'logs', '--source must be metro or app.\n  Next: mm-harness logs --source metro   or   mm-harness logs --source app');
+    return usageOut(json, 'logs', '--source must be metro or app.', 'mm-harness logs --source metro   or   mm-harness logs --source app');
   }
 
   // Env-gap flag (docs/CLI-SPEC.md Part 4): --events sets the compact event count
@@ -38,7 +34,7 @@ export async function handleLogs(argv: string[]): Promise<number> {
   const events = str(options, 'events');
   if (events !== undefined) {
     if (!/^\d+$/u.test(events)) {
-      return usageOut(json, 'logs', `--events must be numeric (got: ${events}).\n  Next: mm-harness logs --events 20`);
+      return usageOut(json, 'logs', `--events must be numeric (got: ${events}).`, 'mm-harness logs --events 20');
     }
     process.env.RECIPE_LOG_EVENTS = events;
   }
@@ -51,7 +47,8 @@ export async function handleLogs(argv: string[]): Promise<number> {
     return usageOut(
       json,
       'logs',
-      `nothing running for this checkout (no ${path.basename(logFile)}).\n  Next: ${launchHint}`,
+      `nothing running for this checkout (no ${path.basename(logFile)}).`,
+      launchHint,
     );
   }
 

package/src/commands/shared.ts

@@ -95,12 +95,14 @@ export interface ScriptResult {
 
 // Compose an adapters/ script directly. Output is always captured (needed for
 // heal classification) and, in human mode, forwarded to stderr. --json keeps
-// stdout clean for the machine summary.
+// stdout clean for the machine summary. `env` overlays extra vars onto the
+// inherited environment for spawns that need a scoped variable (e.g. color mode).
 export function spawnScript(
   script: string,
   args: string[],
   cwd: string,
   json: boolean,
+  env?: Record<string, string>,
 ): ScriptResult {
   // For node invocations (script === process.execPath) the seam stem is derived
   // from args[0] so each spawned script has its own override key.
@@ -114,7 +116,7 @@ export function spawnScript(
   const result = spawnSync(bin, spawnArgs, {
     cwd,
     encoding: 'utf8',
-    env: process.env,
+    env: env ? { ...process.env, ...env } : process.env,
     maxBuffer: 64 * 1024 * 1024,
   });
   if (result.error) {
@@ -125,14 +127,24 @@ export function spawnScript(
   return { status: result.status ?? 1, output };
 }
 
-// Teaching-error emitter (exit 2, machine-readable in --json).
-export function usageOut(json: boolean, command: string, message: string): number {
+// Both escapes from a failed repo-type detection (defined at the detection source
+// in harness.ts): where to run it (checkout/target) and how to force it (adapter).
+export { ADAPTER_DETECT_NEXT } from '../harness.ts';
+
+// Teaching-error emitter (exit 2, machine-readable in --json). `userAction` is
+// REQUIRED: a teaching error without a reachable escape must not compile, so the
+// escape is a typed parameter rather than free-form prose spliced into `message`.
+export function usageOut(json: boolean, command: string, message: string, userAction: string): number {
   if (json) {
     console.log(
-      JSON.stringify({ schemaVersion: 1, command, status: 'fail', exitCode: EXIT.usage, error: { code: 'USAGE', message } }, null, 2),
+      JSON.stringify(
+        { schemaVersion: 1, command, status: 'fail', exitCode: EXIT.usage, error: { code: 'USAGE', message, userAction } },
+        null,
+        2,
+      ),
     );
   } else {
-    console.error(`✗ mm-harness ${command}: ${message}`);
+    console.error(`✗ mm-harness ${command}: ${message}\n  Next: ${userAction}`);
   }
   return EXIT.usage;
 }

package/src/commands/update.ts

@@ -0,0 +1,316 @@
+// update — keep the globally-installed mm-harness current against the npm registry.
+// `mm-harness update` upgrades to the published latest; `--check` reports without
+// touching anything; `--json` carries { current, latest, updateAvailable }. A
+// passive once-a-day nudge (maybeNudge) prints a single stderr line when a newer
+// version exists — it never blocks, never auto-updates, and stays off stdout so
+// the --json contract of every other command is untouched. Every failure path
+// (no npm, registry unreachable, permission-denied global dir) names its escape.
+//
+// Two fetch strategies:
+//   fetchLatest    — spawnSync(`npm view`) used by the explicit `update` command;
+//                    respects the user's npm registry config; bounded by timeoutMs.
+//   fetchLatestAsync — native fetch() used by the passive nudge; never spawns a
+//                    subprocess; hard-aborts at timeoutMs so it cannot block the
+//                    event loop beyond that bound.
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { runnerDir } from '../paths.ts';
+import { EXIT, flag, parseFlags } from './shared.ts';
+
+export const PACKAGE_NAME = '@deeeed/metamask-harness';
+const NUDGE_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const NUDGE_FETCH_TIMEOUT_MS = 300;
+
+export function currentVersion(): string {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(runnerDir, 'package.json'), 'utf8')) as { version?: string };
+    return pkg.version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function parseVersion(value: string): { nums: number[]; pre: string } {
+  const cleaned = value.replace(/^v/u, '');
+  const dash = cleaned.indexOf('-');
+  const core = dash === -1 ? cleaned : cleaned.slice(0, dash);
+  const pre = dash === -1 ? '' : cleaned.slice(dash + 1);
+  const nums = core.split('.').map((part) => Number.parseInt(part, 10) || 0);
+  while (nums.length < 3) nums.push(0);
+  return { nums, pre };
+}
+
+// True when `candidate` is a strictly higher version than `base`. A release outranks
+// a prerelease of the same core (1.0.0 > 1.0.0-rc.1); prereleases compare lexically.
+export function isNewer(candidate: string, base: string): boolean {
+  const a = parseVersion(candidate);
+  const b = parseVersion(base);
+  for (let i = 0; i < 3; i += 1) {
+    if (a.nums[i] !== b.nums[i]) return a.nums[i] > b.nums[i];
+  }
+  if (a.pre === b.pre) return false;
+  if (a.pre === '') return true;
+  if (b.pre === '') return false;
+  return a.pre > b.pre;
+}
+
+export interface FetchResult {
+  latest?: string;
+  error?: { kind: 'no-npm' | 'unreachable'; message: string };
+}
+
+// Query the registry dist-tag `latest` via `npm view`. `timeoutMs` bounds the
+// wait; callers MUST pass a finite value — an unbounded registry call can hang
+// indefinitely. When the timeout fires, spawnSync sets result.signal to SIGTERM.
+export function fetchLatest(timeoutMs: number): FetchResult {
+  const result = spawnSync('npm', ['view', PACKAGE_NAME, 'dist-tags.latest'], {
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.error) {
+    const code = (result.error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') return { error: { kind: 'no-npm', message: 'npm was not found on PATH' } };
+    return { error: { kind: 'unreachable', message: result.error.message } };
+  }
+  if (result.signal) {
+    return { error: { kind: 'unreachable', message: `registry fetch timed out after ${timeoutMs}ms` } };
+  }
+  if (result.status !== 0) {
+    return { error: { kind: 'unreachable', message: (result.stderr ?? '').trim() || `npm view exited ${result.status}` } };
+  }
+  const latest = (result.stdout ?? '').trim();
+  if (!latest) return { error: { kind: 'unreachable', message: 'npm returned no dist-tag for latest' } };
+  return { latest };
+}
+
+// Async variant for the passive nudge: uses the native fetch() API so it never
+// spawns a subprocess and never blocks the event loop. Hard-aborts at timeoutMs.
+// Skips silently on any error (nudge is best-effort).
+async function fetchLatestAsync(timeoutMs: number): Promise<FetchResult> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const url = `https://registry.npmjs.org/-/package/${encodeURIComponent(PACKAGE_NAME)}/dist-tags`;
+    const res = await fetch(url, { signal: controller.signal });
+    if (!res.ok) return { error: { kind: 'unreachable', message: `registry returned HTTP ${res.status}` } };
+    const data = (await res.json()) as Record<string, string>;
+    const latest = data['latest'];
+    if (!latest) return { error: { kind: 'unreachable', message: 'npm registry returned no latest dist-tag' } };
+    return { latest };
+  } catch (err) {
+    const msg = (err as Error).name === 'AbortError'
+      ? `registry fetch timed out after ${timeoutMs}ms`
+      : (err as Error).message;
+    return { error: { kind: 'unreachable', message: msg } };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Non-zero on every failure (EXIT.infra = 3) so it never collides with `--check`'s
+// exit 1 = "update available"; each carries the exact reachable escape.
+function teachFailure(
+  json: boolean,
+  current: string,
+  code: string,
+  message: string,
+  userAction: string,
+): number {
+  if (json) {
+    console.log(
+      JSON.stringify(
+        { schemaVersion: 1, command: 'update', status: 'fail', current, error: { code, message, userAction } },
+        null,
+        2,
+      ),
+    );
+  } else {
+    console.error(`✗ mm-harness update: ${message}\n  Next: ${userAction}`);
+  }
+  return EXIT.infra;
+}
+
+function emitFetchError(json: boolean, error: NonNullable<FetchResult['error']>, current: string): number {
+  if (error.kind === 'no-npm') {
+    return teachFailure(
+      json,
+      current,
+      'NO_NPM',
+      'npm was not found on PATH — cannot check for updates',
+      'install Node.js (which bundles npm) from https://nodejs.org, then re-run: mm-harness update',
+    );
+  }
+  return teachFailure(
+    json,
+    current,
+    'REGISTRY_UNREACHABLE',
+    `could not reach the npm registry (${error.message})`,
+    'check your network, then re-run: mm-harness update — or inspect the registry with: npm config get registry',
+  );
+}
+
+export async function handleUpdate(argv: string[]): Promise<number> {
+  const { options } = parseFlags(argv, new Set(['check', 'json']));
+  const json = flag(options, 'json');
+  const checkOnly = flag(options, 'check');
+  const current = currentVersion();
+
+  const fetched = fetchLatest(30_000);
+  if (fetched.error) return emitFetchError(json, fetched.error, current);
+  const latest = fetched.latest as string;
+  const updateAvailable = isNewer(latest, current);
+
+  if (checkOnly) {
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, command: 'update', current, latest, updateAvailable }, null, 2));
+    } else if (updateAvailable) {
+      console.error(`mm-harness ${current} → ${latest} available · run: mm-harness update`);
+    } else {
+      console.log(`mm-harness is up to date (${current}).`);
+    }
+    // exit 1 signals "update available"; exit 0 signals up-to-date.
+    return updateAvailable ? EXIT.runtime : EXIT.ok;
+  }
+
+  if (!updateAvailable) {
+    if (json) {
+      console.log(JSON.stringify({ schemaVersion: 1, command: 'update', current, latest, updateAvailable: false, updated: false }, null, 2));
+    } else {
+      console.log(`mm-harness is up to date (${current}).`);
+    }
+    return EXIT.ok;
+  }
+
+  const INSTALL_TIMEOUT_MS = 5 * 60 * 1000;
+  const install = spawnSync('npm', ['i', '-g', `${PACKAGE_NAME}@latest`], {
+    encoding: 'utf8',
+    timeout: INSTALL_TIMEOUT_MS,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (install.error) {
+    const code = (install.error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') return emitFetchError(json, { kind: 'no-npm', message: 'npm was not found on PATH' }, current);
+    return teachFailure(json, current, 'INSTALL_FAILED', `global install failed (${install.error.message})`, `run it directly to see the error: npm i -g ${PACKAGE_NAME}@latest`);
+  }
+  if (install.signal) {
+    return teachFailure(
+      json,
+      current,
+      'INSTALL_FAILED',
+      `global install timed out after ${INSTALL_TIMEOUT_MS / 1000}s — slow network or registry unavailable`,
+      `check your network, then retry: mm-harness update — or install manually: npm i -g ${PACKAGE_NAME}@latest`,
+    );
+  }
+  const combined = `${install.stdout ?? ''}${install.stderr ?? ''}`;
+  if (install.status !== 0) {
+    if (/EACCES|permission denied|EPERM/iu.test(combined)) {
+      return teachFailure(
+        json,
+        current,
+        'GLOBAL_DIR_PERMISSION',
+        'global install denied — the npm global directory is not writable',
+        'either re-run with sudo, or point npm at a user-writable prefix: npm config set prefix ~/.npm-global (then add ~/.npm-global/bin to PATH) and re-run: mm-harness update',
+      );
+    }
+    return teachFailure(
+      json,
+      current,
+      'INSTALL_FAILED',
+      `global install failed (${combined.trim() || `npm exited ${install.status}`})`,
+      `run it directly to see the error: npm i -g ${PACKAGE_NAME}@latest`,
+    );
+  }
+
+  // Re-check the registry so the reported new version is the one that resolved,
+  // not merely the tag we asked for. Best-effort — fall back to the tag if slow.
+  const rechecked = fetchLatest(30_000);
+  const installed = rechecked.latest ?? latest;
+  if (json) {
+    console.log(JSON.stringify({ schemaVersion: 1, command: 'update', current, latest: installed, updateAvailable: true, updated: true, from: current, to: installed }, null, 2));
+  } else {
+    console.log(`mm-harness updated ${current} → ${installed}.`);
+  }
+  return EXIT.ok;
+}
+
+// --- Passive update nudge ----------------------------------------------------
+
+interface NudgeCache {
+  lastCheck: number;
+  latest: string;
+}
+
+function cacheFile(): string {
+  const override = process.env.MM_HARNESS_UPDATE_CACHE;
+  if (override) return override;
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(base, 'mm-harness', 'update-check.json');
+}
+
+function readCache(file: string): NudgeCache | null {
+  try {
+    const data = JSON.parse(fs.readFileSync(file, 'utf8')) as Partial<NudgeCache>;
+    if (typeof data.lastCheck === 'number' && typeof data.latest === 'string') {
+      return { lastCheck: data.lastCheck, latest: data.latest };
+    }
+  } catch {
+    // Missing or corrupt cache = no prior state; a fresh probe will rebuild it.
+  }
+  return null;
+}
+
+function writeCache(file: string, cache: NudgeCache): void {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(cache));
+  } catch {
+    // Best-effort; a cache we cannot persist just means the next run re-probes.
+  }
+}
+
+// Suppressed in CI and when the user opts out — the nudge is for interactive use.
+export function nudgeDisabled(): boolean {
+  return process.env.MM_HARNESS_NO_UPDATE_CHECK === '1' || Boolean(process.env.CI);
+}
+
+// Pure decision, testable without a clock or network.
+export function nudgeLine(current: string, latest: string): string | null {
+  return isNewer(latest, current) ? `mm-harness ${current} → ${latest} available · run: mm-harness update` : null;
+}
+
+// One throttled, bounded, stderr-only line when a newer version is published.
+// Called via setImmediate in mm-harness-cli.ts so no nudge code runs before
+// parse/dispatch starts. Prints AFTER command output via process.once('exit'),
+// giving cleaner UX than mid-output interleaving. The `latest` closure variable
+// is captured by the exit handler; an async probe that resolves before
+// process.exit() fires updates it automatically. Offline / timeout / no network
+// skip silently. Cache timestamp is stamped before the fetch so an abandoned
+// probe (process exits within 300ms) does not re-probe on the next invocation.
+export async function maybeNudge(now: number = Date.now()): Promise<void> {
+  if (nudgeDisabled()) return;
+  const file = cacheFile();
+  const cache = readCache(file);
+  const current = currentVersion();
+  // Mutable: exit handler closes over this so a probe result that arrives before
+  // process.exit() automatically updates what gets printed.
+  let latest = cache?.latest ?? '';
+  // Register once — checks nudgeLine at exit time, picking up the freshest value.
+  process.once('exit', () => {
+    const line = nudgeLine(current, latest);
+    if (line) process.stderr.write(`${line}\n`);
+  });
+  if (!cache || now - cache.lastCheck >= NUDGE_INTERVAL_MS) {
+    // Stamp before the fetch so a killed probe does not re-probe next run.
+    writeCache(file, { lastCheck: now, latest });
+    const fetched = await fetchLatestAsync(NUDGE_FETCH_TIMEOUT_MS);
+    if (fetched.latest) {
+      latest = fetched.latest;
+      writeCache(file, { lastCheck: now, latest });
+    }
+  }
+}

package/src/harness.ts

@@ -156,6 +156,12 @@ function parseHarnessArgs(args: string[]): ParsedHarnessArgs {
 // Mirror of scripts/lib/cli-common.sh detect_adapter for the auto-detect path.
 // Exported so `doctor` shares the exact same detect-from-target logic as the
 // overlay commands (verify/install/cleanup) — one auto-detect story, no drift.
+// Both escapes from a failed repo-type detection: where to run it (checkout/target)
+// and how to force it (adapter). A single source so every detect-failure teaches
+// the same reachable next step.
+export const ADAPTER_DETECT_NEXT =
+  'cd into a MetaMask checkout or pass --target <path>, or force it with --adapter <mobile|extension|core>';
+
 export function detectAdapter(target: string): MetaMaskRecipeAdapter | undefined {
   let remote = '';
   try {
@@ -395,6 +401,7 @@ async function handleMobileLive(
         harnessSummary('live', 'mobile', target, 'fail', prepResult.status, autoDetected, {
           code: 'MOBILE_PREPARE_FAILED',
           message: `mobile prepare failed (exit ${prepResult.status})`,
+          userAction: failureHint('mobile', 'live'),
         }),
       );
     } else {
@@ -433,7 +440,7 @@ async function handleMobileLive(
         autoDetected,
         exitCode === 0
           ? undefined
-          : { code: 'MOBILE_VERIFY_FAILED', message: `mobile live verify failed (exit ${exitCode})` },
+          : { code: 'MOBILE_VERIFY_FAILED', message: `mobile live verify failed (exit ${exitCode})`, userAction: failureHint('mobile', 'live') },
       ),
     );
   } else if (exitCode === 0) {
@@ -470,15 +477,15 @@ export async function handleHarness(argv: string[]): Promise<number> {
       // parsedAdapter is string|undefined here; not yet validated as a real
       // adapter, so pass undefined rather than forwarding a garbage string.
       const detectError = adapter
-        ? { code: 'UNSUPPORTED_PLATFORM', message: `unsupported platform: ${adapter}` }
-        : { code: 'ADAPTER_DETECTION_FAILED', message: `could not detect the MetaMask repo type for ${target}` };
+        ? { code: 'UNSUPPORTED_PLATFORM', message: `unsupported platform: ${adapter}`, userAction: 'pass --adapter <mobile|extension|core> to specify a supported adapter' }
+        : { code: 'ADAPTER_DETECTION_FAILED', message: `could not detect the MetaMask repo type for ${target}`, userAction: ADAPTER_DETECT_NEXT };
       console.log(harnessSummary(harnessAction, undefined, target, 'fail', 2, false, detectError));
     } else {
       harnessUsage();
       console.error(
         adapter
           ? `\n✗ unsupported platform: ${adapter}`
-          : `\n✗ could not detect the MetaMask repo type for ${target}\n  Next: pass --platform mobile|extension|core`,
+          : `\n✗ could not detect the MetaMask repo type for ${target}\n  Next: ${ADAPTER_DETECT_NEXT}`,
       );
     }
     return 2;
@@ -489,6 +496,7 @@ export async function handleHarness(argv: string[]): Promise<number> {
         harnessSummary(harnessAction, adapter, target, 'fail', 2, parsedAdapter === undefined, {
           code: 'UNSUPPORTED_ACTION',
           message: `${harnessAction} is not supported for ${adapter} (core supports install, verify, cleanup).`,
+          userAction: 'run mm-harness doctor to see which actions are supported for this adapter',
         }),
       );
     } else {
@@ -519,6 +527,9 @@ export async function handleHarness(argv: string[]): Promise<number> {
         harnessSummary(harnessAction, adapter, target, 'fail', 1, autoDetected, {
           code: 'DISPATCH_UNAVAILABLE',
           message: dispatch.error,
+          // The dispatch error embeds "Next: <hint>" — extract it so --json consumers
+          // get a clean programmatic escape without parsing the human message.
+          userAction: dispatch.error.split('\nNext: ')[1] ?? 'run mm-harness install to complete setup, then retry',
         }),
       );
     } else {
@@ -547,6 +558,7 @@ export async function handleHarness(argv: string[]): Promise<number> {
         harnessSummary(harnessAction, adapter, target, 'fail', 1, autoDetected, {
           code: 'HARNESS_SPAWN_FAILED',
           message: `${harnessAction} ${adapter} could not start: ${result.error.message}`,
+          userAction: failureHint(adapter, harnessAction),
         }),
       );
     } else {
@@ -567,7 +579,7 @@ export async function handleHarness(argv: string[]): Promise<number> {
         autoDetected,
         exitCode === 0
           ? undefined
-          : { code: 'HARNESS_FAILED', message: `${harnessAction} ${adapter} failed (exit ${exitCode})` },
+          : { code: 'HARNESS_FAILED', message: `${harnessAction} ${adapter} failed (exit ${exitCode})`, userAction: failureHint(adapter, harnessAction) },
       ),
     );
   } else if (exitCode === 0) {
@@ -578,6 +590,9 @@ export async function handleHarness(argv: string[]): Promise<number> {
   return exitCode;
 }
 
+// userAction is required whenever an error object is present so every --json
+// failure carries a machine-readable escape path — parallel to the `usageOut`
+// enforcement on the CLI layer. Omitting userAction is a compile-time error.
 function harnessSummary(
   action: HarnessAction,
   adapter: MetaMaskRecipeAdapter | undefined,
@@ -585,7 +600,7 @@ function harnessSummary(
   status: 'pass' | 'fail',
   exitCode: number,
   autoDetected: boolean,
-  error?: { code: string; message: string },
+  error?: { code: string; message: string; userAction: string },
 ): string {
   return JSON.stringify({
     schemaVersion: 1,
@@ -597,7 +612,8 @@ function harnessSummary(
     status,
     exitCode,
     // Error contract: every --json failure carries a stable machine code + human
-    // message (CLI-SPEC.md §5.1).
+    // message (CLI-SPEC.md §5.1). userAction is included when present so callers
+    // can surface the reachable escape without parsing the human message.
     ...(status === 'fail' && error ? { error } : {}),
   });
 }

package/src/heal-bounds.ts

@@ -7,6 +7,7 @@
 
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
+import path from 'node:path';
 
 import { handleHarness } from './harness.ts';
 import { recipeHarnessPath, recipeRuntimePath } from './paths.ts';
@@ -54,6 +55,24 @@ function overlayPresent(target: string, adapter: MetaMaskRecipeAdapter): boolean
   }
 }
 
+// Validates that the installed overlay's runner-source stamp points to an existing
+// runner directory whose binary is still present. Two failure modes are detected:
+//   1. Stale stamp — runner dir moved or renamed since install (dir absent).
+//   2. Stale exec target — runner dir exists but its bin/mm-harness was removed
+//      (e.g. the package was unlinked/purged inside an otherwise-live dir).
+// Either way the delegate binary will fail to exec; treat the overlay as absent
+// so auto-ensure re-installs it from the current runner.
+function overlayDelegateValid(target: string, adapter: MetaMaskRecipeAdapter): boolean {
+  if (adapter === 'core') return true;
+  const pointer = path.join(recipeHarnessPath(target, adapter), 'runner', '.runner-source');
+  if (!fs.existsSync(pointer)) return true; // no stamp = running from local runner, valid
+  const runnerPath = fs.readFileSync(pointer, 'utf8').trim();
+  if (!Boolean(runnerPath) || !fs.existsSync(runnerPath)) return false;
+  // Runner dir is present; verify the binary inside still exists — the directory
+  // can survive a package removal while the binary inside is deleted.
+  return fs.existsSync(path.join(runnerPath, 'bin', 'mm-harness'));
+}
+
 // Auto-ensure the runtime overlay (install phase). Missing + heal != off →
 // install inline, emit a first-install notice to stderr, and record the mutation.
 // heal === off disables auto-install (repro-preserving); we proceed and let the
@@ -67,7 +86,7 @@ export async function ensureOverlay(
 ): Promise<{ ok: boolean; error?: string }> {
   // core is headless — the engine path used by run/call needs no launch overlay.
   if (adapter === 'core') return { ok: true };
-  if (overlayPresent(target, adapter)) return { ok: true };
+  if (overlayPresent(target, adapter) && overlayDelegateValid(target, adapter)) return { ok: true };
   if (heal === 'off') return { ok: true };
 
   const installBin = process.env.MM_HARNESS_INSTALL_BIN;

package/src/mm-harness-cli.ts

@@ -12,6 +12,8 @@ import { fileURLToPath } from 'node:url';
 
 import { Command } from 'commander';
 
+import { handleUpdate, maybeNudge } from './commands/update.ts';
+
 // …/src → its parent is the package root that holds scripts/.
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -245,6 +247,26 @@ Example:
   mm-harness debug
   mm-harness debug --worker`,
   },
+  {
+    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 → new;
+  already-current exits 0.
+
+  --check                            Report only — 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: 'fixtures',
     summary: 'Manage the canonical wallet fixture (wallet DATA only) — sync files / set the wallet.',
@@ -340,6 +362,11 @@ const HELP_GROUPS: HelpGroup[] = [
     blurb: 'install/verify/clean the per-checkout overlay (the everyday commands auto-ensure it)',
     commands: ['install', 'verify', 'cleanup'],
   },
+  {
+    title: 'MAINTAIN',
+    blurb: 'keep the installed harness current with the npm registry',
+    commands: ['update'],
+  },
 ];
 
 function commandMeta(name: string): { summary: string; example: string; planned: boolean } {
@@ -371,6 +398,9 @@ function groupedHelp(): string {
   lines.push('SETUP — 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 — 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 docs/MENTAL-MODEL.md (overview) and docs/CLI-SPEC.md (full contract).');
   return `${lines.join('\n')}\n`;
 }
@@ -430,6 +460,11 @@ for (const command of REAL) {
         process.stdout.write(`${command.helpText}\n`);
         process.exit(0);
       }
+      // `update` is self-contained registry tooling (no engine, no overlay), so it
+      // runs directly rather than through the dispatch in cli.ts.
+      if (command.name === 'update') {
+        process.exit(await handleUpdate(rawArgv.slice(1)));
+      }
       const argv = command.name === 'actions' && rawArgv.includes('--raw') ? translateActionsRaw(rawArgv) : rawArgv;
       process.exit(await delegate(argv));
     });
@@ -496,6 +531,16 @@ for (const retired of RETIRED) {
     });
 }
 
+// Passive update nudge: one throttled stderr line if a newer version is published.
+// Skipped for update itself (redundant) and for shell/completion tooling (whose
+// stdout is consumed by the shell). stderr-only keeps every --json stdout clean.
+const NUDGE_SKIP: readonly string[] = ['update', 'completions', 'completion-candidates'];
+if (rawArgv.length > 0 && !NUDGE_SKIP.includes(rawArgv[0])) {
+  // Fully deferred: no nudge code runs before parseAsync starts. The exit hook
+  // registered inside maybeNudge prints the line after command output.
+  setImmediate(() => void maybeNudge());
+}
+
 if (rawArgv.length === 0) {
   process.stdout.write(groupedHelp());
   process.exit(0);