@deeeed/metamask-harness 0.17.5 → 0.18.0

package/dist/commands/launch/extension.js

@@ -3,13 +3,15 @@ import http from "node:http";
 import fs from "node:fs";
 import path from "node:path";
 import { depsCheck } from "@farmslot/recipe-harness/runtime/deps-readiness";
+import { colorHumanMessage } from "../../cli-color.js";
 import { recipeHarnessPath, recipeRuntimeDir, runnerDir } from "../../paths.js";
 import { extensionIdFromKey } from "../../adapters/extension/extension-id.js";
+import { extensionProductConfigBlock } from "../../adapters/extension/product-config.js";
 import { isExtensionDistStale } from "../../adapters/extension/runtime-decision.js";
 import { checkExtensionRuntimeHealth } from "../../adapters/extension/runtime.js";
 import { ensureExtensionHarnessFresh } from "../../adapters/extension/harness-freshness.js";
 import { stopExtensionWatcher } from "../../adapters/slot-ports.js";
-import { spawnScriptStreaming } from "../shared.js";
+import { EXIT, spawnScriptStreaming } from "../shared.js";
 function extensionDepsBlock(target) {
   if (!fs.existsSync(path.join(target, "package.json"))) return null;
   const deps = depsCheck(target);
@@ -30,18 +32,32 @@ function installExtensionDeps(target) {
   return spawnScriptStreaming(installScript, ["--target", target], target);
 }
 async function launchExtension(target, tier, wantWatch, displayMode = "fullscreen") {
+  if (process.env.CHROME_USER_DATA_DIR) {
+    process.env.CHROME_USER_DATA_DIR = path.resolve(process.env.CHROME_USER_DATA_DIR);
+  }
+  const reusable = !wantWatch && tier !== "build" && await extensionRuntimeReusable(target);
+  if (!reusable) {
+    const block = extensionProductConfigBlock(target);
+    if (block) {
+      return {
+        status: EXIT.infra,
+        output: `EXTENSION_PRODUCT_CONFIG_REQUIRED: ${block.message}
+Next: ${block.userAction}`
+      };
+    }
+  }
   await ensureExtensionHarnessFresh(target);
   if (wantWatch) {
     const startWatchSh = path.join(runnerDir, "adapters/extension/start-watch.sh");
     const watchArgs = ["--target", target];
     if (process.env.WATCHER_PORT) watchArgs.push("--watcher-port", process.env.WATCHER_PORT);
-    console.error(`\u2192 extension watch \u2014 webpack :${process.env.WATCHER_PORT ?? "default"} (output streams below)`);
+    console.error(colorHumanMessage(`\u2192 extension watch \u2014 webpack :${process.env.WATCHER_PORT ?? "default"} (output streams below)`));
     return spawnScriptStreaming(startWatchSh, watchArgs, target);
   }
   if (tier === "build") {
     return extensionRebuild(target);
   }
-  if (await extensionRuntimeReusable(target)) {
+  if (reusable) {
     return extensionReattach(target, displayMode);
   }
   return extensionRebuild(target);
@@ -49,12 +65,16 @@ async function launchExtension(target, tier, wantWatch, displayMode = "fullscree
 async function extensionRuntimeReusable(target) {
   const cdpPort = process.env.CDP_PORT;
   if (!cdpPort) return false;
-  if (!cdpOwnedByExpectedRuntime(cdpPort, target)) return false;
-  if (!await cdpVersionReachable(cdpPort)) return false;
-  if (!await cdpHasExpectedExtensionTarget(cdpPort, target)) return false;
-  if (!await cdpRuntimeHealthy(cdpPort, target)) return false;
   if (isExtensionDistStale(target)) return false;
-  return true;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const reachable = await cdpVersionReachable(cdpPort);
+    const owned = reachable && cdpOwnedByExpectedRuntime(cdpPort, target);
+    const targetPresent = owned && await cdpHasExpectedExtensionTarget(cdpPort, target);
+    const healthy = targetPresent && await cdpRuntimeHealthy(cdpPort, target);
+    if (healthy) return true;
+    if (attempt < 2) await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  return false;
 }
 function expectedChromeProfile(target) {
   const profileName = process.env.RECIPE_CHROME_PROFILE_NAME || "chrome-profile";
@@ -170,12 +190,15 @@ function cdpHasExpectedExtensionTarget(port, target) {
   });
 }
 async function cdpRuntimeHealthy(port, target) {
-  try {
-    const report = await checkExtensionRuntimeHealth(target, Number(port), { pageMode: "home-or-sidepanel" });
-    return report.status === "PASS";
-  } catch {
-    return false;
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      const report = await checkExtensionRuntimeHealth(target, Number(port), { pageMode: "home-or-sidepanel" });
+      if (report.status === "PASS") return true;
+    } catch {
+    }
+    if (attempt < 2) await new Promise((resolve) => setTimeout(resolve, 250));
   }
+  return false;
 }
 async function extensionReattach(target, displayMode = "fullscreen") {
   const reattachScript = recipeHarnessPath(target, "extension", "scripts", "reattach.sh");
@@ -183,7 +206,7 @@ async function extensionReattach(target, displayMode = "fullscreen") {
   if (process.env.CDP_PORT) reattachArgs.push("--cdp-port", process.env.CDP_PORT);
   if (process.env.WATCHER_PORT) reattachArgs.push("--watcher-port", process.env.WATCHER_PORT);
   if (process.env.EXTENSION_START_URL) reattachArgs.push("--start-url", process.env.EXTENSION_START_URL);
-  console.error(`\u2192 extension quick reattach \u2014 reload in place \xB7 CDP :${process.env.CDP_PORT ?? "default"} (no rebuild, no relaunch)`);
+  console.error(colorHumanMessage(`\u2192 extension quick reattach \u2014 reload in place \xB7 CDP :${process.env.CDP_PORT ?? "default"} (no rebuild, no relaunch)`));
   return spawnScriptStreaming(reattachScript, reattachArgs, target);
 }
 async function extensionRebuild(target) {
@@ -197,7 +220,7 @@ async function extensionRebuild(target) {
   const liveArgs = ["--target", target, "--start-watch"];
   if (process.env.CDP_PORT) liveArgs.push("--cdp-port", process.env.CDP_PORT);
   if (process.env.EXTENSION_START_URL) liveArgs.push("--start-url", process.env.EXTENSION_START_URL);
-  console.error(`\u2192 extension quick relaunch \u2014 webpack :${process.env.WATCHER_PORT ?? "default"} \xB7 CDP :${process.env.CDP_PORT ?? "default"} (output streams below)`);
+  console.error(colorHumanMessage(`\u2192 extension quick relaunch \u2014 webpack :${process.env.WATCHER_PORT ?? "default"} \xB7 CDP :${process.env.CDP_PORT ?? "default"} (output streams below)`));
   const result = await spawnScriptStreaming(liveScript, liveArgs, target);
   if (result.output) {
     try {

package/dist/commands/launch/index.js

@@ -1,12 +1,13 @@
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { color } from "../../cli-color.js";
+import { color, colorHumanMessage } from "../../cli-color.js";
 import { handleHarness } from "../../harness.js";
 import { recipeRuntimePath, runnerDir } from "../../paths.js";
 import { getAdapterSurface } from "../../adapters/surface.js";
 import {
   ADAPTER_DETECT_NEXT,
+  checkoutBusyOut,
   EXIT,
   flag,
   parseFlags,
@@ -14,7 +15,8 @@ import {
   spawnScript,
   str,
   targetOf,
-  usageOut
+  usageOut,
+  writeInteractiveProgress
 } from "../shared.js";
 import {
   RECOVERY_CODE,
@@ -32,6 +34,9 @@ import {
 import { launchMobile } from "./mobile.js";
 import { applyDeviceTargeting } from "../device-target.js";
 import { acquireCheckoutLock } from "../../checkout-lock.js";
+import { JsonStreamWriter } from "../../json-stream.js";
+import { ensureExtensionConsoleCapture } from "../../adapters/extension/console-capture.js";
+import { extensionProductConfigBlock } from "../../adapters/extension/product-config.js";
 const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
   "build",
   "watch",
@@ -39,30 +44,58 @@ const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
   "sidepanel",
   "fullscreen",
   "runway",
-  "json"
+  "json",
+  "jsonStream"
 ]);
 const DEFAULT_EXTENSION_DAPP_URL = "https://metamask.github.io/test-dapp/";
 async function handleLaunch(argv) {
   const { options } = parseFlags(argv, LAUNCH_BOOLEANS);
   const json = flag(options, "json");
+  const stream = new JsonStreamWriter("launch", flag(options, "jsonStream"));
+  const jsonOutput = json && !stream.enabled;
+  const restoreStdout = stream.isolateStdout();
   const target = targetOf(options);
-  if (!fs.existsSync(target)) return handleLaunchLocked(argv);
-  const lock = acquireCheckoutLock(target, "launch");
-  if ("message" in lock) {
-    return usageOut(json, "launch", lock.message, `wait for the current owner, or inspect ${lock.path} if its process has exited`);
-  }
   try {
-    return await handleLaunchLocked(argv);
+    let exitCode;
+    if (!fs.existsSync(target)) {
+      exitCode = await handleLaunchLocked(argv, stream);
+    } else {
+      const lock = acquireCheckoutLock(target, "launch");
+      if ("message" in lock) {
+        const userAction = `wait for the current owner, or inspect ${lock.path} if its process has exited`;
+        stream.error({ code: "SANDBOX_BUSY", message: lock.message, userAction });
+        exitCode = checkoutBusyOut(jsonOutput, "launch", lock.message, lock.path);
+      } else {
+        try {
+          exitCode = await handleLaunchLocked(argv, stream);
+        } finally {
+          lock.release();
+        }
+      }
+    }
+    stream.complete(exitCode === EXIT.ok ? "pass" : "fail", exitCode);
+    return exitCode;
+  } catch (error) {
+    const exitCode = error !== null && typeof error === "object" && "exitCode" in error && typeof error.exitCode === "number" ? error.exitCode : EXIT.runtime;
+    stream.error({
+      code: exitCode === EXIT.usage ? "CLI_USAGE_ERROR" : "LAUNCH_FAILED",
+      message: error instanceof Error ? error.message : String(error),
+      userAction: `mm-harness doctor --target ${shellQuote(target)} --json`
+    });
+    stream.complete("fail", exitCode);
+    throw error;
   } finally {
-    lock.release();
+    restoreStdout();
   }
 }
-async function handleLaunchLocked(argv) {
+async function handleLaunchLocked(argv, stream) {
   const { positional, options } = parseFlags(argv, LAUNCH_BOOLEANS);
   const json = flag(options, "json");
+  const jsonOutput = json && !stream.enabled;
+  const machine = json || stream.enabled;
   const target = targetOf(options);
   const heal = parseHeal(options, "auto");
-  if (typeof heal !== "string") return usageOut(json, "launch", heal.error, "use --heal off|infra-only|auto");
+  if (typeof heal !== "string") return launchUsage(jsonOutput, stream, heal.error, "use --heal off|infra-only|auto");
   const posToken = positional[0];
   const mobileTargetToken = posToken === "ios" || posToken === "android" ? posToken : void 0;
   const platformFlag = str(options, "platform");
@@ -71,15 +104,16 @@ async function handleLaunchLocked(argv) {
   const adapterHint = mobileTarget ? "mobile" : void 0;
   const adapter = resolveAdapter(options, target, adapterHint);
   if (!adapter) {
-    return usageOut(json, "launch", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
+    return launchUsage(jsonOutput, stream, `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   }
+  stream.phase("resolve", { target, adapter, platform: mobileTarget ?? null });
   if (adapter === "core") {
-    return usageOut(json, "launch", "core is headless; there is nothing to launch.", "mm-harness verify");
+    return launchUsage(jsonOutput, stream, "core is headless; there is nothing to launch.", "mm-harness verify");
   }
   if (adapter === "mobile" && !mobileTarget) {
-    return usageOut(
-      json,
-      "launch",
+    return launchUsage(
+      jsonOutput,
+      stream,
       "target is required for mobile.",
       "mm-harness launch ios   or   mm-harness launch android"
     );
@@ -89,15 +123,15 @@ async function handleLaunchLocked(argv) {
   const wantWatch = flag(options, "watch");
   const wantRunway = flag(options, "runway");
   if (wantRunway && adapter !== "mobile") {
-    return usageOut(json, "launch", "runway is mobile-only.", "drop --runway for the extension");
+    return launchUsage(jsonOutput, stream, "runway is mobile-only.", "drop --runway for the extension");
   }
   const displayMode = flag(options, "sidepanel") && !flag(options, "fullscreen") ? "sidepanel" : "fullscreen";
   for (const portFlag of ["cdpPort", "watcherPort"]) {
     const value = str(options, portFlag);
     if (value !== void 0 && !/^\d+$/u.test(value)) {
-      return usageOut(
-        json,
-        "launch",
+      return launchUsage(
+        jsonOutput,
+        stream,
         `--${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"}`
       );
@@ -105,7 +139,7 @@ async function handleLaunchLocked(argv) {
   }
   const envResult = applyLaunchEnvOverrides(options, adapter, mobileTarget, target);
   if (envResult && "code" in envResult) {
-    return usageOut(json, "launch", envResult.message, "mm-harness launch android --device <adb-serial|device-name>");
+    return launchUsage(jsonOutput, stream, envResult.message, envResult.userAction);
   }
   const tier = wantBuild ? "build" : "quick";
   if (adapter === "extension") {
@@ -114,44 +148,65 @@ async function handleLaunchLocked(argv) {
       process.env.EXTENSION_START_URL = requestedUrl || DEFAULT_EXTENSION_DAPP_URL;
     }
   }
-  if (!json && adapter === "extension") {
+  if (!machine && adapter === "extension") {
     const modeNote = displayMode === "sidepanel" ? `sidepanel \xB7 dapp ${process.env.EXTENSION_START_URL ?? DEFAULT_EXTENSION_DAPP_URL}` : "fullscreen";
     const workNote = wantWatch ? "watch only" : tier === "build" ? "clean build" : "quick reuse probe";
-    console.error(
+    console.error(colorHumanMessage(
       `\u2192 extension launch \u2014 ${modeNote} \xB7 CDP :${process.env.CDP_PORT ?? "default"} \xB7 ${workNote}`
+    ));
+  }
+  if (adapter === "mobile") {
+    const device = str(options, "device") ?? (mobileTarget === "android" ? process.env.ADB_SERIAL ?? process.env.ANDROID_SERIAL : process.env.IOS_SIMULATOR ?? process.env.SIM_UDID) ?? "configured device";
+    const watcherPort = str(options, "watcherPort") ?? process.env.WATCHER_PORT ?? "auto";
+    writeInteractiveProgress(
+      machine,
+      `\u2192 mobile launch \u2014 ${mobileTarget} \xB7 ${tier === "build" ? "native build" : "quick readiness"} \xB7 ${device} \xB7 Metro ${watcherPort === "auto" ? "auto" : `:${watcherPort}`}`
     );
   }
   const state = newHealState();
   if (tier === "quick" && nativeInputsChanged(target, adapter)) {
-    return usageOut(
-      json,
-      "launch",
+    return launchUsage(
+      jsonOutput,
+      stream,
       "native build inputs changed since last build.",
       `mm-harness launch ${adapter === "mobile" ? `${mobileTarget} ` : ""}--build`
     );
   }
-  const ensured = await ensureOverlay(adapter, target, heal, state, json);
+  stream.phase("install");
+  const ensured = await ensureOverlay(adapter, target, heal, state, machine);
   if (!ensured.ok) {
-    return launchFail(json, adapter, mobileTarget, tier, state, {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: "OVERLAY_INSTALL_FAILED",
       message: ensured.error ?? "overlay install failed",
       recoverable: false,
       exitCode: EXIT.infra
     });
   }
+  stream.phase("healthcheck");
   if (adapter === "extension") {
     const willBuild = wantWatch || tier === "build" || !await extensionRuntimeReusable(target);
     if (willBuild) {
+      const productConfigBlock = extensionProductConfigBlock(target);
+      if (productConfigBlock) {
+        return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
+          code: "EXTENSION_PRODUCT_CONFIG_REQUIRED",
+          message: productConfigBlock.message,
+          recoverable: false,
+          userAction: productConfigBlock.userAction,
+          exitCode: EXIT.infra
+        });
+      }
       const depsBlock = extensionDepsBlock(target);
       if (depsBlock) {
         if (heal === "off") {
-          return usageOut(json, "launch", depsBlock.message, depsBlock.userAction);
+          return launchUsage(jsonOutput, stream, depsBlock.message, depsBlock.userAction);
         }
         const recoveryCode2 = "deps.installed";
         state.attemptedRecoveries.push(recoveryCode2);
+        stream.phase("recover");
         const repaired = await installExtensionDeps(target);
         if (repaired.status !== 0 || extensionDepsBlock(target)) {
-          return launchFail(json, adapter, mobileTarget, tier, state, {
+          return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
             code: "DEPENDENCY_INSTALL_FAILED",
             message: depsBlock.message,
             recoverable: false,
@@ -165,12 +220,32 @@ async function handleLaunchLocked(argv) {
       }
     }
   }
-  let attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, json, displayMode);
+  stream.phase("launch");
+  let attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, machine, displayMode);
   if (attempt.status === 0) {
-    return await finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
+    return await finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
+  }
+  if (adapter === "extension" && extensionProductConfigMissing(attempt.output)) {
+    const block = extensionProductConfigBlock(target);
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
+      code: "EXTENSION_PRODUCT_CONFIG_REQUIRED",
+      message: block?.message ?? "Extension product configuration was not ready when the build started.",
+      recoverable: false,
+      userAction: block?.userAction ?? `mm-harness launch --adapter extension --target ${shellQuote(target)}`,
+      exitCode: EXIT.infra
+    });
+  }
+  if (adapter === "extension" && extensionBrowserMissing(attempt.output)) {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
+      code: "EXTENSION_BROWSER_REQUIRED",
+      message: "the checkout Playwright browser is not installed; system Chrome is not a compatible unpacked-extension fallback. Installing the browser cache requires user approval.",
+      recoverable: false,
+      userAction: `ask the user for approval, then run: cd ${shellQuote(target)} && yarn playwright install chromium`,
+      exitCode: EXIT.infra
+    });
   }
   if (heal === "off") {
-    return launchFail(json, adapter, mobileTarget, tier, state, {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: "LAUNCH_FAILED",
       message: `launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ""} failed (healing off)`,
       recoverable: false,
@@ -180,12 +255,13 @@ async function handleLaunchLocked(argv) {
   if (adapter === "extension" && tier === "quick" && extensionQuickReattachFailed(attempt.output)) {
     const recoveryCode2 = "chrome.relaunched";
     state.attemptedRecoveries.push(recoveryCode2);
-    const rebuildAttempt = await executeComposition(adapter, mobileTarget, "build", wantWatch, target, json, displayMode);
+    stream.phase("recover");
+    const rebuildAttempt = await executeComposition(adapter, mobileTarget, "build", wantWatch, target, machine, displayMode);
     if (rebuildAttempt.status === 0) {
       state.recovered.push(recoveryCode2);
-      return await finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
+      return await finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
     }
-    return launchFail(json, adapter, mobileTarget, tier, state, {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: "EXTENSION_RELAUNCH_FAILED",
       message: "quick reattach failed, and clean relaunch failed too.",
       recoverable: false,
@@ -194,7 +270,7 @@ async function handleLaunchLocked(argv) {
     });
   }
   if (adapter === "mobile" && mobileProvisioningBlocked(attempt.output)) {
-    return launchFail(json, adapter, mobileTarget, tier, state, {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: "MOBILE_PROVISION_REQUIRED",
       message: `mobile ${mobileTarget ?? "runtime"} is not provisioned for this slot.`,
       recoverable: false,
@@ -205,7 +281,7 @@ async function handleLaunchLocked(argv) {
   }
   const bound = checkHealBounds(target, attempt.output, state);
   if (bound !== null) {
-    return launchFail(json, adapter, mobileTarget, tier, state, {
+    return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
       code: bound.code,
       message: bound.message,
       recoverable: false,
@@ -216,12 +292,13 @@ async function handleLaunchLocked(argv) {
   }
   const recoveryCode = RECOVERY_CODE[adapter];
   state.attemptedRecoveries.push(recoveryCode);
-  attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, json, displayMode);
+  stream.phase("recover");
+  attempt = await executeComposition(adapter, mobileTarget, tier, wantWatch, target, machine, displayMode);
   if (attempt.status === 0) {
     state.recovered.push(recoveryCode);
-    return await finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
+    return await finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify);
   }
-  return launchFail(json, adapter, mobileTarget, tier, state, {
+  return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
     code: "SAME_RECOVERY_TWICE",
     message: `launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ""} failed again after ${recoveryCode} recovery \u2014 refusing to loop.`,
     recoverable: false,
@@ -235,6 +312,12 @@ function extensionQuickReattachFailed(output) {
 function extensionRuntimeBlocked(output) {
   return /ERR_BLOCKED_BY_CLIENT|has been blocked by Chromium/u.test(output);
 }
+function extensionBrowserMissing(output) {
+  return /Playwright Chromium is not installed|No compatible Chromium binary selected/u.test(output);
+}
+function extensionProductConfigMissing(output) {
+  return /EXTENSION_PRODUCT_CONFIG_REQUIRED:/u.test(output);
+}
 function mobileProvisioningBlocked(output) {
   return /open-device: configured iOS simulator '.+' does not exist|open-device: no MetaMask bundle found|fast mode requires an installed (?:iOS dev client|Android dev client)/u.test(output);
 }
@@ -274,14 +357,16 @@ function applyLaunchEnvOverrides(options, adapter, mobileTarget, target) {
       return {
         ok: false,
         code: "DEVICE_WRONG_PLATFORM",
-        message: `--device ${device} did not resolve to an Android device for launch android.`
+        message: `--device ${device} did not resolve to an Android device for launch android.`,
+        userAction: `mm-harness status --target ${shellQuote(target)} --all-devices --json`
       };
     }
     if (mobileTarget === "ios" && device && !process.env.IOS_SIMULATOR) {
       return {
         ok: false,
         code: "DEVICE_WRONG_PLATFORM",
-        message: `--device ${device} did not resolve to an iOS simulator for launch ios.`
+        message: `--device ${device} did not resolve to an iOS simulator for launch ios.`,
+        userAction: `mm-harness status --target ${shellQuote(target)} --all-devices --json`
       };
     }
   }
@@ -327,26 +412,29 @@ async function executeComposition(adapter, mobileTarget, tier, wantWatch, target
   }
   return launchExtension(target, tier, wantWatch, displayMode);
 }
-async function finishLaunch(json, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, sidepanelRecoveryAllowed = true) {
+async function finishLaunch(jsonOutput, machine, stream, adapter, mobileTarget, tier, displayMode, target, state, wantWatch, wantVerify, sidepanelRecoveryAllowed = true) {
   if (adapter === "extension" && displayMode === "sidepanel") {
     const sidepanelSh = path.join(runnerDir, "adapters/extension/sidepanel-toggle.sh");
     const sidepanelArgs = ["open"];
     if (process.env.CDP_PORT) sidepanelArgs.push("--cdp-port", process.env.CDP_PORT);
-    if (!json) {
+    if (!machine) {
       console.error(
         `[sidepanel] opening panel beside ${process.env.EXTENSION_START_URL ?? DEFAULT_EXTENSION_DAPP_URL}`
       );
     }
-    const sidepanel = spawnScript(sidepanelSh, sidepanelArgs, target, json, { REPO: target });
+    const sidepanel = spawnScript(sidepanelSh, sidepanelArgs, target, machine, { REPO: target });
     if (sidepanel.status !== 0) {
       const recoveryCode = "chrome.relaunched";
       if (sidepanelRecoveryAllowed && tier === "quick" && extensionRuntimeBlocked(sidepanel.output) && !state.attemptedRecoveries.includes(recoveryCode)) {
         state.attemptedRecoveries.push(recoveryCode);
-        const rebuildAttempt = await executeComposition(adapter, mobileTarget, "build", wantWatch, target, json, displayMode);
+        stream.phase("recover");
+        const rebuildAttempt = await executeComposition(adapter, mobileTarget, "build", wantWatch, target, machine, displayMode);
         if (rebuildAttempt.status === 0) {
           state.recovered.push(recoveryCode);
           return await finishLaunch(
-            json,
+            jsonOutput,
+            machine,
+            stream,
             adapter,
             mobileTarget,
             tier,
@@ -358,7 +446,7 @@ async function finishLaunch(json, adapter, mobileTarget, tier, displayMode, targ
             false
           );
         }
-        return launchFail(json, adapter, mobileTarget, tier, state, {
+        return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
           code: "EXTENSION_RELAUNCH_FAILED",
           message: "sidepanel open found a blocked extension runtime, and clean relaunch failed too.",
           recoverable: false,
@@ -366,7 +454,7 @@ async function finishLaunch(json, adapter, mobileTarget, tier, displayMode, targ
           originalError: rebuildAttempt.output.trim() || void 0
         });
       }
-      return launchFail(json, adapter, mobileTarget, tier, state, {
+      return launchFail(jsonOutput, stream, adapter, mobileTarget, tier, state, target, {
         code: "SIDEPANEL_OPEN_FAILED",
         message: "app launched but opening the side panel failed.",
         recoverable: false,
@@ -376,16 +464,48 @@ async function finishLaunch(json, adapter, mobileTarget, tier, displayMode, targ
       });
     }
   }
+  if (adapter === "extension") {
+    try {
+      await ensureExtensionConsoleCapture(target);
+    } catch (error) {
+      if (!machine) {
+        console.error(`WARN: Extension console capture unavailable: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  }
   if (wantVerify) {
+    stream.phase("verify");
     const verifyArgs = ["verify", "--adapter", adapter, "--target", target];
     if (adapter === "mobile" && mobileTarget) verifyArgs.push("--platform", mobileTarget);
-    if (json) verifyArgs.push("--json");
-    return handleHarness(verifyArgs);
+    if (machine) verifyArgs.push("--json");
+    const exitCode = await handleHarness(verifyArgs);
+    if (stream.enabled) {
+      for (const mutation of state.mutations) stream.mutation(mutation);
+      for (const recovery of state.recovered) stream.recovery(recovery);
+      stream.complete(exitCode === EXIT.ok ? "pass" : "fail", exitCode, {
+        adapter,
+        platform: mobileTarget ?? (adapter === "extension" ? displayMode : null),
+        tier,
+        recovered: state.recovered,
+        mutations: state.mutations
+      });
+    }
+    return exitCode;
   }
-  return launchPass(json, adapter, mobileTarget, tier, displayMode, state);
+  return launchPass(jsonOutput, stream, adapter, mobileTarget, tier, displayMode, state);
 }
-function launchPass(json, adapter, mobileTarget, tier, displayMode, state) {
-  if (json) {
+function launchPass(json, stream, adapter, mobileTarget, tier, displayMode, state) {
+  if (stream.enabled) {
+    for (const mutation of state.mutations) stream.mutation(mutation);
+    for (const recovery of state.recovered) stream.recovery(recovery);
+    stream.complete("pass", EXIT.ok, {
+      adapter,
+      platform: mobileTarget ?? (adapter === "extension" ? displayMode : null),
+      tier,
+      recovered: state.recovered,
+      mutations: state.mutations
+    });
+  } else if (json) {
     console.log(
       JSON.stringify(
         {
@@ -423,8 +543,32 @@ function launchDeviceLabel(mobileTarget) {
   }
   return process.env.IOS_SIMULATOR || process.env.ADB_SERIAL || "booted device";
 }
-function launchFail(json, adapter, mobileTarget, tier, state, failure) {
-  if (json) {
+function launchUsage(json, stream, message, userAction) {
+  stream.error({ code: "USAGE", message, userAction });
+  return usageOut(json, "launch", message, userAction);
+}
+function launchFail(json, stream, adapter, mobileTarget, tier, state, target, failure) {
+  const userAction = failure.userAction ?? `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
+  if (stream.enabled) {
+    for (const mutation of state.mutations) stream.mutation(mutation);
+    for (const recovery of state.recovered) stream.recovery(recovery);
+    stream.error({
+      code: failure.code,
+      message: failure.message,
+      retryable: failure.recoverable,
+      userAction,
+      originalError: failure.originalError ?? null
+    });
+    stream.complete("fail", failure.exitCode, {
+      adapter,
+      platform: mobileTarget ?? null,
+      tier,
+      recovered: state.recovered,
+      mutations: state.mutations,
+      recoverable: failure.recoverable,
+      attemptedRecoveries: state.attemptedRecoveries
+    });
+  } else if (json) {
     console.log(
       JSON.stringify(
         {
@@ -444,7 +588,7 @@ function launchFail(json, adapter, mobileTarget, tier, state, failure) {
             code: failure.code,
             message: failure.message,
             retryable: failure.recoverable,
-            userAction: failure.userAction ?? null,
+            userAction,
             originalError: failure.originalError ?? null
           }
         },
@@ -453,13 +597,13 @@ function launchFail(json, adapter, mobileTarget, tier, state, failure) {
       )
     );
   } else {
-    console.error(
+    console.error(colorHumanMessage(
       `\u2717 launch ${adapter}${mobileTarget ? ` ${mobileTarget}` : ""} failed
   ${failure.message}` + (failure.originalError ? `
   --- original failure ---
-${failure.originalError}` : "") + (failure.userAction ? `
-  Next: ${failure.userAction}` : "")
-    );
+${failure.originalError}` : "") + `
+  Next: ${userAction}`
+    ));
   }
   return failure.exitCode;
 }