@deeeed/metamask-harness 0.19.1 → 0.20.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 0.20.0 - 2026-07-24
+
+### Added
+
+- `mm-harness checklist closeout` delegates learning capture to `@farmslot/handoff`; successful terminal marks stage automatically while sharing stays explicit.
+
+### Fixed
+
+- Extension readiness bounds both CDP connection setup and page calls instead of hanging.
+- Extension readiness reports a suspended UI compositor instead of claiming a reachable CDP page is interactive.
+- Extension hash navigation stays inside the running app so SPA routes are not reset during startup.
+- `ui.navigate page=perps` discovers and activates current Perps controls, including bounded back navigation from detail screens, and verifies the destination; bundled recipes no longer embed stale product routes.
+- Semantic Extension navigation honors the caller timeout while avoiding repeated control activation.
+- Invalid enum recovery commands use the closest valid value instead of repeating the rejected input.
+- Perps mutation plans fail early when required market, side, or amount inputs are missing.
+- `check diff` honors the checkout's configured ESLint config file.
+- Extension builds no longer certify dependency state; Yarn `node-modules` freshness follows the installed tree and only successful installs record its baseline.
+
 ## 0.19.1 - 2026-07-23
 
 ### Added

package/adapters/extension/ensure-browser.sh

@@ -277,7 +277,11 @@ const fs = require('fs');
 const http = require('http');
 const { execSync, execFileSync } = require('child_process');
 let chromium; try { chromium = require('@playwright/test').chromium; } catch { chromium = require('playwright').chromium; }
-const { isolatedProfileArgs, remoteDebuggingArgs } = require(path.join('${SCRIPT_DIR}', 'lib/chrome-args.cjs'));
+const {
+  automationRuntimeArgs,
+  isolatedProfileArgs,
+  remoteDebuggingArgs,
+} = require(path.join('${SCRIPT_DIR}', 'lib/chrome-args.cjs'));
 const { captureMacFrontmostProcess, restoreMacFrontmostProcess } = require(path.join('${SCRIPT_DIR}', 'lib/macos-focus.cjs'));
 
 const SLOT_ID = '${SLOT_ID}';
