@deeeed/metamask-harness 0.16.0 → 0.17.1

package/dist/commands/doctor.js

@@ -81,7 +81,7 @@ async function handleDoctor({ options }) {
     surface.resolveSlotPorts(target);
     const dtResult = applyDeviceTargeting("doctor", adapter, options, { gate: false, rerun: "" });
     if ("code" in dtResult) {
-      return usageOut(json, "doctor", dtResult.message, "mm-harness doctor --fix --adapter mobile --device <adb-serial|simulator-udid>");
+      return usageOut(json, "doctor", dtResult.message, dtResult.userAction);
     }
     applyDoctorRuntimePorts(options);
     const lock = acquireCheckoutLock(target, "doctor-fix");
@@ -98,7 +98,14 @@ async function handleDoctor({ options }) {
     const result2 = createDoctorReport(adapter, target, manifestValidation, actionManifestPath);
     const nextActions = doctorFixNextActions(failed, result2.fixture, adapter, target);
     const status = result2.status === "pass" && failed.length === 0 ? "pass" : "fail";
-    if (json) console.log(JSON.stringify({ ...result2, status, fixed, failed, nextActions }, null, 2));
+    const retryDoctor = `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
+    const fixUserAction = failed.includes("wallet-fixture") ? `choose one wallet fixture source from nextActions, run it, then retry: ${retryDoctor}` : nextActions[0] ?? retryDoctor;
+    const error = status === "fail" ? {
+      code: "DOCTOR_FIX_INCOMPLETE",
+      message: "doctor --fix could not make every required check pass",
+      userAction: fixUserAction
+    } : void 0;
+    if (json) console.log(JSON.stringify({ ...result2, status, fixed, failed, nextActions, ...error ? { error } : {} }, null, 2));
     else {
       console.log(`${status} ${adapter} ${result2.compatibilityMode} manifest=${actionManifestPath} fixed=[${fixed.join(",")}] failed=[${failed.join(",")}]`);
       for (const action of nextActions) console.error(`  Next: ${action}`);
@@ -113,8 +120,9 @@ async function handleDoctor({ options }) {
     surface.resolveSlotPorts(target);
     const dtResult = applyDeviceTargeting("doctor", adapter, options, { gate: false, rerun: "" });
     if ("code" in dtResult) {
-      if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "doctor", adapter, target, error: { code: dtResult.code, message: dtResult.message } }, null, 2));
-      else console.error(`\u2717 doctor: ${dtResult.message}`);
+      if (json) console.log(JSON.stringify({ schemaVersion: 1, command: "doctor", adapter, target, error: { code: dtResult.code, message: dtResult.message, userAction: dtResult.userAction } }, null, 2));
+      else console.error(`\u2717 doctor: ${dtResult.message}
+  Next: ${dtResult.userAction}`);
       return EXIT.usage;
     }
     applyDoctorRuntimePorts(options);
@@ -151,7 +159,9 @@ async function handleDoctor({ options }) {
       printReady
     );
   }
-  if (json) console.log(JSON.stringify({ ...doctorResult, ready: runtime?.decision === "ready", runtime, orphanMetros, capture, devices, additionalReachableDevices }, null, 2));
+  const doctorUserAction = `mm-harness doctor --fix --adapter ${adapter} --target ${shellQuote(target)} --json`;
+  const doctorError = doctorResult.status === "fail" ? { code: "DOCTOR_CHECKS_FAILED", message: "one or more required doctor checks failed", userAction: doctorUserAction } : void 0;
+  if (json) console.log(JSON.stringify({ ...doctorResult, ready: runtime?.decision === "ready", runtime, orphanMetros, capture, devices, additionalReachableDevices, ...doctorError ? { error: doctorError } : {} }, null, 2));
   else {
     const out = (style, text) => color(style, text, { stream: process.stdout });
     const stateStyle = (value, good) => value === good ? "ok" : "warn";
@@ -194,6 +204,7 @@ async function handleDoctor({ options }) {
       if (additionalReachableDevices.length > 0) renderAdditionalReachableDevices(additionalReachableDevices, out);
       if (liveView) renderMobileLiveBlock(deviceView?.devices ?? [], liveView.liveMap, out);
     }
+    if (doctorError) console.log(`  ${out("dim", `Next: ${doctorUserAction}`)}`);
   }
   return doctorResult.status === "pass" ? 0 : 1;
 }
@@ -256,7 +267,9 @@ function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture,
     return EXIT.runtime;
   }
   if (json) {
-    console.log(JSON.stringify({ ...result, ready: live, runtime, orphanMetros, capture, devices, additionalReachableDevices }, null, 2));
+    const userAction = adapter === "extension" ? `mm-harness launch --adapter extension --target ${shellQuote(target)}` : adapter === "core" ? `mm-harness verify --adapter core --target ${shellQuote(target)}` : `mm-harness status --target ${shellQuote(target)} --json`;
+    const error = live ? void 0 : { code: "RUNTIME_NOT_LIVE", message: `${adapter} runtime is not live`, userAction };
+    console.log(JSON.stringify({ ...result, ready: live, runtime, orphanMetros, capture, devices, additionalReachableDevices, ...error ? { error } : {} }, null, 2));
     return live ? EXIT.ok : EXIT.runtime;
   }
   const out = (style, text) => color(style, text, { stream: process.stdout });

package/dist/commands/fixtures.js

@@ -56,6 +56,14 @@ async function handleFixturesLocked(argv, deps) {
   if (sub !== "init" && sub !== "sync" && sub !== "set" && sub !== "generate" && sub !== "finalize") {
     return usageOut(json, "fixtures", "fixtures requires a subcommand: mm-harness fixtures <init|sync|set|generate|finalize>", "mm-harness fixtures init --from <path>   or   mm-harness fixtures init --dev");
   }
+  if (sub !== "init" && (flag(options, "dev") || flag(options, "force") || str(options, "from"))) {
+    return usageOut(
+      json,
+      "fixtures",
+      "--dev, --from, and --force belong to fixtures init; they do not apply a fixture.",
+      "mm-harness fixtures init --dev && mm-harness fixtures set"
+    );
+  }
   const target = targetOf(options);
   const adapter = resolveAdapter(options, target);
   if (!adapter) {
@@ -65,7 +73,7 @@ async function handleFixturesLocked(argv, deps) {
   surface.resolveSlotPorts(target);
   const dtResult = applyDeviceTargeting("fixtures", adapter, options, { gate: false, rerun: "" });
   if ("code" in dtResult) {
-    return usageOut(json, "fixtures", dtResult.message, "mm-harness fixtures set --adapter mobile --device <adb-serial|simulator-udid>");
+    return usageOut(json, "fixtures", dtResult.message, dtResult.userAction);
   }
   if (sub === "generate") return fixturesGenerate(adapter, target, options, json);
   if (sub === "finalize") return fixturesFinalize(adapter, target, options, json);
@@ -96,6 +104,14 @@ async function handleFixturesLocked(argv, deps) {
     return exitCode;
   }
   const fixturePath = path.resolve(str(options, "fixture") ?? process.env.RECIPE_WALLET_FIXTURE ?? canonicalFixture);
+  if (!fs.existsSync(fixturePath)) {
+    return usageOut(
+      json,
+      "fixtures",
+      `no wallet fixture at ${fixturePath}.`,
+      "mm-harness fixtures init --dev && mm-harness fixtures set"
+    );
+  }
   process.stderr.write(`\u2192 fixtures set ${adapter} \u2014 connecting bridge + applying wallet fixture (can take ~30s)\u2026
 `);
   let status;
@@ -129,14 +145,6 @@ async function handleFixturesLocked(argv, deps) {
       console.error(`  Next: ${retryHint}`);
     }
   } else {
-    if (!fs.existsSync(fixturePath)) {
-      return usageOut(
-        json,
-        "fixtures",
-        `no wallet fixture at ${fixturePath}.`,
-        "create it (or pass --fixture <path>), then re-run: mm-harness fixtures set"
-      );
-    }
     const previousFixtureEnv = process.env.RECIPE_WALLET_FIXTURE;
     process.env.RECIPE_WALLET_FIXTURE = fixturePath;
     try {
@@ -150,7 +158,7 @@ async function handleFixturesLocked(argv, deps) {
       console.error(`  Next: ${retryHint}`);
     }
   }
-  const teaching = `Wallet fixture applied.  Want different accounts? Edit: ${canonicalFixture}`;
+  const teaching = status === "pass" ? `Wallet fixture applied.  Want different accounts? Edit: ${canonicalFixture}` : "Wallet fixture was not applied.";
   if (json) {
     console.log(
       JSON.stringify(
@@ -174,7 +182,7 @@ async function handleFixturesLocked(argv, deps) {
         2
       )
     );
-  } else {
+  } else if (status === "pass") {
     console.error(teaching);
   }
   return status === "pass" ? EXIT.ok : EXIT.runtime;

package/dist/commands/last.js

@@ -0,0 +1,52 @@
+import { readCommandJournal } from "../command-journal.js";
+import { EXIT } from "./shared.js";
+import {
+  optionFlag,
+  optionString,
+  targetPath
+} from "./parse-args.js";
+async function handleLast({ options }) {
+  const target = targetPath(options);
+  const { file, record } = readCommandJournal(target, optionString(options, "runtimeDir"));
+  const json = optionFlag(options, "json");
+  if (!record) {
+    const message = `no resumability journal exists for ${target}`;
+    const userAction = "run a proof or runtime command in this checkout, then re-run mm-harness last --json";
+    if (json) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        command: "last",
+        target,
+        journalPath: file,
+        status: "fail",
+        exitCode: EXIT.runtime,
+        error: { code: "LAST_NOT_FOUND", message, userAction }
+      }, null, 2));
+    } else {
+      console.error(`\u2717 mm-harness last: ${message}
+  Next: ${userAction}`);
+    }
+    return EXIT.runtime;
+  }
+  if (json) {
+    console.log(JSON.stringify({
+      schemaVersion: 1,
+      command: "last",
+      target,
+      journalPath: file,
+      status: "pass",
+      exitCode: EXIT.ok,
+      last: record
+    }, null, 2));
+  } else {
+    const end = record.finishedAt ?? "still running or interrupted";
+    console.log(`${record.verdict.toUpperCase()} ${record.command} (exit ${record.exitCode ?? "pending"})`);
+    console.log(`started: ${record.startedAt}`);
+    console.log(`finished: ${end}`);
+    if (record.evidencePaths.length > 0) console.log(`evidence: ${record.evidencePaths.join(", ")}`);
+  }
+  return EXIT.ok;
+}
+export {
+  handleLast
+};

package/dist/commands/launch/index.js

@@ -15,7 +15,8 @@ import {
   spawnScript,
   str,
   targetOf,
-  usageOut
+  usageOut,
+  writeInteractiveProgress
 } from "../shared.js";
 import {
   RECOVERY_CODE,
@@ -33,6 +34,8 @@ 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";
 const LAUNCH_BOOLEANS = /* @__PURE__ */ new Set([
   "build",
   "watch",
@@ -40,30 +43,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 checkoutBusyOut(json, "launch", lock.message, lock.path);
-  }
   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");
@@ -72,15 +103,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"
     );
@@ -90,15 +122,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"}`
       );
@@ -106,7 +138,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") {
@@ -115,44 +147,55 @@ 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(
       `\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 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,
@@ -166,12 +209,13 @@ 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 (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,
@@ -181,12 +225,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,
@@ -195,7 +240,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,
@@ -206,7 +251,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,
@@ -217,12 +262,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,
@@ -275,14 +321,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`
       };
     }
   }
@@ -328,26 +376,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,
@@ -359,7 +410,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,
@@ -367,7 +418,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,
@@ -377,16 +428,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(
         {
@@ -424,8 +507,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(
         {
@@ -445,7 +552,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
           }
         },
@@ -458,8 +565,8 @@ function launchFail(json, adapter, mobileTarget, tier, state, failure) {
       `\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;