@deeeed/metamask-harness 0.57.0 → 0.59.0

package/dist/adapters/mobile/verify.js

@@ -0,0 +1,549 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { readRuntimeContextField } from "../../harness.js";
+import { recipeHarnessPath, recipeHarnessRoot, recipeRuntimeDir, runnerDir } from "../../paths.js";
+const USAGE = "Usage: mm-harness verify --adapter mobile -- [--target <metamask-mobile>] [--artifacts-dir <dir>] [--static-only] [--platform ios|android] [--preflight-mode fast|auto|default|rebuild-native|clean] [--no-auto-start]";
+const ENV_FILES = [".js.env", ".env", ".env.local"];
+const PREFLIGHT_MODES = ["fast", "auto", "default", "rebuild-native", "clean"];
+const AUTO_START_TRUE = ["1", "true", "TRUE", "True", "yes", "YES", "Yes", "on", "ON", "On"];
+const AUTO_START_FALSE = ["0", "false", "FALSE", "False", "no", "NO", "No", "off", "OFF", "Off", ""];
+const AUTO_START_REFUSAL = "Mobile auto-start is not allowed from product-local scripts. Start or prepare the app through the runner/slot runtime, then rerun verify with --no-auto-start.";
+const EVM_READINESS_EXPRESSION = "(async function(){try{var engine=globalThis.Engine;var controller=engine&&engine.context&&engine.context.NetworkController;if(!controller||typeof controller.getSelectedNetworkClient!=='function')throw new Error('NetworkController selected client is unavailable');var client=controller.getSelectedNetworkClient();if(!client||!client.provider||typeof client.provider.request!=='function')throw new Error('selected EVM provider is unavailable');var result=await client.provider.request({method:'eth_blockNumber'});if(typeof result!=='string'||!/^0x[0-9a-f]+$/i.test(result))throw new Error('eth_blockNumber returned an invalid result');return {ok:true,result:result};}catch(error){return {ok:false,error:error&&(error.message||String(error))};}})()";
+const STATUS_SMOKE_RECIPE = `{
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
+  "title": "Mobile runner status smoke",
+  "description": "Checks that the installed runner can read Mobile app status before live verification.",
+  "workflow": {
+    "entry": "status",
+    "nodes": {
+      "status": { "action": "app.status", "intent": "Read Mobile app status through the runner-owned bridge", "next": "done" },
+      "done": { "action": "end", "status": "pass" }
+    }
+  }
+}
+`;
+const LIVE_SMOKE_RECIPE = `{
+  "$schema": "https://farmslot.io/schemas/recipe-v1.schema.json",
+  "title": "Mobile v1 runner live bridge smoke",
+  "description": "Verifies the installed MetaMask runner can read the React Native debug bridge without mutating wallet state.",
+  "workflow": {
+    "entry": "status",
+    "nodes": {
+      "status": { "action": "app.status", "intent": "Read Mobile app status through the v1 runner", "next": "cdp-probe" },
+      "cdp-probe": { "action": "cdp.target", "intent": "Verify the React Native debug bridge target is reachable", "require_reachable": true, "timeout_ms": 60000, "cdp_timeout_ms": 60000, "next": "done" },
+      "done": { "action": "end", "status": "pass" }
+    }
+  }
+}
+`;
+function parseMobileVerifyArgs(argv, env = process.env) {
+  let target = process.cwd();
+  let artifactsDir;
+  let staticOnly = false;
+  let platform = env.RECIPE_HARNESS_PLATFORM || env.PLATFORM || "ios";
+  let preflightMode = env.RECIPE_HARNESS_MOBILE_PREFLIGHT_MODE || "fast";
+  let autoStart = env.RECIPE_HARNESS_MOBILE_AUTO_START ?? "false";
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const needsValue = () => {
+      if (i + 1 >= argv.length) return void 0;
+      i += 1;
+      return argv[i];
+    };
+    switch (arg) {
+      case "--target": {
+        const value = needsValue();
+        if (value === void 0) return { kind: "error", message: "Missing value for --target", exitCode: 2 };
+        target = value;
+        break;
+      }
+      case "--artifacts-dir": {
+        const value = needsValue();
+        if (value === void 0) return { kind: "error", message: "Missing value for --artifacts-dir", exitCode: 2 };
+        artifactsDir = value;
+        break;
+      }
+      case "--static-only":
+        staticOnly = true;
+        break;
+      case "--platform": {
+        const value = needsValue();
+        if (value === void 0) return { kind: "error", message: "Missing value for --platform", exitCode: 2 };
+        platform = value;
+        break;
+      }
+      case "--preflight-mode": {
+        const value = needsValue();
+        if (value === void 0) return { kind: "error", message: "Missing value for --preflight-mode", exitCode: 2 };
+        preflightMode = value;
+        break;
+      }
+      case "--auto-start":
+        autoStart = "true";
+        break;
+      case "--no-auto-start":
+        autoStart = "false";
+        break;
+      case "-h":
+      case "--help":
+        return { kind: "help", usage: USAGE };
+      default:
+        return { kind: "error", message: `Unknown arg: ${arg}`, exitCode: 2 };
+    }
+  }
+  if (!PREFLIGHT_MODES.includes(preflightMode)) {
+    return { kind: "error", message: `Unknown --preflight-mode: ${preflightMode}`, exitCode: 2 };
+  }
+  if (platform !== "ios" && platform !== "android") {
+    return { kind: "error", message: `Unknown --platform: ${platform} (expected ios or android)`, exitCode: 2 };
+  }
+  if (!AUTO_START_TRUE.includes(autoStart) && !AUTO_START_FALSE.includes(autoStart)) {
+    return { kind: "error", message: `Unknown RECIPE_HARNESS_MOBILE_AUTO_START value: ${autoStart}`, exitCode: 2 };
+  }
+  return {
+    kind: "options",
+    options: {
+      target,
+      artifactsDir,
+      staticOnly,
+      platform,
+      preflightMode,
+      autoStart: AUTO_START_TRUE.includes(autoStart)
+    }
+  };
+}
+function isNumericWatcherPort(port) {
+  return port.length > 0 && /^[0-9]+$/u.test(port);
+}
+function classifyMobileRuntimeOwner(portHolder, startedByVerify, liveSmokeStatus) {
+  if (!portHolder) return "static-only";
+  if (startedByVerify) return "harness-owned";
+  if (!portHolder.listening) return "none";
+  return liveSmokeStatus === "pass" ? "compatible-external-or-harness" : "incompatible-external-or-stale";
+}
+function buildMobileVerifySummary(input) {
+  const liveRuntimeCheck = input.checks.find((check) => check.name === "runner v1 live bridge smoke");
+  const runtimeOwner = classifyMobileRuntimeOwner(input.portHolder, input.startedByVerify, liveRuntimeCheck?.status);
+  return {
+    adapter: "mobile",
+    status: input.status,
+    runtimeClassification: {
+      runtimeOwner,
+      recipeControllable: liveRuntimeCheck?.status === "pass",
+      startedByVerify: input.startedByVerify
+    },
+    cleanupOwnership: {
+      mayStop: input.startedByVerify,
+      reason: input.startedByVerify ? "verify launched the runtime through harness preflight" : "verify did not launch this runtime; do not stop human-owned or pre-existing processes automatically"
+    },
+    gitStatus: input.gitStatus,
+    runtimePolicy: {
+      preflightMode: input.preflightMode,
+      nativeBuildPolicy: input.preflightMode === "fast" ? "verify does not start product-local Mobile scripts; start/reuse a runner-owned or slot-owned runtime before live proof" : "verify did not start product-local Mobile scripts"
+    },
+    fixtureStatus: input.fixtureStatus,
+    portHolder: input.portHolder,
+    runtimeNotes: input.runtimeNotes,
+    checks: input.checks,
+    generatedAt: input.generatedAt
+  };
+}
+function resolveWatcherPort(target, env = process.env) {
+  const explicit = env.WATCHER_PORT || "";
+  if (explicit) return explicit;
+  for (const file of ENV_FILES) {
+    const full = path.join(target, file);
+    if (!fs.existsSync(full)) continue;
+    const match = fs.readFileSync(full, "utf8").match(/^\s*(?:export\s+)?WATCHER_PORT=(["']?)([0-9]+)\1/mu);
+    if (match) return match[2];
+  }
+  return "8081";
+}
+function resolveJsEnvValue(target, name, env = process.env) {
+  const fromProcess = env[name] || "";
+  if (fromProcess) return fromProcess;
+  const pattern = new RegExp(`^\\s*(?:export\\s+)?${name}=(["']?)([^"'\\n]+)\\1`, "mu");
+  for (const file of ENV_FILES) {
+    const full = path.join(target, file);
+    if (!fs.existsSync(full)) continue;
+    const match = fs.readFileSync(full, "utf8").match(pattern);
+    if (match) return match[2];
+  }
+  return "";
+}
+function runtimeContextValue(target, names) {
+  const file = path.join(target, recipeRuntimeDir(), "agentic-runtime.json");
+  for (const name of names) {
+    const value = readRuntimeContextField(file, name);
+    if (value !== void 0 && value !== "") return value;
+  }
+  return "";
+}
+function mobileDeviceTarget(target, platform, env) {
+  if (platform === "android") {
+    return env.ADB_SERIAL || env.ANDROID_SERIAL || env.ANDROID_DEVICE || runtimeContextValue(target, ["adbSerial", "androidDevice", "device"]);
+  }
+  return env.SIM_UDID || env.IOS_SIMULATOR || runtimeContextValue(target, ["simulator", "iosSimulator", "device"]);
+}
+function mobileFixtureStatus(target) {
+  const runtimeDir = recipeRuntimeDir();
+  const fixture = path.join(target, runtimeDir, "wallet-fixture.json");
+  if (!fs.existsSync(fixture)) {
+    return {
+      status: "MISSING_FIXTURES",
+      message: `No wallet fixture found. This run may spend time repairing wallet/perps state manually. For a clean isolated sandbox, create ${runtimeDir}/wallet-fixture.json.`,
+      setupCommand: `mkdir -p ${runtimeDir} && edit ${runtimeDir}/wallet-fixture.json with password + accounts`
+    };
+  }
+  const fixtureRaw = fs.readFileSync(fixture);
+  let valid = false;
+  let accountCount = null;
+  let hasPassword = false;
+  try {
+    const parsed = JSON.parse(fixtureRaw.toString("utf8"));
+    valid = true;
+    accountCount = Array.isArray(parsed.accounts) ? parsed.accounts.length : 0;
+    hasPassword = typeof parsed.password === "string" && parsed.password.length > 0;
+  } catch {
+    valid = false;
+  }
+  const relative = path.relative(target, fixture);
+  const ready = valid && hasPassword && (accountCount ?? 0) > 0;
+  return {
+    status: ready ? "READY" : "STALE_OR_INVALID",
+    path: relative,
+    sha256: crypto.createHash("sha256").update(fixtureRaw).digest("hex"),
+    modifiedAt: fs.statSync(fixture).mtime.toISOString(),
+    accountCount,
+    hasPassword,
+    message: ready ? `Fixture status: READY (${relative}, accounts=${accountCount}).` : `Fixture status: STALE_OR_INVALID (${relative}). Validate password/accounts before relying on a clean sandbox.`
+  };
+}
+function capture(command, args) {
+  try {
+    return execFileSync(command, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return "";
+  }
+}
+function mobilePortHolder(port) {
+  const pid = capture("lsof", [`-iTCP:${port}`, "-sTCP:LISTEN", "-t"]).split("\n")[0] ?? "";
+  const command = /^[0-9]+$/u.test(pid) ? capture("ps", ["-p", pid, "-o", "command="]) : "";
+  return {
+    port,
+    listening: Boolean(pid),
+    pid: pid || null,
+    command: command || null,
+    metroStatusReachable: null,
+    metroHttpProbeSkipped: true,
+    note: "HTTP /status probing is skipped during live verify because the React Native bridge is the authoritative readiness path for Mobile."
+  };
+}
+function spawnToLog(logPath, command, args, options = {}) {
+  fs.mkdirSync(path.dirname(logPath), { recursive: true });
+  const fd = fs.openSync(logPath, "w");
+  try {
+    const result = spawnSync(command, args, {
+      cwd: options.cwd,
+      env: options.env ?? process.env,
+      stdio: ["ignore", fd, fd],
+      ...options.timeoutMs === void 0 ? {} : { timeout: options.timeoutMs }
+    });
+    if (result.error) {
+      const timedOut = result.error.code === "ETIMEDOUT";
+      fs.writeSync(
+        fd,
+        timedOut ? `Timed out after ${(options.timeoutMs ?? 0) / 1e3}s: ${[command, ...args].join(" ")}
+` : `${result.error.message}
+`
+      );
+      return timedOut ? 124 : 127;
+    }
+    return result.status ?? 1;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+function readJsonFile(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function gitStatusSummary(target, harnessRootExclude) {
+  const runGit = (args) => {
+    try {
+      return execFileSync("git", ["-C", target, ...args], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"]
+      }).trim();
+    } catch {
+      return null;
+    }
+  };
+  const statusShort = runGit(["status", "--short", "--", ".", `:(exclude)${harnessRootExclude}`]);
+  const dirty = statusShort ? statusShort.split("\n").filter(Boolean) : [];
+  return {
+    branch: runGit(["branch", "--show-current"]),
+    head: runGit(["rev-parse", "--short", "HEAD"]),
+    dirtyCount: dirty.length,
+    dirtyPreview: dirty.slice(0, 25)
+  };
+}
+function utcStamp(date) {
+  return `${date.toISOString().replace(/[-:]/gu, "").split(".")[0]}Z`;
+}
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+const defaultIo = {
+  out: (line) => process.stdout.write(`${line}
+`),
+  err: (line) => process.stderr.write(`${line}
+`)
+};
+async function runMobileVerify(argv, io = defaultIo) {
+  const parsed = parseMobileVerifyArgs(argv);
+  if (parsed.kind === "help") {
+    io.out(parsed.usage);
+    return 0;
+  }
+  if (parsed.kind === "error") {
+    io.err(parsed.message);
+    return parsed.exitCode;
+  }
+  const { staticOnly, platform, preflightMode, autoStart } = parsed.options;
+  const target = path.resolve(parsed.options.target);
+  if (!fs.existsSync(target)) {
+    io.err(`Refusing mobile verify: target checkout does not exist: ${target}`);
+    io.err("  Next: pass --target <metamask-mobile checkout>");
+    return 1;
+  }
+  const harnessRoot = recipeHarnessRoot();
+  const harnessRel = `${harnessRoot}/mobile`;
+  const harnessDir = recipeHarnessPath(target, "mobile");
+  const runnerBin = path.join(harnessDir, "runner/bin/mm-harness");
+  const artifacts = parsed.options.artifactsDir ? path.resolve(parsed.options.artifactsDir) : path.join(harnessDir, "verify", utcStamp(/* @__PURE__ */ new Date()));
+  fs.mkdirSync(path.join(artifacts, "logs"), { recursive: true });
+  const notesPath = path.join(artifacts, "logs/runtime-notes.txt");
+  const addNote = (note) => {
+    fs.appendFileSync(notesPath, `${note}
+`);
+  };
+  let status = "pass";
+  const checks = [];
+  const checkFile = (rel) => {
+    const ok = fs.existsSync(path.join(target, rel));
+    checks.push({ name: rel, status: ok ? "pass" : "fail" });
+    if (!ok) status = "fail";
+  };
+  const checkContains = (name, file, needle) => {
+    let ok = false;
+    try {
+      ok = fs.readFileSync(path.join(target, file), "utf8").includes(needle);
+    } catch {
+      ok = false;
+    }
+    checks.push({ name, status: ok ? "pass" : "fail" });
+    if (!ok) status = "fail";
+  };
+  checkFile(`${harnessRel}/manifest.json`);
+  checkFile(`${harnessRel}/action-manifest.json`);
+  checkFile(`${harnessRel}/runner/bin/mm-harness`);
+  checkFile("package.json");
+  checkFile("app/dev-tools/AgenticService/AgenticService.ts");
+  checkContains("NavigationService agentic bridge", "app/core/NavigationService/NavigationService.ts", "AgenticService.install");
+  checkContains("App AgentStepHud", "app/components/Nav/App/App.tsx", "AgentStepHud");
+  let fixtureStatus = null;
+  let portHolder = null;
+  if (!staticOnly) {
+    const port = resolveWatcherPort(target);
+    if (!isNumericWatcherPort(port)) {
+      io.err(`Refusing mobile verify: resolved watcher port is not numeric: '${port}' (check WATCHER_PORT)`);
+      return 2;
+    }
+    let deviceTarget = mobileDeviceTarget(target, platform, process.env);
+    if (!deviceTarget) {
+      deviceTarget = platform === "android" ? resolveJsEnvValue(target, "ADB_SERIAL") || resolveJsEnvValue(target, "ANDROID_DEVICE") : resolveJsEnvValue(target, "IOS_SIMULATOR");
+    }
+    const deviceArgs = deviceTarget ? ["--device", deviceTarget] : [];
+    const statusSmokeRecipe = path.join(artifacts, "mobile-status-smoke.recipe.json");
+    const precheckLog = path.join(artifacts, "logs/app-status-precheck.log");
+    let liveRuntimeOk = false;
+    for (let attempt = 1; attempt <= 5; attempt += 1) {
+      fs.writeFileSync(statusSmokeRecipe, STATUS_SMOKE_RECIPE);
+      const code = spawnToLog(precheckLog, runnerBin, [
+        "run",
+        statusSmokeRecipe,
+        "--adapter",
+        "mobile",
+        "--target",
+        target,
+        ...deviceArgs,
+        "--watcher-port",
+        port,
+        "--artifacts-dir",
+        path.join(artifacts, "runner-status-smoke"),
+        "--json"
+      ], { cwd: target });
+      if (code === 0) {
+        liveRuntimeOk = true;
+        break;
+      }
+      const deviceNotFound = /"code"[ \t]*:[ \t]*"DEVICE_NOT_FOUND"/u.test(
+        fs.readFileSync(precheckLog, "utf8")
+      );
+      if (attempt < 5 && deviceNotFound) {
+        io.err(`Waiting for Mobile device discovery (${attempt}/5): ${deviceTarget || "configured target"}`);
+        await sleep(1e3);
+        continue;
+      }
+      break;
+    }
+    if (!liveRuntimeOk && autoStart) io.err(AUTO_START_REFUSAL);
+    checks.push(liveRuntimeOk ? { name: "mobile runtime controllable precheck", status: "pass" } : { name: "mobile runtime controllable precheck", status: "fail", detail: "see logs/app-status-precheck.log" });
+    if (!liveRuntimeOk) status = "fail";
+    fixtureStatus = mobileFixtureStatus(target);
+    fs.writeFileSync(path.join(artifacts, "logs/fixture-status.json"), `${JSON.stringify(fixtureStatus)}
+`);
+    const fixtureCheck = {
+      name: "fixture status",
+      status: fixtureStatus.status === "READY" ? "pass" : "warn",
+      detail: fixtureStatus.path || fixtureStatus.status || "",
+      message: fixtureStatus.message || fixtureStatus.status
+    };
+    io.err(fixtureCheck.message);
+    addNote(fixtureCheck.message);
+    checks.push(fixtureCheck);
+    portHolder = mobilePortHolder(port);
+    fs.writeFileSync(path.join(artifacts, "logs/port-holder.json"), `${JSON.stringify(portHolder)}
+`);
+    if (status !== "fail" && portHolder.listening) {
+      const waiter = path.join(runnerDir, "adapters/mobile/wait-for-bridge.sh");
+      if (!fs.existsSync(waiter)) {
+        addNote("Mobile bridge settle skipped: wait-for-bridge.sh not found under the runner adapters; reinstall the runner.");
+      } else {
+        const waiterCode = spawnToLog(
+          path.join(artifacts, "logs/wait-for-bridge.log"),
+          "bash",
+          [waiter, "--target", target, "--port", port, "--platform", platform],
+          {
+            env: {
+              ...process.env,
+              MOBILE_BRIDGE_READY_TIMEOUT_MS: process.env.MOBILE_BRIDGE_READY_TIMEOUT_MS || "90000",
+              MOBILE_BRIDGE_UNRESPONSIVE_GRACE_MS: process.env.MOBILE_BRIDGE_UNRESPONSIVE_GRACE_MS || "90000"
+            }
+          }
+        );
+        addNote(waiterCode === 0 ? "Mobile bridge settled before the live smoke (logs/wait-for-bridge.log)." : `Mobile bridge settle did not complete (waiter exit ${waiterCode}); running the live smoke anyway (logs/wait-for-bridge.log).`);
+      }
+    }
+    const liveSmokeRecipe = path.join(artifacts, "mobile-v1-live-smoke.recipe.json");
+    fs.writeFileSync(liveSmokeRecipe, LIVE_SMOKE_RECIPE);
+    const iosSimulatorResolved = resolveJsEnvValue(target, "IOS_SIMULATOR");
+    const adbSerialResolved = resolveJsEnvValue(target, "ADB_SERIAL");
+    const liveSmokeCode = spawnToLog(
+      path.join(artifacts, "logs/runner-live-smoke.log"),
+      runnerBin,
+      [
+        "run",
+        liveSmokeRecipe,
+        "--adapter",
+        "mobile",
+        "--target",
+        target,
+        ...deviceArgs,
+        "--watcher-port",
+        port,
+        "--artifacts-dir",
+        path.join(artifacts, "runner-live-smoke"),
+        "--json"
+      ],
+      {
+        cwd: target,
+        env: {
+          ...process.env,
+          METAMASK_RECIPE_AUTO_HUD: "0",
+          IOS_SIMULATOR: process.env.IOS_SIMULATOR || iosSimulatorResolved,
+          ADB_SERIAL: process.env.ADB_SERIAL || adbSerialResolved,
+          ANDROID_SERIAL: process.env.ANDROID_SERIAL || adbSerialResolved
+        }
+      }
+    );
+    if (liveSmokeCode === 0) {
+      checks.push({ name: "runner v1 live bridge smoke", status: "pass" });
+    } else {
+      checks.push({ name: "runner v1 live bridge smoke", status: "fail", detail: "see logs/runner-live-smoke.log" });
+      addNote("Runner v1 live bridge smoke failed; inspect logs/runner-live-smoke.log and runner-live-smoke/trace.json.");
+      status = "fail";
+    }
+    const evmLog = path.join(artifacts, "logs/evm-rpc-readiness.log");
+    const bridge = path.join(harnessDir, "bridge-runtime/cdp-bridge.cjs");
+    let evmOk = false;
+    if (!fs.existsSync(bridge)) {
+      fs.writeFileSync(evmLog, `Mobile bridge is missing at ${bridge}
+`);
+    } else {
+      const evmCode = spawnToLog(evmLog, process.execPath, [bridge, "eval-async", EVM_READINESS_EXPRESSION], {
+        timeoutMs: 25e3,
+        env: {
+          ...process.env,
+          APP_ROOT: target,
+          WATCHER_PORT: port,
+          IOS_SIMULATOR: process.env.IOS_SIMULATOR || iosSimulatorResolved,
+          ADB_SERIAL: process.env.ADB_SERIAL || adbSerialResolved,
+          ANDROID_SERIAL: process.env.ANDROID_SERIAL || adbSerialResolved
+        }
+      });
+      evmOk = evmCode === 0 && readJsonFile(evmLog)?.ok === true;
+    }
+    if (evmOk) {
+      checks.push({ name: "live EVM RPC readiness", status: "pass" });
+    } else {
+      checks.push({ name: "live EVM RPC readiness", status: "fail", detail: "see logs/evm-rpc-readiness.log" });
+      addNote(`EVM RPC readiness probe failed. Infura configured \u2260 RPC reachable. Next: confirm ${target}/.js.env has a real MM_INFURA_PROJECT_ID (not 00000000000), then rerun mm-harness launch ${platform} --verify --target '${target}'.`);
+      status = "fail";
+    }
+  }
+  const summary = buildMobileVerifySummary({
+    status,
+    preflightMode,
+    startedByVerify: fs.existsSync(path.join(artifacts, "logs/harness-started-runtime")),
+    fixtureStatus: readJsonFile(path.join(artifacts, "logs/fixture-status.json")),
+    portHolder: readJsonFile(path.join(artifacts, "logs/port-holder.json")),
+    runtimeNotes: readRuntimeNotes(notesPath),
+    checks,
+    gitStatus: gitStatusSummary(target, harnessRoot),
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+  fs.writeFileSync(path.join(artifacts, "summary.json"), `${JSON.stringify(summary, null, 2)}
+`);
+  fs.writeFileSync(
+    path.join(artifacts, "artifact-manifest.json"),
+    `${JSON.stringify({ artifacts: fs.readdirSync(artifacts).map((name) => ({ path: name })) }, null, 2)}
+`
+  );
+  io.out(`Mobile harness verify ${status}: ${path.join(artifacts, "summary.json")}`);
+  return status === "pass" ? 0 : 1;
+}
+function readRuntimeNotes(notesPath) {
+  try {
+    return fs.readFileSync(notesPath, "utf8").trim().split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+export {
+  buildMobileVerifySummary,
+  classifyMobileRuntimeOwner,
+  isNumericWatcherPort,
+  parseMobileVerifyArgs,
+  resolveJsEnvValue,
+  resolveWatcherPort,
+  runMobileVerify
+};

package/dist/adapters/resolve-slot-ports.js

@@ -3,6 +3,7 @@ import {
   formatExtensionIdentityPorts,
   formatExtensionSlotPorts,
   inferSlotSuffix,
+  poolFilesForHost,
   realRepoPath,
   resolveDefaultExtensionPorts,
   resolveExtensionRuntimeContext,
@@ -17,6 +18,7 @@ export {
   formatExtensionSlotPorts,
   formatKvLines,
   inferSlotSuffix,
+  poolFilesForHost,
   realRepoPath,
   resolveDefaultExtensionPorts,
   resolveExtensionRuntimeContext,

package/dist/cli.js

@@ -103,7 +103,7 @@ async function main(argv) {
   if (command === "completion-candidates") return handleCompletionCandidates(argv.slice(1));
   if (command === "provision") return handleProvision(parseArgs(argv.slice(1), command));
   if (OVERLAY_COMMANDS.includes(command)) {
-    if (command === "verify") {
+    if (command === "verify" && process.env.MM_HARNESS_SKIP_OVERLAY_ENSURE !== "1") {
       try {
         const { options } = parseArgs(argv.slice(1), command);
         const target = targetPath(options);

package/dist/commands/run-engine.js

@@ -89,7 +89,7 @@ async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManif
       preExecute
     );
     if (preExecuteDrift.length > 0) {
-      const provenancePath2 = writeExecutionProvenance(
+      const provenancePath2 = await writeExecutionProvenance(
         absoluteArtifactsDir,
         provenanceSnapshots,
         preExecuteDrift
@@ -134,7 +134,7 @@ async function runRecipe(adapter, recipe, artifactsDir, projectRoot, actionManif
     const end = await captureExecutionProvenance(provenanceInput, "end");
     provenanceSnapshots.push(end);
     const endDrift = executionProvenanceDrift(provenanceSnapshots[0], end);
-    const provenancePath = writeExecutionProvenance(
+    const provenancePath = await writeExecutionProvenance(
       absoluteArtifactsDir,
       provenanceSnapshots,
       endDrift,

package/dist/execution-provenance.js

@@ -3,6 +3,7 @@ import { createHash } from "node:crypto";
 import fs, { constants as fsConstants } from "node:fs";
 import path from "node:path";
 import { mobileSourceFingerprint } from "./adapters/mobile/source-freshness.js";
+import { indexArtifactManifest } from "./artifact-files.js";
 import { importRecipeProtocol, runnerDir } from "./paths.js";
 const gitContexts = /* @__PURE__ */ new Map();
 let protocolPromise;
@@ -102,7 +103,7 @@ function executionProvenanceDrift(start, current) {
   }
   return drift;
 }
-function writeExecutionProvenance(artifactsDir, snapshots, drift, artifactManifestPath) {
+async function writeExecutionProvenance(artifactsDir, snapshots, drift, artifactManifestPath) {
   const provenancePath = path.join(path.resolve(artifactsDir), "execution-provenance.json");
   const record = {
     schemaVersion: 1,
@@ -113,7 +114,20 @@ function writeExecutionProvenance(artifactsDir, snapshots, drift, artifactManife
   fs.mkdirSync(path.dirname(provenancePath), { recursive: true });
   fs.writeFileSync(provenancePath, `${JSON.stringify(record, null, 2)}
 `);
-  if (artifactManifestPath) indexProvenanceArtifact(artifactManifestPath, record);
+  if (artifactManifestPath) {
+    await indexArtifactManifest(artifactManifestPath, [
+      {
+        path: "execution-provenance.json",
+        type: "json",
+        label: "Execution provenance",
+        category: "system",
+        metadata: {
+          valid: record.valid,
+          errorCode: record.valid ? null : "PROVENANCE_DRIFT"
+        }
+      }
+    ]);
+  }
   return provenancePath;
 }
 function recipeFileDigest(protocol, recipePath) {
@@ -309,32 +323,6 @@ function compareSource(drift, phase, prefix, start, current) {
 function compare(drift, phase, field, start, current) {
   if (start !== current) drift.push({ phase, field, start, current });
 }
-function indexProvenanceArtifact(artifactManifestPath, record) {
-  let manifest;
-  try {
-    manifest = JSON.parse(fs.readFileSync(artifactManifestPath, "utf8"));
-  } catch {
-    return;
-  }
-  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) return;
-  const document = manifest;
-  const artifacts = Array.isArray(document.artifacts) ? document.artifacts : [];
-  document.artifacts = [
-    ...artifacts.filter((artifact) => !artifact || typeof artifact !== "object" || Array.isArray(artifact) || artifact.path !== "execution-provenance.json"),
-    {
-      path: "execution-provenance.json",
-      type: "json",
-      label: "Execution provenance",
-      category: "system",
-      metadata: {
-        valid: record.valid,
-        errorCode: record.valid ? null : "PROVENANCE_DRIFT"
-      }
-    }
-  ];
-  fs.writeFileSync(artifactManifestPath, `${JSON.stringify(document, null, 2)}
-`);
-}
 export {
   ProvenanceDriftError,
   captureExecutionProvenance,