@@ -304,9 +308,7 @@ const resumeWebpack = () => {
     '--user-data-dir=' + PROFILE,
     '--disable-extensions-except=' + EXTENSION,
     '--load-extension=' + EXTENSION,
-    '--disable-background-timer-throttling',
-    '--disable-backgrounding-occluded-windows',
-    '--disable-renderer-backgrounding',
+    ...automationRuntimeArgs(),
     '--no-first-run',
     '--no-default-browser-check',
     ...isolatedProfileArgs(),

package/adapters/extension/launch-browser.cjs

@@ -24,7 +24,11 @@ const os = require('node:os');
 const path = require('node:path');
 const { execFileSync, spawn, spawnSync } = require('node:child_process');
 const { extensionIdFromExtensionDir } = require('./lib/extension-id.cjs');
-const { isolatedProfileArgs, remoteDebuggingArgs } = require('./lib/chrome-args.cjs');
+const {
+  automationRuntimeArgs,
+  isolatedProfileArgs,
+  remoteDebuggingArgs,
+} = require('./lib/chrome-args.cjs');
 const { captureMacFrontmostProcess, restoreMacFrontmostProcess } = require('./lib/macos-focus.cjs');
 
 if (process.argv.includes('--help') || process.argv.includes('-h')) {
@@ -99,6 +103,7 @@ const chromeArgs = [
   ...remoteDebuggingArgs(cdpPort),
   '--no-first-run',
   '--disable-first-run-ui',
+  ...automationRuntimeArgs(),
   ...isolatedProfileArgs(),
   '--disable-default-apps',
   '--disable-popup-blocking',

package/adapters/extension/lib/chrome-args.cjs

@@ -28,4 +28,14 @@ function isolatedProfileArgs(platform = process.platform) {
   return platform === 'darwin' ? ['--use-mock-keychain'] : [];
 }
 
-module.exports = { isolatedProfileArgs, remoteDebuggingArgs };
+// Keep requestAnimationFrame, transitions, and input hit testing alive when the
+// slot-owned browser is occluded by the operator's other windows.
+function automationRuntimeArgs() {
+  return [
+    '--disable-background-timer-throttling',
+    '--disable-backgrounding-occluded-windows',
+    '--disable-renderer-backgrounding',
+  ];
+}
+
+module.exports = { automationRuntimeArgs, isolatedProfileArgs, remoteDebuggingArgs };

package/adapters/extension/start-watch.sh

@@ -338,6 +338,6 @@ fi
 echo '[recipe-harness] yarn start compiled successfully'
 if [ -n "$RUNNER_BIN" ]; then
   "$RUNNER_BIN" runtime-decision --adapter extension --target . --record-baseline --json >/dev/null 2>&1 || true
-  echo '[recipe-harness] recorded deps/cache baseline (runtime-decision --record-baseline)'
+  echo '[recipe-harness] recorded webpack cache baseline (runtime-decision --record-baseline)'
 fi
 status=pass

package/adapters/extension/verify.sh

@@ -407,6 +407,23 @@ if [ "$STATIC_ONLY" = false ]; then
       refresh_extension_id
     else
       checks+=("{\"name\":\"home-tab convergence\",\"status\":\"fail\",\"detail\":\"see logs/extension-ensure-ready.json\"}")
+      node - "$ARTIFACTS/logs/extension-ensure-ready.json" <<'NODE' >&2
+const fs = require('fs');
+const file = process.argv[2];
+try {
+  const report = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const code = report.health?.errorCode;
+  const findings = Array.isArray(report.health?.findings) ? report.health.findings : [];
+  if (code) {
+    const finding = findings[0] ?? 'Extension UI is not interactive.';
+    console.error(finding.startsWith(`${code}:`) ? finding : `${code}: ${finding}`);
+  }
+  else if (findings[0]) console.error(findings[0]);
+  if (report.health?.userAction) console.error(`Next: ${report.health.userAction}`);
+} catch {
+  // The summary retains the raw helper output for diagnosis.
+}
+NODE
       status="fail"
     fi
 

package/adapters/mobile/open-device.sh

@@ -13,6 +13,7 @@
 #   --simulator <udid|name|"booted">    iOS simulator (default: IOS_SIMULATOR env, else "booted")
 #   --adb-serial <serial>               Android device serial (default: ADB_SERIAL env)
 #   --preflight-mode fast|auto|rebuild-native|clean  (default: fast; env MOBILE_PREFLIGHT_MODE)
+#   --restart                            terminate the selected app before opening it
 #   --ui-only                           iOS only: ensure Simulator.app is visible; do not relaunch the app
 # Outputs:
 #   Progress on stderr; exit 0 pass; 1 open failed; 2 bad args.
@@ -27,6 +28,7 @@ ADB_SERIAL_ARG="${ADB_SERIAL:-${ANDROID_SERIAL:-}}"
 PREFLIGHT_MODE="${MOBILE_PREFLIGHT_MODE:-fast}"
 PORT="${WATCHER_PORT:-${METRO_PORT:-8081}}"
 UI_ONLY=false
+RESTART=false
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
@@ -36,11 +38,12 @@ while [ "$#" -gt 0 ]; do
     --adb-serial)     ADB_SERIAL_ARG="$2"; shift 2 ;;
     --preflight-mode) PREFLIGHT_MODE="$2"; shift 2 ;;
     --port)           PORT="$2"; shift 2 ;;
+    --restart)        RESTART=true; shift ;;
     --ui-only)        UI_ONLY=true; shift ;;
     -h|--help)
       printf 'Usage: open-device.sh [--platform ios|android] [--target <dir>]\n'
       printf '  [--simulator <udid|name|booted>] [--adb-serial <serial>]\n'
-      printf '  [--preflight-mode fast|auto|rebuild-native|clean] [--port <n>] [--ui-only]\n'
+      printf '  [--preflight-mode fast|auto|rebuild-native|clean] [--port <n>] [--restart] [--ui-only]\n'
       exit 0
       ;;
     *) printf 'open-device: unknown arg: %s\n' "$1" >&2; exit 2 ;;
@@ -265,6 +268,10 @@ if [ "$PLATFORM" = "ios" ]; then
   LAUNCHED=false
   for BUNDLE_ID in "${BUNDLE_IDS[@]}"; do
     ensure_ios_app_for_mode "$SIM_TARGET" "$BUNDLE_ID" "$PREFLIGHT_MODE" || continue
