@deeeed/metamask-harness 0.17.5 → 0.19.0

package/adapters/shared/update-check-worker.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+
+const [cacheFile, timeoutText, endpoint] = process.argv.slice(2);
+const timeoutMs = Number.parseInt(timeoutText ?? '', 10);
+
+function stableVersion(value) {
+  const match = /^(\d{1,6})\.(\d{1,6})\.(\d{1,6})$/u.exec(value);
+  if (!match) return null;
+  return `${Number(match[1])}.${Number(match[2])}.${Number(match[3])}`;
+}
+
+async function main() {
+  if (!cacheFile || !endpoint || !Number.isInteger(timeoutMs) || timeoutMs < 1) return;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(endpoint, { signal: controller.signal });
+    if (!response.ok) return;
+    const data = await response.json();
+    if (!data || typeof data.latest !== 'string' || data.latest.length === 0) return;
+    const latest = stableVersion(data.latest);
+    if (!latest) return;
+    let lastCheck = Date.now();
+    try {
+      const cached = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+      if (typeof cached.lastCheck === 'number') lastCheck = cached.lastCheck;
+    } catch {
+      // The parent may have exited before creating the cache; recreate it below.
+    }
+    fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+    const temporary = `${cacheFile}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, JSON.stringify({ lastCheck, latest }));
+    fs.renameSync(temporary, cacheFile);
+  } catch {
+    // Passive checks are intentionally silent; the explicit update command teaches failures.
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+await main();

package/bin/mm-harness

@@ -5,6 +5,17 @@
 # end-state surface; it resolves node/tsx/dist the same way whether the package is
 # installed as a dependency or run from a source checkout.
 set -euo pipefail
+INVOKED_AS="$0"
+if [[ "$INVOKED_AS" == */* ]]; then
+  INVOKED_AS="$(cd "$(dirname "$INVOKED_AS")" && pwd -L)/${INVOKED_AS##*/}"
+else
+  RESOLVED_INVOKED_AS="$(command -v "$INVOKED_AS" 2>/dev/null || true)"
+  if [[ -z "$RESOLVED_INVOKED_AS" ]]; then
+    echo "ERROR: Cannot resolve the invoked mm-harness executable: $INVOKED_AS" >&2
+    exit 1
+  fi
+  INVOKED_AS="$RESOLVED_INVOKED_AS"
+fi
 SOURCE="${BASH_SOURCE[0]}"
 while [ -L "$SOURCE" ]; do
   SOURCE_DIR="$(cd "$(dirname "$SOURCE")" && pwd -P)"
@@ -26,7 +37,7 @@ RUNNER_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 # 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")"
+  self_real="$SCRIPT_DIR/${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
@@ -39,7 +50,7 @@ if [ -n "${MM_HARNESS_BIN:-}" ]; then
     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")}"
+  bin_real="${bin_real_dir:+$bin_real_dir/${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
@@ -50,6 +61,14 @@ if [ -n "${MM_HARNESS_BIN:-}" ]; then
   fi
 fi
 
+# Internal executable identity (not part of the public env surface): the CLI
+# embeds this in emitted recovery commands so they run verbatim even when
+# mm-harness is not on PATH (task-local installs). Set AFTER the MM_HARNESS_BIN
+# delegation above so the final executable entered always overwrites any
+# inherited/stale value with its own resolved self path.
+export MM_HARNESS_EXECUTABLE="$SCRIPT_DIR/${SOURCE##*/}"
+export MM_HARNESS_INVOKED_AS="$INVOKED_AS"
+
 ENTRY_TS="$RUNNER_DIR/src/mm-harness-cli.ts"
 ENTRY_DIST="$RUNNER_DIR/dist/mm-harness-cli.js"
 

package/dist/adapters/core/surface.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { depsCheck } from "@farmslot/recipe-harness/runtime/deps-readiness";
+import { shellQuote } from "../../commands/parse-args.js";
 const coreSurface = {
   adapter: "core",
   headless: true,
@@ -14,6 +15,7 @@ const coreSurface = {
       reasons: [
         ready ? "Core is headless; dependencies are installed. Run recipes with mm-harness run." : "Core is headless; dependencies are not fully installed."
       ],
+      nextAction: ready ? void 0 : `cd ${shellQuote(path.resolve(target))} && yarn install --immutable`,
       deps: deps.status
     };
   },
@@ -49,7 +51,8 @@ const coreSurface = {
   },
   hints: {
     launch: "mm-harness run <recipe>   # run recipes against the headless core",
-    relaunch: "mm-harness verify"
+    relaunch: "mm-harness verify",
+    runtimeProbeRecovery: (target) => `mm-harness verify --adapter core --target ${shellQuote(path.resolve(target))}`
   }
 };
 export {

package/dist/adapters/extension/console-capture.js

@@ -0,0 +1,95 @@
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { recipeRuntimePath, runnerDir } from "../../paths.js";
+async function ensureExtensionConsoleCapture(target) {
+  const cdpPort = process.env.CDP_PORT ?? process.env.RECIPE_CDP_PORT;
+  if (!cdpPort) throw new Error("Extension console capture requires a resolved CDP port.");
+  const response = await fetch(`http://127.0.0.1:${cdpPort}/json/version`, {
+    signal: AbortSignal.timeout(3e3)
+  });
+  if (!response.ok) throw new Error(`Extension CDP ${cdpPort} is not ready for console capture.`);
+  const extensionLog = recipeRuntimePath(target, "extension-console.log");
+  const dappLog = recipeRuntimePath(target, "dapp-console.log");
+  const collectorLog = recipeRuntimePath(target, "console-tail.log");
+  const pidFile = recipeRuntimePath(target, "console-tail.pid");
+  fs.mkdirSync(path.dirname(extensionLog), { recursive: true });
+  const existingPid = readPid(pidFile);
+  if (existingPid && collectorOwnsLog(existingPid, extensionLog)) return;
+  if (existingPid) {
+    try {
+      process.kill(existingPid, "SIGTERM");
+    } catch {
+    }
+  }
+  fs.rmSync(pidFile, { force: true });
+  fs.writeFileSync(extensionLog, "");
+  fs.writeFileSync(dappLog, "");
+  const script = path.join(runnerDir, "adapters", "extension", "console-tail.mjs");
+  const output = fs.openSync(collectorLog, "a");
+  let child;
+  try {
+    child = spawn(process.execPath, [
+      script,
+      "--cdp-port",
+      cdpPort,
+      "--extension-log",
+      extensionLog,
+      "--dapp-log",
+      dappLog
+    ], {
+      cwd: target,
+      detached: true,
+      stdio: ["ignore", output, output]
+    });
+  } finally {
+    fs.closeSync(output);
+  }
+  if (!child.pid) throw new Error("Extension console collector did not start.");
+  child.unref();
+  fs.writeFileSync(pidFile, `${child.pid}
+`);
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    if (!processAlive(child.pid)) break;
+    if (collectorOwnsLog(child.pid, extensionLog) && containsAttachment(extensionLog, dappLog)) return;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error(`Extension console collector ${child.pid} did not attach to CDP ${cdpPort}.`);
+}
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function readPid(pidFile) {
+  try {
+    const pid = Number.parseInt(fs.readFileSync(pidFile, "utf8").trim(), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+function collectorOwnsLog(pid, extensionLog) {
+  try {
+    process.kill(pid, 0);
+  } catch {
+    return false;
+  }
+  const result = spawnSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8" });
+  return result.status === 0 && result.stdout.includes("console-tail.mjs") && result.stdout.includes(extensionLog);
+}
+function containsAttachment(...logs) {
+  return logs.some((log) => {
+    try {
+      return fs.readFileSync(log, "utf8").includes("[attached]");
+    } catch {
+      return false;
+    }
+  });
+}
+export {
+  ensureExtensionConsoleCapture
+};

package/dist/adapters/extension/product-config.js

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import path from "node:path";
+import { shellQuote } from "../../commands/parse-args.js";
+function isConfiguredInfuraId(value, placeholder) {
+  return value.length > 0 && value !== placeholder && value !== "true" && value !== "false" && value !== "null";
+}
+function extensionProductConfigBlock(target) {
+  const template = path.join(target, ".metamaskrc.dist");
+  const templateSnapshot = readConfigSnapshot(template);
+  if (templateSnapshot.kind === "missing") return null;
+  if (templateSnapshot.kind === "invalid") {
+    return invalidConfigBlock(target, ".metamaskrc.dist", templateSnapshot.reason);
+  }
+  const placeholder = readInfuraProjectId(templateSnapshot.text) ?? "";
+  const configuredFromEnvironment = process.env.INFURA_PROJECT_ID;
+  if (configuredFromEnvironment !== void 0) {
+    if (isConfiguredInfuraId(configuredFromEnvironment, placeholder)) return null;
+    return {
+      message: "Extension product configuration is blocked by an unusable exported INFURA_PROJECT_ID (the value is never displayed).",
+      userAction: `unset INFURA_PROJECT_ID; cd ${shellQuote(path.resolve(target))} && cp -n .metamaskrc.dist .metamaskrc && \${EDITOR:-vi} .metamaskrc`
+    };
+  }
+  const productionConfig = readConfigSnapshot(path.join(target, ".metamaskprodrc"));
+  if (productionConfig.kind === "invalid") {
+    return invalidConfigBlock(target, ".metamaskprodrc", productionConfig.reason);
+  }
+  if (productionConfig.kind === "file") {
+    const value2 = readInfuraProjectId(productionConfig.text);
+    if (value2 !== void 0) {
+      if (isConfiguredInfuraId(value2, placeholder)) return null;
+      return {
+        message: "Extension product configuration is incomplete: .metamaskprodrc shadows .metamaskrc but does not contain a usable INFURA_PROJECT_ID (the value is never displayed).",
+        userAction: `cd ${shellQuote(path.resolve(target))} && \${EDITOR:-vi} .metamaskprodrc`
+      };
+    }
+  }
+  const config = path.join(target, ".metamaskrc");
+  const configSnapshot = readConfigSnapshot(config);
+  if (configSnapshot.kind === "missing") {
+    return {
+      message: "Extension product configuration is required before launch: create .metamaskrc and set a non-placeholder INFURA_PROJECT_ID (the value is never displayed).",
+      userAction: `cd ${shellQuote(path.resolve(target))} && cp .metamaskrc.dist .metamaskrc && \${EDITOR:-vi} .metamaskrc`
+    };
+  }
+  if (configSnapshot.kind === "invalid") {
+    return invalidConfigBlock(target, ".metamaskrc", configSnapshot.reason);
+  }
+  const value = readInfuraProjectId(configSnapshot.text) ?? "";
+  if (isConfiguredInfuraId(value, placeholder)) return null;
+  return {
+    message: "Extension product configuration is incomplete: .metamaskrc must contain a non-placeholder INFURA_PROJECT_ID (the value is never displayed).",
+    userAction: `cd ${shellQuote(path.resolve(target))} && \${EDITOR:-vi} .metamaskrc`
+  };
+}
+function readConfigSnapshot(file) {
+  let descriptor;
+  try {
+    descriptor = fs.openSync(
+      file,
+      fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK
+    );
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT") return { kind: "missing" };
+    if (code === "ELOOP") return { kind: "invalid", reason: "symlink" };
+    return { kind: "invalid", reason: "unreadable" };
+  }
+  try {
+    if (!fs.fstatSync(descriptor).isFile()) return { kind: "invalid", reason: "not-regular" };
+    return { kind: "file", text: fs.readFileSync(descriptor, "utf8") };
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+function invalidConfigBlock(target, name, reason) {
+  const resolved = shellQuote(path.resolve(target));
+  if (name === ".metamaskrc.dist") {
+    return {
+      message: `Extension product configuration is invalid: ${name} is ${reason === "symlink" ? "a symbolic link" : reason === "not-regular" ? "not a regular file" : "unreadable"}.`,
+      userAction: `cd ${resolved} && ls -l ${name}`
+    };
+  }
+  if (reason === "unreadable") {
+    return {
+      message: `Extension product configuration could not be read from ${name}.`,
+      userAction: `cd ${resolved} && ls -l ${name} && \${EDITOR:-vi} ${name}`
+    };
+  }
+  return {
+    message: reason === "symlink" ? `Extension product configuration is invalid: ${name} must not be a symbolic link.` : `Extension product configuration is invalid: ${name} must be a regular file, not its current file type.`,
+    userAction: `cd ${resolved} && rm ${name} && ${name === ".metamaskrc" ? "cp .metamaskrc.dist .metamaskrc && " : ""}\${EDITOR:-vi} ${name}`
+  };
+}
+function readInfuraProjectId(text) {
+  const lines = text.replace(/\r\n?/gu, "\n");
+  const pattern = /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/gmu;
+  let result;
+  for (const match of lines.matchAll(pattern)) {
+    if (match[1] !== "INFURA_PROJECT_ID") continue;
+    let value = (match[2] ?? "").trim();
+    const quote = value[0];
+    value = value.replace(/^(['"`])([\s\S]*)\1$/u, "$2");
+    if (quote === '"') value = value.replace(/\\n/gu, "\n").replace(/\\r/gu, "\r");
+    result = value;
+  }
+  return result;
+}
+export {
+  extensionProductConfigBlock
+};

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

@@ -166,6 +166,10 @@ function runtimeDistCheck(target) {
       "-rnic",
       "--exclude",
       "_metadata",
+      "--exclude",
+      "home.html",
+      "--exclude",
+      "sidepanel.html",
       "--out-format=%n",
       `${dist}${path.sep}`,
       `${runtimeDist}${path.sep}`
@@ -173,8 +177,22 @@ function runtimeDistCheck(target) {
   } catch {
     return { status: "stale", modified: ["<snapshot comparison failed>"] };
   }
-  const modified = output.split("\n").map((line) => line.trim()).filter(Boolean).slice(0, 10);
-  return modified.length > 0 ? { status: "stale", modified } : { status: "fresh" };
+  const modified = output.split("\n").map((line) => line.trim()).filter(Boolean);
+  for (const name of ["home.html", "sidepanel.html"]) {
+    const source = path.join(dist, name);
+    const loaded = path.join(runtimeDist, name);
+    if (normalizedRuntimeHtml(source) !== normalizedRuntimeHtml(loaded)) modified.push(name);
+  }
+  const boundedModified = [...new Set(modified)].slice(0, 10);
+  return boundedModified.length > 0 ? { status: "stale", modified: boundedModified } : { status: "fresh" };
+}
+function normalizedRuntimeHtml(file) {
+  if (!fs.existsSync(file)) return null;
+  const source = fs.readFileSync(file, "utf8");
+  return source.replace(/<title>([^<]*)<\/title>/iu, (_match, title) => {
+    const base = String(title || "MetaMask").replace(/^.+?\s+[—–-]\s+/u, "") || "MetaMask";
+    return `<title>${base}</title>`;
+  });
 }
 function distCheck(target) {
   const manifestPath = path.join(target, "dist/chrome/manifest.json");

package/dist/adapters/extension/surface.js

@@ -1,12 +1,14 @@
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { recipeRuntimePath, runnerDir } from "../../paths.js";
+import { shellQuote } from "../../commands/parse-args.js";
 import {
   isExtensionWatcherLive,
   resolveExtensionSlotPorts,
   stopExtensionRuntime
 } from "../slot-ports.js";
 import { decideExtensionReadiness } from "./runtime-decision.js";
+import { extensionProductConfigBlock } from "./product-config.js";
 function watcherStatus(buildLog) {
   if (buildLog === "ok") return "up";
   if (buildLog === "no-watch") return "down";
@@ -22,10 +24,25 @@ const extensionSurface = {
     const cdpPort = process.env.CDP_PORT ? parseInt(process.env.CDP_PORT, 10) : void 0;
     const report = await decideExtensionReadiness(target, { cdpPort, pageMode: "home-or-sidepanel" });
     const watcherLive = isExtensionWatcherLive(target);
+    const productConfigBlock = report.decision === "ready" ? null : extensionProductConfigBlock(target);
+    if (productConfigBlock) {
+      return {
+        decision: "blocked",
+        reasonCode: "product-config-required",
+        reasons: [productConfigBlock.message],
+        nextAction: productConfigBlock.userAction,
+        deps: report.checks.deps.status,
+        devServer: {
+          label: "webpack",
+          status: watcherLive ? watcherStatus(report.checks.buildLog.status) : "down"
+        }
+      };
+    }
     return {
       decision: report.decision,
       reasonCode: report.reasonCode,
       reasons: report.reasons,
+      nextAction: report.decision === "ready" ? void 0 : `mm-harness launch --adapter extension --target ${shellQuote(path.resolve(target))}`,
       deps: report.checks.deps.status,
       devServer: {
         label: "webpack",
@@ -65,15 +82,17 @@ const extensionSurface = {
     return [
       { label: "webpack", path: recipeRuntimePath(target, "webpack.log") },
       { label: "watcher", path: recipeRuntimePath(target, "recipe-harness-webpack.log") },
-      { label: "rebuild", path: recipeRuntimePath(target, "rebuild.log") }
+      { label: "rebuild", path: recipeRuntimePath(target, "rebuild.log") },
+      { label: "dapp", path: recipeRuntimePath(target, "dapp-console.log") }
     ];
   },
   appLogSource(target) {
-    return { label: "app", path: recipeRuntimePath(target, "extension-console.log") };
+    return { label: "extension", path: recipeRuntimePath(target, "extension-console.log") };
   },
   hints: {
     launch: "mm-harness launch",
-    relaunch: "mm-harness launch --build"
+    relaunch: "mm-harness launch --build",
+    runtimeProbeRecovery: (target) => `mm-harness launch --adapter extension --target ${shellQuote(path.resolve(target))}`
   }
 };
 export {

package/dist/adapters/harness-freshness.js

@@ -0,0 +1,49 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { recipeHarnessPath, runnerDir } from "../paths.js";
+async function ensureHarnessFresh(target, adapter) {
+  if (!fs.existsSync(path.join(target, "package.json")) || !hasCheckoutHead(target)) return;
+  let current;
+  try {
+    const mod = await import(pathToFileURL(path.join(runnerDir, "adapters/shared/harness-source-fingerprint.mjs")).href);
+    current = mod.harnessSourceFingerprint(runnerDir, adapter);
+  } catch (error) {
+    const detail = error instanceof Error ? `: ${error.message}` : "";
+    throw new Error(`could not fingerprint the ${adapter} harness source${detail}`);
+  }
+  const manifestPath = recipeHarnessPath(target, adapter, "manifest.json");
+  const installed = readInstalledFingerprint(manifestPath);
+  if (installed === current) return;
+  const reason = installed === null ? "harness not installed" : "runner changed";
+  const injector = path.join(runnerDir, `adapters/${adapter}/inject.${adapter === "extension" ? "mjs" : "sh"}`);
+  try {
+    execFileSync(adapter === "extension" ? process.execPath : "bash", [injector, "--target", target], {
+      stdio: ["ignore", "ignore", "inherit"]
+    });
+    console.error(`\u2192 refreshed ${adapter} harness overlay (${reason})`);
+  } catch (error) {
+    const detail = error instanceof Error ? `: ${error.message}` : "";
+    throw new Error(`could not refresh the ${adapter} harness overlay (${reason})${detail}`);
+  }
+}
+function hasCheckoutHead(target) {
+  try {
+    execFileSync("git", ["-C", target, "rev-parse", "--verify", "HEAD"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function readInstalledFingerprint(manifestPath) {
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    return typeof manifest.sourceFingerprint === "string" ? manifest.sourceFingerprint : null;
+  } catch {
+    return null;
+  }
+}
+export {
+  ensureHarnessFresh
+};

package/dist/adapters/mobile/perps-env.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 const DEFAULTS = {
@@ -24,14 +25,53 @@ function ensureMobilePerpsEnvironment(target) {
     (key) => settingForKey(current, key).status === "missing"
   );
   if (missing.length === 0) return [];
-  const file = path.join(target, current.file);
-  const before = current.fileExists ? fs.readFileSync(file, "utf8") : "";
+  const file = path.join(fs.realpathSync(target), current.file);
+  const snapshot = readEnvironmentSnapshot(file);
+  const before = snapshot?.text ?? "";
   const separator = before.length > 0 && !before.endsWith("\n") ? "\n" : "";
   const additions = missing.map((key) => `export ${key}="${DEFAULTS[key]}"`).join("\n");
-  fs.writeFileSync(file, `${before}${separator}${additions}
+  const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  let descriptor = null;
+  try {
+    descriptor = fs.openSync(
+      temporary,
+      fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL,
+      snapshot?.mode ?? 384
+    );
+    fs.writeFileSync(descriptor, `${before}${separator}${additions}
 `);
+    if (snapshot) fs.fchmodSync(descriptor, snapshot.mode);
+    fs.closeSync(descriptor);
+    descriptor = null;
+    fs.renameSync(temporary, file);
+  } finally {
+    if (descriptor !== null) fs.closeSync(descriptor);
+    fs.rmSync(temporary, { force: true });
+  }
   return missing;
 }
+function readEnvironmentSnapshot(file) {
+  let descriptor;
+  try {
+    descriptor = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT") return null;
+    if (code === "ELOOP") {
+      throw new Error(`.js.env must not be a symbolic link. Next: replace ${file} with a regular file.`);
+    }
+    throw error;
+  }
+  try {
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile()) {
+      throw new Error(`.js.env must be a regular file. Next: replace ${file} with a regular file.`);
+    }
+    return { text: fs.readFileSync(descriptor, "utf8"), mode: stat.mode & 511 };
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
 function readSetting(source, key) {
   const assignment = new RegExp(`^\\s*(?:export\\s+)?${key}\\s*=(.*)$`, "u");
   let value = null;

package/dist/adapters/mobile/prepare.js

@@ -49,6 +49,8 @@ async function prepareMobile(target, opts = {}) {
     return { status: EXIT.runtime, output: msg };
   }
   if (report.decision === "ready") {
+    const surface = await ensureMobileHumanSurface(target, platform, json);
+    if (surface.status !== 0) return surface;
     const confirm = await dispatchAction(
       { id: "wait-for-bridge", cwd: target, argv: ["--max-polls", String(READY_BRIDGE_CONFIRM_POLLS)] },
       target,
@@ -56,14 +58,21 @@ async function prepareMobile(target, opts = {}) {
       json,
       preflightMode
     );
-    if (confirm.status === 0) return { status: 0, output: "" };
+    if (confirm.status === 0) return startMobileConsoleForwarder(target, platform, json);
     if (!json) {
       process.stderr.write(
         `launch: runtime looked ready but no ${platform} bridge target answered; launching the app.
 `
       );
     }
-    return dispatchActionSequence(launchActions(path.resolve(target)), target, platform, json, preflightMode);
+    const launch = await dispatchActionSequence(
+      launchActions(path.resolve(target)),
+      target,
+      platform,
+      json,
+      preflightMode
+    );
+    return launch.status === 0 ? startMobileConsoleForwarder(target, platform, json) : launch;
   }
   if (report.decision === "unknown") {
     const msg = "mobile prepare: runtime state unknown\n  Next: run mm-harness verify --adapter mobile --target <checkout>";
@@ -93,6 +102,8 @@ async function prepareMobile(target, opts = {}) {
         return { status: EXIT.runtime, output: msg };
       }
       case "ready": {
+        const surface = await ensureMobileHumanSurface(target, platform, json);
+        if (surface.status !== 0) return surface;
         const bridge = await dispatchAction({ id: "wait-for-bridge", cwd: target }, target, platform, json, preflightMode);
         if (bridge.status !== 0) return bridge;
         break;
@@ -111,7 +122,19 @@ async function prepareMobile(target, opts = {}) {
       }
     }
   }
-  return { status: 0, output: "" };
+  return startMobileConsoleForwarder(target, platform, json);
+}
+function startMobileConsoleForwarder(target, platform, json) {
+  return dispatchAction(
+    { id: "start-console-forwarder", cwd: target, argv: json ? ["--quiet"] : [] },
+    target,
+    platform,
+    json
+  );
+}
+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);
 }
 async function dispatchActionSequence(requestedActions, target, platform, json, preflightMode) {
   const resolved = path.resolve(target);
@@ -147,6 +170,10 @@ async function dispatchAction(action, target, platform, json, preflightMode = "f
       const extra = action.argv ?? [];
       return spawnScriptStreaming(leaf, ["--target", cwd, ...extra], target);
     }
+    case "start-console-forwarder": {
+      const leaf = path.join(runnerDir, "adapters/mobile/start-console-forwarder.sh");
+      return spawnScriptStreaming(leaf, ["--target", cwd, ...action.argv ?? []], target);
+    }
     case "prewarm-bundle": {
       const leaf = path.join(runnerDir, "adapters/mobile/prewarm-bundle.sh");
       return spawnScriptStreaming(leaf, ["--platform", platform, "--target", cwd], target);
@@ -156,10 +183,6 @@ async function dispatchAction(action, target, platform, json, preflightMode = "f
       const extra = action.argv ?? [];
       return spawnScriptStreaming(leaf, ["--target", cwd, "--platform", platform, ...extra], target);
     }
-    case "clear-metro-cache": {
-      const leaf = path.join(runnerDir, "adapters/mobile/start-metro.sh");
-      return spawnScriptStreaming(leaf, ["--target", cwd, "--clear"], target);
-    }
     case "launch-mobile-runtime": {
       const leaf = path.join(runnerDir, "adapters/mobile/open-device.sh");
       return spawnScriptStreaming(
@@ -169,6 +192,15 @@ async function dispatchAction(action, target, platform, json, preflightMode = "f
         POD_PROBE_ENV
       );
     }
+    case "ensure-device-ui": {
+      const leaf = path.join(runnerDir, "adapters/mobile/open-device.sh");
+      return spawnScriptStreaming(
+        leaf,
+        ["--platform", platform, "--target", cwd, "--ui-only"],
+        target,
+        POD_PROBE_ENV
+      );
+    }
     case "rebuild-native-dev-client": {
       const msg = "rebuild-native-dev-client required: native module mismatch detected.\n  Next: yarn start:ios or yarn start:android to rebuild the native dev client, then re-run mm-harness launch.";
       if (!json) process.stderr.write(`${msg}

package/dist/adapters/mobile/surface.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { recipeRuntimePath, runnerDir } from "../../paths.js";
+import { shellQuote } from "../../commands/parse-args.js";
 import { resolveMobileSlotPorts } from "../slot-ports.js";
 import { mobileRuntimeStatus } from "./prepare.js";
 import { hasRunwayProvisionBaseline, provisionRunwayMobile } from "./provision.js";
@@ -20,6 +21,7 @@ const mobileSurface = {
       decision: depsPending ? "launch" : report.decision,
       reasonCode: depsPending ? "app-installed-deps-pending" : report.reasonCode,
       reasons: depsPending ? ["Runway app is installed; JavaScript dependencies are pending until dispatch-time launch."] : report.reasons,
+      nextAction: report.decision === "ready" && !depsPending ? void 0 : `mm-harness launch ${platform} --adapter mobile --target ${shellQuote(path.resolve(target))}`,
       deps: runwayProvisioned && report.checks?.deps?.status !== "current" ? "pending" : report.checks?.deps?.status,
       devServer: { label: "metro", status: report.checks?.metro?.status ?? "unprobed" }
     };
@@ -47,11 +49,12 @@ const mobileSurface = {
     return [{ label: "metro", path: recipeRuntimePath(target, "metro.log") }];
   },
   appLogSource(target) {
-    return { label: "app", path: recipeRuntimePath(target, "metro.log") };
+    return { label: "app", path: recipeRuntimePath(target, "app-console.log") };
   },
   hints: {
     launch: "mm-harness launch ios",
-    relaunch: "mm-harness launch ios"
+    relaunch: "mm-harness launch ios",
+    runtimeProbeRecovery: (target) => `mm-harness status --target ${shellQuote(path.resolve(target))} --json`
   }
 };
 export {