+    if $RESTART; then
+      xcrun simctl terminate "$SIM_TARGET" "$BUNDLE_ID" >/dev/null 2>&1 || true
+      printf 'Restarting iOS dev client %s on %s\n' "$BUNDLE_ID" "$SIM_TARGET" >&2
+    fi
 
     # Dismiss Expo dev-menu onboarding for clean headless runs.
     xcrun simctl spawn "$SIM_TARGET" defaults write "$BUNDLE_ID" \
@@ -314,6 +321,10 @@ else
   LAUNCHED=false
   for PKG in "${ANDROID_PKGS[@]}"; do
     ensure_android_app_for_mode "$PKG" "$PREFLIGHT_MODE" "${ADB_ARGS[@]}" || continue
+    if $RESTART; then
+      adb "${ADB_ARGS[@]}" shell am force-stop "$PKG" >/dev/null 2>&1 || true
+      printf 'Restarting Android dev client %s\n' "$PKG" >&2
+    fi
 
     ENCODED_URL="$(urlencode "http://localhost:${PORT}?disableOnboarding=1" 2>/dev/null \
       || printf 'http%%3A%%2F%%2Flocalhost%%3A%s%%3FdisableOnboarding%%3D1' "$PORT")"

package/adapters/mobile/wait-for-bridge.sh

@@ -158,5 +158,5 @@ printf 'wait-for-bridge: no bridge target matched the requested %s on port %s (%
   "$(requested_target)" "$PORT" "$MAX_POLLS" "$((MAX_POLLS * 2))" >&2
 printf '  requested: %s\n' "$(requested_target)" >&2
 printf '  answered:  %s\n' "$(answered_targets)" >&2
-printf '  Next: check %s — or run mm-harness app-status\n' "$STATUS_LOG" >&2
+printf '  Next: check %s — or run mm-harness status --json\n' "$STATUS_LOG" >&2
 exit 1

package/dist/adapters/extension/ensure-ready.js

@@ -135,7 +135,12 @@ async function ensureExtensionReady(target, options) {
     try {
       const { checkExtensionRuntimeHealth } = await import("./runtime.js");
       const report = await checkExtensionRuntimeHealth(resolved, cdpPort);
-      return { status: report.status, findings: report.findings };
+      return {
+        status: report.status,
+        ...report.errorCode ? { errorCode: report.errorCode } : {},
+        ...report.userAction ? { userAction: report.userAction } : {},
+        findings: report.findings
+      };
     } catch (error) {
       return { status: "FAIL", findings: [error instanceof Error ? error.message : String(error)] };
     }
@@ -180,7 +185,7 @@ async function ensureExtensionReady(target, options) {
     homeTabs: { before, closed, after },
     ...slotTitle ? { slotTitle } : {},
     ready,
-    reasonCode: ready ? "ready" : after !== 1 ? "tab-count" : "unhealthy",
+    reasonCode: ready ? "ready" : after !== 1 ? "tab-count" : health.errorCode ?? "unhealthy",
     health
   });
 }

package/dist/adapters/extension/runtime-decision.js

@@ -4,8 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import {
   depsCheck,
-  INSTALL_MARKERS,
-  recordDepsBaseline
+  INSTALL_MARKERS
 } from "@farmslot/recipe-harness/runtime/deps-readiness";
 import { recipeHarnessPath, recipeRuntimeDir, recipeWatchLogCandidates } from "../../paths.js";
 const WEBPACK_DIRECT_INPUTS = ["package.json", "yarn.lock", ".yarnrc.yml", ".tool-versions"];
@@ -236,14 +235,13 @@ async function cdpCheck(target, cdpPort, pageMode) {
     return { status: "fail", findings: [error instanceof Error ? error.message : String(error)] };
   }
 }
-function recordReadinessBaseline(target) {
-  recordDepsBaseline(target);
+function recordWebpackBaseline(target) {
   const cache = webpackFingerprint(target);
   writeBaseline(target, "webpack-cache-state.json", cache);
 }
 async function decideExtensionReadiness(target, options = {}) {
   const resolved = path.resolve(target);
-  if (options.record) recordReadinessBaseline(resolved);
+  if (options.record) recordWebpackBaseline(resolved);
   const deps = depsCheck(resolved);
   const webpackCache = webpackCacheCheck(resolved);
   const buildLog = buildLogCheck(resolved, options.watchLog);
@@ -355,6 +353,6 @@ function buildAction(target, clean) {
 export {
   decideExtensionReadiness,
   isExtensionDistStale,
-  recordReadinessBaseline,
+  recordWebpackBaseline,
   runtimeDistCheck
 };

package/dist/adapters/extension/runtime.js

@@ -2,7 +2,12 @@ import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { importRecipeHarnessRuntimeBrowserExtension, importRecipeHarnessRuntimeCdp, recipeRuntimeDir, resolveLocalProtocolRoot, resolveRequiredLocalProtocolRoot, runnerDir } from "../../paths.js";
-const { CdpSession, jsonGet, sleep } = await importRecipeHarnessRuntimeCdp();
+const {
+  CdpSession,
+  jsonGet,
+  probeCdpCompositorInteractivity,
+  sleep
+} = await importRecipeHarnessRuntimeCdp();
 const { extensionIdFromTarget } = await importRecipeHarnessRuntimeBrowserExtension();
 async function prepareExtensionRuntime(options) {
   const projectRoot = path.resolve(options.projectRoot);
@@ -39,6 +44,9 @@ async function assertHealthyExtensionRuntime(options) {
       pageMode: options.pageMode
     });
     if (lastReport.status === "PASS") return lastReport;
+    if (lastReport.errorCode === "UI_COMPOSITOR_SUSPENDED") {
+      throw new Error(formatHealthFailure(lastReport, options.projectRoot));
+    }
     await sleep(500);
   }
   const report = lastReport ?? failReport(options.cdpPort, ["CDP runtime was not probed."], {});
@@ -48,9 +56,14 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
   const findings = [];
   const warnings = [];
   let targets = [];
+  const cdpCallTimeoutMs = options.cdpCallTimeoutMs ?? 5e3;
   try {
-    await jsonGet(`http://127.0.0.1:${cdpPort}/json/version`);
-    const rawTargets = await jsonGet(`http://127.0.0.1:${cdpPort}/json/list`);
+    await jsonGet(`http://127.0.0.1:${cdpPort}/json/version`, {
+      timeoutMs: cdpCallTimeoutMs
+    });
+    const rawTargets = await jsonGet(`http://127.0.0.1:${cdpPort}/json/list`, {
+      timeoutMs: cdpCallTimeoutMs
+    });
     targets = Array.isArray(rawTargets) ? rawTargets : [];
   } catch (error) {
     return failReport(cdpPort, [`CDP is not reachable on port ${cdpPort}: ${messageOf(error)}`], {});
@@ -76,11 +89,57 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
   if (String(target.url ?? "").startsWith("chrome-error://")) {
     findings.push(`Extension target resolved to chrome-error page: ${target.url}`);
   }
-  const session = await CdpSession.connect(target.webSocketDebuggerUrl);
+  let session;
   try {
-    await session.call("Runtime.enable");
-    await session.call("Page.enable");
-    const runtime = await evaluateHealth(session);
+    session = await CdpSession.connect(target.webSocketDebuggerUrl, {
+      timeoutMs: cdpCallTimeoutMs
+    });
+    await boundedCdpCall(session, "Runtime.enable", {}, cdpCallTimeoutMs);
+    await boundedCdpCall(session, "Page.enable", {}, cdpCallTimeoutMs);
+    const compositor = await probeCdpCompositorInteractivity(
+      session,
+      Math.min(1e3, cdpCallTimeoutMs)
+    );
+    if (compositor.status === "suspended") {
+      const userAction = compositorRecoveryAction(projectRoot);
+      return {
+        status: "FAIL",
+        errorCode: "UI_COMPOSITOR_SUSPENDED",
+        userAction,
+        cdpPort,
+        targetUrl: target.url,
+        extensionId: safeExtensionId(target),
+        extensionPageTargets: extensionTargets.length,
+        findings: [
+          `UI_COMPOSITOR_SUSPENDED: the Extension page is reachable over CDP but its render compositor is not advancing (${compositor.reason ?? "unknown reason"}).`
+        ],
+        details: {
+          projectRoot,
+          targetUrls: targets.map((entry) => entry.url).filter(Boolean),
+          compositor
+        }
+      };
+    }
+    if (compositor.status === "not-interactive") {
+      return {
+        status: "FAIL",
+        errorCode: "UI_NOT_INTERACTIVE",
+        userAction: `Inspect the visible Extension page for an overlay or blocked control, then rerun: mm-harness verify --target ${projectRoot}`,
+        cdpPort,
+        targetUrl: target.url,
+        extensionId: safeExtensionId(target),
+        extensionPageTargets: extensionTargets.length,
+        findings: [
+          `UI_NOT_INTERACTIVE: the Extension page is rendering, but its visible controls failed browser hit testing (${compositor.reason ?? "unknown reason"}).`
+        ],
+        details: {
+          projectRoot,
+          targetUrls: targets.map((entry) => entry.url).filter(Boolean),
+          compositor
+        }
+      };
+    }
+    const runtime = await evaluateHealth(session, cdpCallTimeoutMs);
     if (runtime.href && !String(runtime.href).startsWith("chrome-extension://")) {
       findings.push(`Extension page href is not an extension URL: ${runtime.href}`);
     }
@@ -114,21 +173,48 @@ async function checkExtensionRuntimeHealth(projectRoot, cdpPort, options = {}) {
         runtime
       }
     };
+  } catch (error) {
+    return failReport(
+      cdpPort,
+      [`Extension page CDP probe failed: ${messageOf(error)}`],
+      {
+        targetUrl: target.url,
+        targetUrls: targets.map((entry) => entry.url).filter(Boolean)
+      },
+      extensionTargets.length
+    );
   } finally {
-    session.close();
+    session?.close();
   }
 }
-function failReport(cdpPort, findings, details) {
+function failReport(cdpPort, findings, details, extensionPageTargets = 0) {
   return {
     status: "FAIL",
     cdpPort,
-    extensionPageTargets: 0,
+    extensionPageTargets,
     findings,
     details
   };
 }
-async function evaluateHealth(session) {
-  const result = await session.call("Runtime.evaluate", {
+async function boundedCdpCall(session, method, params, timeoutMs) {
+  let timer;
+  try {
+    return await Promise.race([
+      session.call(method, params),
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`${method} timed out after ${timeoutMs}ms.`)),
+          timeoutMs
+        );
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+async function evaluateHealth(session, timeoutMs) {
+  const backgroundProbeTimeoutMs = extensionBackgroundProbeTimeoutMs(timeoutMs);
+  const result = await boundedCdpCall(session, "Runtime.evaluate", {
     expression: `(() => {
       const hooks = globalThis.stateHooks || {};
       const bodyText = document.body?.innerText || '';
@@ -177,13 +263,13 @@ async function evaluateHealth(session) {
           hasPerpsStreamManager: typeof hooks.getPerpsStreamManager === 'function',
           backgroundUnresponsive: bodyText.includes('Background connection unresponsive') || bodyText.includes('MetaMask had trouble starting'),
           backgroundProbeOk: false,
-          backgroundProbeError: 'perpsGetAccountState timed out after 5000ms',
-        }), 5000)),
+          backgroundProbeError: 'perpsGetAccountState timed out after ${backgroundProbeTimeoutMs}ms',
+        }), ${backgroundProbeTimeoutMs})),
       ]);
     })()`,
     awaitPromise: true,
     returnByValue: true
-  });
+  }, timeoutMs);
   if (result.exceptionDetails) {
     throw new Error(
       result.exceptionDetails.exception?.description ?? result.exceptionDetails.text ?? "Extension runtime health evaluation failed."
@@ -191,15 +277,24 @@ async function evaluateHealth(session) {
   }
   return result.result?.value ?? {};
 }
+function extensionBackgroundProbeTimeoutMs(cdpCallTimeoutMs) {
+  return Math.max(1, Math.floor(cdpCallTimeoutMs * 0.8));
+}
 function formatHealthFailure(report, projectRoot) {
   return [
     `Extension runtime health check failed for ${projectRoot} on CDP port ${report.cdpPort}.`,
     ...report.findings.map((finding) => `- ${finding}`),
-    "Use the host-managed validation launcher, for example:",
-    `  mm-harness run <recipe.json> --adapter extension --target ${projectRoot} --slot <slot-id> --cdp-port ${report.cdpPort} --launch-existing-dist --artifacts-dir <artifacts-dir>`,
+    ...report.userAction ? ["Next:", `  ${report.userAction}`] : [
+      "Use the host-managed validation launcher, for example:",
+      `  mm-harness run <recipe.json> --adapter extension --target ${projectRoot} --slot <slot-id> --cdp-port ${report.cdpPort} --launch-existing-dist --artifacts-dir <artifacts-dir>`
+    ],
     `Health details: ${JSON.stringify(report.details)}`
   ].join("\n");
 }
+function compositorRecoveryAction(projectRoot) {
+  const recovery = `mm-harness launch --verify --target ${JSON.stringify(projectRoot)}`;
+  return process.platform === "darwin" ? `Unlock the macOS session, then rerun: ${recovery}` : `Restore an active display compositor, then rerun: ${recovery}`;
+}
 function resolveCdpPort(rawPort, slot) {
   const raw = rawPort ?? process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT ?? slot?.cdpPort;
   const port = Number(raw);
@@ -329,6 +424,8 @@ function messageOf(error) {
 export {
   assertHealthyExtensionRuntime,
   checkExtensionRuntimeHealth,
+  compositorRecoveryAction,
+  extensionBackgroundProbeTimeoutMs,
   formatHealthFailure,
   prepareExtensionRuntime
 };

package/dist/adapters/mobile/prepare.js

@@ -32,6 +32,7 @@ async function prepareMobile(target, opts = {}) {
   const platform = opts.platform ?? "ios";
   const preflightMode = opts.preflightMode ?? "fast";
   const clearMetro = opts.clearMetro ?? false;
+  const restartApp = opts.restartApp ?? false;
   const report = await decideMobileReadiness(target, {
     watcherPort: opts.watcherPort,
     metroLog: opts.metroLog,
@@ -49,6 +50,16 @@ async function prepareMobile(target, opts = {}) {
     return { status: EXIT.runtime, output: msg };
   }
   if (report.decision === "ready") {
+    if (restartApp) {
+      const launch2 = await dispatchActionSequence(
+        withAppRestart(launchActions(path.resolve(target)), true),
+        target,
+        platform,
+        json,
+        preflightMode
+      );
+      return launch2.status === 0 ? startMobileConsoleForwarder(target, platform, json) : launch2;
+    }
     const surface = await ensureMobileHumanSurface(target, platform, json);
     if (surface.status !== 0) return surface;
     const confirm = await dispatchAction(
@@ -66,7 +77,7 @@ async function prepareMobile(target, opts = {}) {
       );
     }
     const launch = await dispatchActionSequence(
-      launchActions(path.resolve(target)),
+      withAppRestart(launchActions(path.resolve(target)), restartApp),
       target,
       platform,
       json,
@@ -80,9 +91,12 @@ async function prepareMobile(target, opts = {}) {
 `);
     return { status: EXIT.runtime, output: msg };
   }
-  const actions = clearMetro ? report.actions.map(
-    (a) => a.id === "start-metro" && !a.argv?.includes("--clear") ? { ...a, argv: [...a.argv ?? [], "--clear"] } : a
-  ) : report.actions;
+  const actions = withAppRestart(
+    clearMetro ? report.actions.map(
+      (a) => a.id === "start-metro" && !a.argv?.includes("--clear") ? { ...a, argv: [...a.argv ?? [], "--clear"] } : a
+    ) : report.actions,
+    restartApp
+  );
   const actionResult = await dispatchActionSequence(actions, target, platform, json, preflightMode);
   if (actionResult.status !== 0) return actionResult;
   if (report.decision === "install" && !process.env["RECIPE_UP_INSTALL_ATTEMPTED"]) {
@@ -109,7 +123,13 @@ async function prepareMobile(target, opts = {}) {
         break;
       }
       case "launch": {
-        const result = await dispatchActionSequence(postInstall.actions, target, platform, json, preflightMode);
+        const result = await dispatchActionSequence(
+          withAppRestart(postInstall.actions, restartApp),
+          target,
+          platform,
+          json,
+          preflightMode
+        );
         if (result.status !== 0) return result;
         break;
       }
@@ -136,6 +156,12 @@ function ensureMobileHumanSurface(target, platform, json) {
   if (platform !== "ios") return Promise.resolve({ status: 0, output: "" });
   return dispatchAction({ id: "ensure-device-ui", cwd: target }, target, platform, json);
 }
+function withAppRestart(actions, restartApp) {
+  if (!restartApp) return actions;
+  return actions.map(
+    (action) => action.id === "launch-mobile-runtime" ? { ...action, argv: [...action.argv ?? [], "--restart"] } : action
+  );
+}
 async function dispatchActionSequence(requestedActions, target, platform, json, preflightMode) {
   const resolved = path.resolve(target);
   const actions = applyMobileMetroEnvPolicy(resolved, requestedActions);
@@ -187,7 +213,15 @@ async function dispatchAction(action, target, platform, json, preflightMode = "f
       const leaf = path.join(runnerDir, "adapters/mobile/open-device.sh");
       return spawnScriptStreaming(
         leaf,
-        ["--platform", platform, "--target", cwd, "--preflight-mode", preflightMode],
+        [
+          "--platform",
+          platform,
+          "--target",
+          cwd,
+          "--preflight-mode",
+          preflightMode,
+          ...action.argv ?? []
+        ],
         target,
         POD_PROBE_ENV
       );

package/dist/command-contract.js

@@ -58,8 +58,8 @@ const PUBLIC_COMMAND_CONTRACTS = {
     })
   },
   checklist: {
-    usage: "mm-harness checklist mark <task-dir> <step> [options]",
-    options: options(HELP, {
+    usage: "mm-harness checklist <mark <task-dir> <step> | closeout <task-dir>> [options]",
+    options: options(HELP, JSON, {
       "--mark-last": bool(),
       "--already-fixed": bool(),
       "--no-self-review": bool(),
@@ -67,10 +67,14 @@ const PUBLIC_COMMAND_CONTRACTS = {
       "--skip-checklist": bool(),
       "--reason": value(),
       "--checklist": value(),
-      "--signal": value()
+      "--signal": value(),
+      "--share": bool(),
+      "--config": value(),
+      "--destination": value(),
+      "--metadata": value()
     }),
     positionals: [
-      { label: "action", choices: ["mark"] },
+      { label: "action", choices: ["mark", "closeout"] },
       { label: "task-dir" },
       {
         label: "step",
@@ -82,7 +86,7 @@ const PUBLIC_COMMAND_CONTRACTS = {
         validDescription: "start|complete|no-change|blocked|a positive numeric step"
       }
     ],
-    minimumPositionals: 3
+    minimumPositionals: 2
   },
   actions: {
     options: options(HELP, JSON, TARGET, ADAPTER, ADAPTER_OR_MOBILE_PLATFORM, {
@@ -307,6 +311,55 @@ function validatePublicInvocation(argv, examples = {}) {
     }
   }
   if (seenOptions.has("--help") || seenOptions.has("-h")) return null;
+  if (name === "checklist") {
+    const action = positionals[0];
+    const markOnly = [
+      "--mark-last",
+      "--already-fixed",
+      "--no-self-review",
+      "--skip-learnings",
+      "--skip-checklist",
+      "--reason",
+      "--checklist",
+      "--signal"
+    ];
+    const closeoutOnly = [
+      "--json",
+      "--share",
+      "--config",
+      "--destination",
+      "--metadata"
+    ];
+    const invalidOption = (action === "mark" ? closeoutOnly : markOnly).find(
+      (option) => seenOptions.has(option)
+    );
+    if (invalidOption && (action === "mark" || action === "closeout")) {
+      return usageFailure(
+        "CLI_UNKNOWN_OPTION",
+        name,
+        `${invalidOption} is not valid with checklist ${action}.`,
+        contract,
+        examples
+      );
+    }
+    if (action === "mark" && positionals.length < 3) {
+      return missingPositionalFailure(
+        name,
+        "checklist mark requires <step>.",
+        contract,
+        examples
+      );
+    }
+    if (action === "closeout" && positionals.length > 2) {
+      return usageFailure(
+        "CLI_EXCESS_POSITIONAL",
+        name,
+        `unexpected positional '${positionals[2]}'; checklist closeout accepts only <task-dir>.`,
+        contract,
+        examples
+      );
+    }
+  }
   if (contract.leadingPositionals && !contract.requiredUnless?.some((option) => seenOptions.has(option)) && tokens.slice(0, contract.leadingPositionals).some((argument) => !argument || argument.startsWith("-"))) {
     const missing = contract.positionals?.[0]?.label ?? "argument";
     return missingPositionalFailure(name, `${name} requires <${missing}> first.`, contract, examples);