@deeeed/metamask-harness 0.14.4 → 0.14.7

package/CHANGELOG.md

@@ -1,6 +1,29 @@
 # Changelog
 
-## Unreleased
+## 0.14.7 - 2026-07-10
+
+### Changed
+- `doctor --print-ready` now implies the exit-coded live probe — Farmslot `health_check` hooks need only `--print-ready`, not `--expect-live --print-ready`.
+- Mobile `--print-ready` uses bridge `walletState` (unlocked + live bridge), not React Navigation route names; mobile `ready_indicator` is `OK`.
+- Removed `metamask-recipe` install symlinks from adapter inject paths (no compat aliases).
+- `doctor --print-ready` rejects `--json` (stdout is reserved for the Farmslot indicator line).
+
+### Fixed
+- Mobile `surface.runtimeStatus` infers Android from `ADB_SERIAL` / `ANDROID_SERIAL` when present.
+
+## 0.14.6 - 2026-07-10
+
+### Added
+- `mm-harness doctor --print-ready` — Farmslot `health_check` mode: prints `health.ready_indicator` on stdout (`extension`/`mobile`: `OK`; `core`: `ready`).
+- `doctor --expect-live` — exit-coded liveness gate without indicator output (prepare recovery and other pass/fail callers).
+
+## 0.14.5 - 2026-07-10
+
+### Fixed
+- Extension `ensure-browser` closes disposable New Tab / blank / extensions pages after reopen, matching reattach/ensure-ready hygiene.
+- Extension slot browser titles are stamped through one shared helper (`adapters/extension/lib/slot-title.cjs`) with a persistent `MutationObserver`, and re-applied after `ensureExtensionReady` open/prune/reopen so relaunch and recipe paths keep `<slot-id> — MetaMask` instead of a bare MetaMask window.
+- Extension slot-title contract test is hermetic (local CDP/WebSocket stub + fake DOM); Playwright and CDP stamps share one function source so they cannot drift.
+- Extension inject copies `scripts/lib/slot-title.cjs` with the other installed helpers so reattach/readiness/reopen do not `MODULE_NOT_FOUND` on injected checkouts.
 
 ## 0.14.4 - 2026-07-09
 

package/adapters/extension/ensure-browser.sh

@@ -358,8 +358,9 @@ const resumeWebpack = () => {
   const page = ctx.pages().find(p => p.url().includes('chrome-extension://')) || ctx.pages()[0];
   await page.goto(homeUrl, { waitUntil: 'load', timeout: 15000 });
 
-  // Set window title to slot ID
-  await page.evaluate((id) => { document.title = id + ' \u2014 ' + document.title; }, SLOT_ID);
+  // Set window title to slot ID (persists across SPA navigations)
+  const { applyPersistentSlotTitle } = require(path.join('${SCRIPT_DIR}', 'lib/slot-title.cjs'));
+  await page.evaluate(applyPersistentSlotTitle, SLOT_ID);
 
   // Wait for runtime state to settle, then unlock if needed.
   const unlockSelector = '[data-testid=\"unlock-password\"]';
@@ -393,10 +394,25 @@ const resumeWebpack = () => {
     console.log('[reopen] Screen: ' + page.url());
   }
 
-  // Close extra extension tabs
+  // Close extra extension tabs and disposable Chrome pages (New Tab / blank).
   for (const p of ctx.pages()) {
-    if (p !== page && p.url().includes('chrome-extension://')) await p.close().catch(() => {});
+    if (p === page) continue;
+    const url = p.url();
+    if (url.includes('chrome-extension://')) {
+      await p.close().catch(() => {});
+      continue;
+    }
+    if (
+      url === 'chrome://newtab/' ||
+      url === 'chrome://new-tab-page/' ||
+      url.startsWith('chrome://new-tab-page') ||
+      url === 'about:blank' ||
+      url === 'chrome://extensions/'
+    ) {
+      await p.close().catch(() => {});
+    }
   }
+  await page.bringToFront().catch(() => {});
 
   fs.writeFileSync(path.join(AGENT_DIR, 'extension.id'), extId);
   console.log('[reopen] Ready \u2014 ' + SLOT_ID + (CDP_PORT ? ' CDP:' + CDP_PORT : ''));

package/adapters/extension/inject.mjs

@@ -130,6 +130,7 @@ copyFile(path.join(runnerDir, 'adapters/shared/tmux-session.sh'), path.join(harn
 copyFile(path.join(runnerDir, 'adapters/shared/tmux-viewer.sh'), path.join(harnessDir, 'scripts/lib/tmux-viewer.sh'));
 copyFile(path.join(runnerDir, 'adapters/shared/log-tui.mjs'), path.join(harnessDir, 'scripts/lib/log-tui.mjs'));
 copyFile(path.join(runnerDir, 'adapters/extension/lib/extension-id.cjs'), path.join(harnessDir, 'scripts/lib/extension-id.cjs'));
+copyFile(path.join(runnerDir, 'adapters/extension/lib/slot-title.cjs'), path.join(harnessDir, 'scripts/lib/slot-title.cjs'));
 makeExecutableTree(path.join(harnessDir, 'scripts'));
 fs.writeFileSync(path.join(harnessDir, 'installed-scripts.sha256'), `${dirContentHash(path.join(harnessDir, 'scripts'))}\n`);
 

package/adapters/extension/lib/slot-title.cjs

@@ -0,0 +1,294 @@
+'use strict';
+
+/**
+ * Operator slot title for headed extension Chrome.
+ *
+ * Chrome's window label is the active tab's document.title. Farmslot stamps
+ * home.html to "<slot-id> — MetaMask" so operators can tell which slot owns a
+ * window when several farms run side by side.
+ *
+ * Stamping is best-effort: missing slot context or an uninspectable tab must
+ * never fail launch/readiness. A MutationObserver keeps the prefix across
+ * MetaMask SPA title resets.
+ */
+
+const fs = require('node:fs');
+const http = require('node:http');
+const path = require('node:path');
+
+function sanitizeSlotId(value) {
+  const slotId = typeof value === 'string' ? value.trim() : '';
+  return /^[A-Za-z0-9._:-]{1,64}$/u.test(slotId) ? slotId : '';
+}
+
+function readSlotId(target, runtimeDir) {
+  for (const key of ['RECIPE_SLOT_ID', 'SLOT_ID', 'FARMSLOT_SLOT_ID']) {
+    const value = sanitizeSlotId(process.env[key]);
+    if (value) return value;
+  }
+  if (!target || !runtimeDir) return '';
+  try {
+    const runtimeContext = JSON.parse(
+      fs.readFileSync(path.join(target, runtimeDir, 'agentic-runtime.json'), 'utf8'),
+    );
+    return sanitizeSlotId(runtimeContext.slotId);
+  } catch {
+    // Standalone harness users do not need a custom browser title.
+    return '';
+  }
+}
+
+/**
+ * Playwright page.evaluate callback. Must stay a plain function (no closure)
+ * so Playwright can serialize it into the page.
+ */
+function applyPersistentSlotTitle(slot) {
+  // Inline sanitize — this function is serialized into the page for Playwright
+  // and CDP, so it cannot call Node helpers.
+  const id =
+    typeof slot === 'string' && /^[A-Za-z0-9._:-]{1,64}$/u.test(slot.trim())
+      ? slot.trim()
+      : '';
+  if (!id) return document.title;
+  window.__farmslotSlotId = id;
+
+  const stripSlotPrefixes = (title) => {
+    let base = String(title || 'MetaMask');
+    // Accept em dash, en dash, or hyphen — historical stampers mixed them.
+    for (let i = 0; i < 32; i += 1) {
+      const stripped = base.replace(/^.+?\s+[—–-]\s+/u, '');
+      if (stripped === base) break;
+      base = stripped;
+    }
+    return base || 'MetaMask';
+  };
+
+  const desiredTitle = () => {
+    const id = window.__farmslotSlotId;
+    if (!id) return document.title;
+    return `${id} — ${stripSlotPrefixes(document.title)}`;
+  };
+
+  const setTitle = () => {
+    if (window.__farmslotSlotTitleLock) {
+      window.__farmslotSlotTitlePending = true;
+      return;
+    }
+    const next = desiredTitle();
+    if (document.title === next) return;
+    window.__farmslotSlotTitleLock = true;
+    try {
+      document.title = next;
+    } finally {
+      // Release after the title mutation is delivered so the observer cannot
+      // re-enter and stack prefixes while React also mutates the DOM. If a
+      // mutation arrived while locked, re-apply once after unlock.
+      queueMicrotask(() => {
+        window.__farmslotSlotTitleLock = false;
+        if (window.__farmslotSlotTitlePending) {
+          window.__farmslotSlotTitlePending = false;
+          setTitle();
+        }
+      });
+    }
+  };
+
+  setTitle();
+  if (!window.__farmslotSlotTitleObserver) {
+    let node = document.querySelector('title');
+    if (!node) {
+      node = document.createElement('title');
+      (document.head || document.documentElement).appendChild(node);
+    }
+    window.__farmslotSlotTitleObserver = new MutationObserver(setTitle);
+    // Observe only the <title> element — watching head/documentElement with
+    // subtree:true re-fires on every React DOM mutation and can livelock CDP.
+    window.__farmslotSlotTitleObserver.observe(node, {
+      childList: true,
+      characterData: true,
+      subtree: true,
+    });
+  }
+  return document.title;
+}
+
+function buildStampExpression(slotId) {
+  const slot = sanitizeSlotId(slotId);
+  if (!slot) return 'document.title';
+  // Single source of truth: serialize the Playwright callback for CDP evaluate.
+  return `(${applyPersistentSlotTitle.toString()})(${JSON.stringify(slot)})`;
+}
+
+function assertLocalUrl(url) {
+  if (!/^http:\/\/127\.0\.0\.1:\d+\//u.test(url)) {
+    throw new Error(`slot-title: refusing non-local URL: ${url}`);
+  }
+}
+
+function assertLocalWebSocketUrl(url) {
+  if (!/^ws:\/\/(?:127\.0\.0\.1|localhost):\d+\//u.test(String(url))) {
+    throw new Error(`slot-title: refusing non-local websocket URL: ${url}`);
+  }
+}
+
+function httpJson(url, timeoutMs = 3000) {
+  assertLocalUrl(url);
+  return new Promise((resolve, reject) => {
+    const req = http.get(url, (res) => {
+      let data = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+      res.on('end', () => {
+        try {
+          resolve(JSON.parse(data));
+        } catch (err) {
+          reject(new Error(`invalid JSON from ${url}: ${err.message}`));
+        }
+      });
+    });
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error(`timeout from ${url}`));
+    });
+    req.on('error', reject);
+  });
+}
+
+function resolveWebSocket(target) {
+  try {
+    // Prefer the target checkout's ws, then the harness install.
+    const { createRequire } = require('node:module');
+    const req = createRequire(__filename);
+    if (target) {
+      try {
+        return req(req.resolve('ws', { paths: [target] }));
+      } catch {
+        // Fall through to harness / global.
+      }
+    }
+    return req('ws');
+  } catch {
+    return typeof WebSocket === 'function' ? WebSocket : null;
+  }
+}
+
+async function cdpEvaluate(target, webSocketDebuggerUrl, expression, timeoutMs = 5000) {
+  assertLocalWebSocketUrl(webSocketDebuggerUrl);
+  const WebSocketImpl = resolveWebSocket(target);
+  if (!WebSocketImpl) return { skipped: true, reason: 'WebSocket unavailable' };
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocketImpl(webSocketDebuggerUrl);
+    const timer = setTimeout(() => {
+      try {
+        ws.close();
+      } catch {
+        // Best-effort timeout cleanup.
+      }
+      reject(new Error('timeout evaluating extension page via CDP'));
+    }, timeoutMs);
+    const onOpen = () => {
+      ws.send(
+        JSON.stringify({
+          id: 1,
+          method: 'Runtime.evaluate',
+          params: { expression, awaitPromise: true, returnByValue: true },
+        }),
+      );
+    };
+    const onMessage = (event) => {
+      const raw = event?.data ?? event;
+      const msg = JSON.parse(Buffer.isBuffer(raw) ? raw.toString('utf8') : String(raw));
+      if (msg.id !== 1) return;
+      clearTimeout(timer);
+      ws.close();
+      if (msg.error) {
+        reject(new Error(msg.error.message || JSON.stringify(msg.error)));
+        return;
+      }
+      resolve(msg.result?.result?.value ?? null);
+    };
+    const onError = (err) => {
+      clearTimeout(timer);
+      reject(new Error(`CDP websocket error while stamping slot title: ${err?.message || err || 'unknown'}`));
+    };
+    if (typeof ws.on === 'function') {
+      ws.on('open', onOpen);
+      ws.on('message', onMessage);
+      ws.on('error', onError);
+    } else {
+      ws.addEventListener('open', onOpen);
+      ws.addEventListener('message', onMessage);
+      ws.addEventListener('error', onError);
+    }
+  });
+}
+
+function isHomePage(target, extensionId) {
+  if (!target || target.type !== 'page' || typeof target.url !== 'string') return false;
+  if (!target.url.startsWith(`chrome-extension://${extensionId}/`)) return false;
+  return target.url.includes('/home.html');
+}
+
+/**
+ * Stamp every inspectable home.html tab for this extension over CDP.
+ * Attached tabs (no webSocketDebuggerUrl) are skipped — another client owns them.
+ */
+async function stampHomeTabsViaCdp(options) {
+  const {
+    target = process.cwd(),
+    cdpPort,
+    extensionId,
+    slotId: slotIdOption,
+    runtimeDir,
+  } = options || {};
+  const slotId = sanitizeSlotId(slotIdOption) || readSlotId(target, runtimeDir);
+  const empty = { slotId: slotId || '', stamped: 0, skipped: 0, titles: [] };
+  if (!slotId || !cdpPort || !extensionId) return empty;
+
+  let targets;
+  try {
+    targets = await httpJson(`http://127.0.0.1:${cdpPort}/json/list`);
+  } catch {
+    return empty;
+  }
+  if (!Array.isArray(targets)) return empty;
+
+  const homes = targets.filter((t) => isHomePage(t, extensionId));
+  const titles = [];
+  let stamped = 0;
+  let skipped = 0;
+  const expression = buildStampExpression(slotId);
+
+  for (const home of homes) {
+    if (typeof home.webSocketDebuggerUrl !== 'string') {
+      skipped += 1;
+      continue;
+    }
+    try {
+      const title = await cdpEvaluate(target, home.webSocketDebuggerUrl, expression);
+      if (title && typeof title === 'object' && title.skipped) {
+        skipped += 1;
+        continue;
+      }
+      if (typeof title === 'string') {
+        titles.push(title);
+        stamped += 1;
+      } else {
+        skipped += 1;
+      }
+    } catch {
+      skipped += 1;
+    }
+  }
+
+  return { slotId, stamped, skipped, titles };
+}
+
+module.exports = {
+  sanitizeSlotId,
+  readSlotId,
+  applyPersistentSlotTitle,
+  buildStampExpression,
+  stampHomeTabsViaCdp,
+};

package/adapters/extension/readiness.mjs

@@ -22,6 +22,10 @@ import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
 const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const {
+  readSlotId: readSlotIdFromLib,
+  buildStampExpression,
+} = require(path.join(scriptDir, 'lib/slot-title.cjs'));
 
 function pathDefault(key) {
   for (const candidate of [
@@ -101,25 +105,7 @@ function readExpectedExtensionId(target) {
 }
 
 function readSlotId(target) {
-  for (const key of ['RECIPE_SLOT_ID', 'SLOT_ID', 'FARMSLOT_SLOT_ID']) {
-    const value = sanitizeSlotId(process.env[key]);
-    if (value) return value;
-  }
-  try {
-    const runtimeContext = JSON.parse(fs.readFileSync(path.join(target, recipeRuntimeDir(), 'agentic-runtime.json'), 'utf8'));
-    const value = sanitizeSlotId(runtimeContext.slotId);
-    if (value) {
-      return value;
-    }
-  } catch {
-    // No slot context: standalone harness users do not need a custom browser title.
-  }
-  return '';
-}
-
-function sanitizeSlotId(value) {
-  const slotId = typeof value === 'string' ? value.trim() : '';
-  return /^[A-Za-z0-9._:-]{1,64}$/u.test(slotId) ? slotId : '';
+  return readSlotIdFromLib(target, recipeRuntimeDir());
 }
 
 function writeExtensionId(target, extensionId) {
@@ -407,16 +393,9 @@ async function inspectCdp(target, cdpPort, expectedExtensionId, expectedServiceW
       const stampedTitle = await cdpEvaluate(
         target,
         pageTarget.webSocketDebuggerUrl,
-        `(() => {
-          const slot = ${JSON.stringify(slotId)};
-          const current = document.title || 'MetaMask';
-          const base = current.replace(/^.+?\\s+—\\s+/, '') || 'MetaMask';
-          const next = slot + ' — ' + base;
-          if (document.title !== next) document.title = next;
-          return document.title;
-        })()`,
+        buildStampExpression(slotId),
       );
-      if (stampedTitle && !stampedTitle.skipped) {
+      if (typeof stampedTitle === 'string') {
         ui.title = stampedTitle;
         ui.slotTitleApplied = true;
       }

package/adapters/extension/reattach.sh

@@ -123,6 +123,7 @@ let chromium; try { chromium = require('@playwright/test').chromium; } catch { c
 const fs = require('node:fs');
 const path = require('node:path');
 const { extensionIdFromManifestFile } = require(path.join(process.env.SCRIPT_DIR, 'lib/extension-id.cjs'));
+const { readSlotId, applyPersistentSlotTitle } = require(path.join(process.env.SCRIPT_DIR, 'lib/slot-title.cjs'));
 
 const port = process.env.CDP_PORT;
 const target = process.env.TARGET;
@@ -131,22 +132,13 @@ const runtimeDistDir = process.env.RUNTIME_DIST_DIR;
 const startUrl = process.env.START_URL || '';
 const settleMs = Number(process.env.SETTLE_MS || '8000') || 8000;
 const displayMode = process.env.DISPLAY_MODE || 'fullscreen';
-const slotId = process.env.RECIPE_SLOT_ID || process.env.SLOT_ID || process.env.FARMSLOT_SLOT_ID || readRuntimeSlotId();
+const slotId = readSlotId(target, runtimeDir);
 
 if (!runtimeDir || !runtimeDistDir) {
   console.error('reattach: resolved runtime paths were not provided.');
   process.exit(2);
 }
 
-function readRuntimeSlotId() {
-  try {
-    const runtimeContext = JSON.parse(fs.readFileSync(path.join(target, runtimeDir, 'agentic-runtime.json'), 'utf8'));
-    return typeof runtimeContext.slotId === 'string' ? runtimeContext.slotId.trim() : '';
-  } catch {
-    return '';
-  }
-}
-
 function extensionIdFromRuntimeDist() {
   return extensionIdFromManifestFile(path.join(target, runtimeDir, runtimeDistDir, 'manifest.json'));
 }
@@ -204,11 +196,7 @@ async function connect() {
 
 async function stampSlotTitle(page) {
   if (!slotId || !page) return;
-  await page.evaluate((slot) => {
-    const base = (document.title || 'MetaMask').replace(/^.+?\s+—\s+/, '') || 'MetaMask';
-    const next = `${slot} — ${base}`;
-    if (document.title !== next) document.title = next;
-  }, slotId).catch(() => {
+  await page.evaluate(applyPersistentSlotTitle, slotId).catch(() => {
     // Best-effort operator affordance; reload success is verified by CDP state.
   });
 }
@@ -285,6 +273,16 @@ async function closePages(context, predicate) {
       .catch(() => { /* wallet home is best-effort; the reload already applied */ });
   }
   await stampSlotTitle(home);
+  for (const page of allPages(context)) {
+    const url = page.url();
+    if (
+      page !== home &&
+      url.startsWith(`chrome-extension://${extId}/`) &&
+      url.includes('/home.html')
+    ) {
+      await stampSlotTitle(page);
+    }
+  }
   await closeDisposableChromeTabs(context);
   if (startUrl) {
     const dapp = allPages(context)

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

@@ -1,5 +1,11 @@
+import { createRequire } from "node:module";
 import path from "node:path";
+import { recipeRuntimeDir, runnerDir } from "../../paths.js";
 import { resolveExtensionId } from "./extension-id.js";
+const requireFromHarness = createRequire(import.meta.url);
+const { stampHomeTabsViaCdp } = requireFromHarness(
+  path.join(runnerDir, "adapters/extension/lib/slot-title.cjs")
+);
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 async function jsonList(port) {
   for (let attempt = 0; attempt < 3; attempt += 1) {
@@ -161,12 +167,25 @@ async function ensureExtensionReady(target, options) {
       health = await checkHealth();
     }
   }
+  let slotTitle;
+  if (after >= 1) {
+    const stamp = await stampHomeTabsViaCdp({
+      target: resolved,
+      cdpPort,
+      extensionId,
+      runtimeDir: recipeRuntimeDir()
+    });
+    if (stamp.slotId || stamp.stamped > 0 || stamp.skipped > 0) {
+      slotTitle = stamp;
+    }
+  }
   const ready = health.status === "PASS" && after === 1;
   return base({
     extensionId,
     opened,
     action,
     homeTabs: { before, closed, after },
+    ...slotTitle ? { slotTitle } : {},
     ready,
     reasonCode: ready ? "ready" : after !== 1 ? "tab-count" : "unhealthy",
     health

package/dist/adapters/mobile/surface.js

@@ -12,7 +12,8 @@ const mobileSurface = {
   },
   async runtimeStatus(target) {
     const watcherPort = process.env.WATCHER_PORT ? parseInt(process.env.WATCHER_PORT, 10) : void 0;
-    const report = await mobileRuntimeStatus(target, { watcherPort });
+    const platform = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL ? "android" : "ios";
+    const report = await mobileRuntimeStatus(target, { watcherPort, platform });
     const runwayProvisioned = hasRunwayProvisionBaseline(target);
     const depsPending = runwayProvisioned && report.checks?.deps?.status !== "current";
     return {

package/dist/cli-commands.js

@@ -16,7 +16,7 @@ const SPEC = {
     { name: "debug", aliases: ["devtools", "inspect"], desc: "Open DevTools UI", flags: ["--json", "--no-open"] },
     { name: "fixtures", desc: "Manage the canonical wallet fixture (sync/set/generate)", args: ["sync", "set", "generate"], flags: ["--fixture", "--out", "--adapter", "--target", "--device", "--json"] },
     { name: "actions", desc: "List runnable recipe actions", flags: ["--json"] },
-    { name: "doctor", desc: "Check harness/orchestration health", flags: ["--json", "--target", "--adapter", "--runtime-dir", "--expect-live", "--cdp-port", "--device"] },
+    { name: "doctor", desc: "Check harness/orchestration health", flags: ["--json", "--target", "--adapter", "--runtime-dir", "--expect-live", "--print-ready", "--cdp-port", "--device"] },
     { name: "run", desc: "Execute a proof recipe (path or library name, e.g. run perps.smoke)", args: ["recipe.json|name"], flags: ["--list", "--device"] },
     { name: "recipe-quality", desc: "Build the recipe-quality artifact from compact JSON", args: ["build"], flags: ["--input", "--output", "--json"] },
     { name: "interactive", aliases: ["menu"], desc: "Interactive command menu" },

package/dist/commands/doctor.js

@@ -15,6 +15,7 @@ import {
   renderMobileDeviceList,
   renderMobileLiveBlock
 } from "./mobile-device-view.js";
+import { farmslotReadyIndicator } from "./farmslot-ready.js";
 import { ADAPTER_DETECT_NEXT, EXIT, usageOut } from "./shared.js";
 import {
   actionManifestPathOption,
@@ -40,7 +41,8 @@ async function handleDoctor({ options }) {
   applyRuntimeDirOption(options);
   const target = targetPath(options);
   const json = optionFlag(options, "json");
-  const expectLive = optionFlag(options, "expectLive");
+  const printReady = optionFlag(options, "printReady");
+  const expectLive = optionFlag(options, "expectLive") || printReady;
   const allDevices = optionFlag(options, "allDevices");
   const platformOption = optionString(options, "platform");
   const explicitAdapter = optionString(options, "adapter") ?? (platformOption === "ios" || platformOption === "android" ? "mobile" : platformOption);
@@ -49,6 +51,14 @@ async function handleDoctor({ options }) {
     return usageOut(json, "doctor", `could not detect the MetaMask repo type for ${target}`, ADAPTER_DETECT_NEXT);
   }
   assertAdapter(adapter);
+  if (printReady && json) {
+    return usageOut(
+      json,
+      "doctor",
+      "--print-ready owns stdout for Farmslot health_check; drop --json (use --expect-live --json for the doctor envelope)",
+      "mm-harness doctor --print-ready --adapter <adapter> --target <path>"
+    );
+  }
   const actionManifestPath = actionManifestPathOption(options, adapter);
   const manifest = loadActionManifest(adapter, optionString(options, "actionManifest"));
   const manifestValidation = await validateManifest(manifest);
@@ -80,7 +90,20 @@ async function handleDoctor({ options }) {
   const liveView = deviceView ? await mobileDeviceLiveView(target, deviceView) : null;
   const devices = liveView?.devicesWithLive ?? deviceView?.devices ?? [];
   const additionalReachableDevices = liveView?.additionalReachableDevices ?? [];
-  if (expectLive) return emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, devices, additionalReachableDevices, json);
+  if (expectLive) {
+    return emitExpectLive(
+      adapter,
+      target,
+      runtime,
+      result,
+      orphanMetros,
+      capture,
+      devices,
+      additionalReachableDevices,
+      json,
+      printReady
+    );
+  }
   if (json) console.log(JSON.stringify({ ...result, runtime, orphanMetros, capture, devices, additionalReachableDevices }, null, 2));
   else {
     const out = (style, text) => color(style, text, { stream: process.stdout });
@@ -119,8 +142,28 @@ async function handleDoctor({ options }) {
   }
   return result.status === "pass" ? 0 : 1;
 }
-function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, devices, additionalReachableDevices, json) {
+function emitExpectLiveVerdict(adapter, target, runtime, verdict) {
+  const out = (style, text) => color(style, text, { stream: process.stderr });
+  const detail = runtime ? `${runtime.decision}${runtime.reasonCode ? ` (${runtime.reasonCode})` : ""}` : "runtime probe unavailable";
+  console.error(`${out("err", verdict)} ${out("bold", adapter)} ${detail} ${out("dim", target)}`);
+  for (const reason of runtime?.reasons ?? []) console.error(`  ${out("dim", reason)}`);
+  console.error(`  Next: ${getAdapterSurface(adapter).hints.relaunch}`);
+}
+function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture, devices, additionalReachableDevices, json, printReady) {
   const live = runtime?.decision === "ready";
+  if (printReady) {
+    if (live) {
+      const indicator = farmslotReadyIndicator(adapter, devices);
+      if (indicator) {
+        console.log(indicator);
+        return EXIT.ok;
+      }
+      emitExpectLiveVerdict(adapter, target, runtime, "not-ready");
+      return EXIT.runtime;
+    }
+    emitExpectLiveVerdict(adapter, target, runtime, "not-live");
+    return EXIT.runtime;
+  }
   if (json) {
     console.log(JSON.stringify({ ...result, runtime, orphanMetros, capture, devices, additionalReachableDevices }, null, 2));
     return live ? EXIT.ok : EXIT.runtime;
@@ -130,10 +173,7 @@ function emitExpectLive(adapter, target, runtime, result, orphanMetros, capture,
     console.log(`${out("ok", "live")} ${out("bold", adapter)} runtime ready`);
     return EXIT.ok;
   }
-  const detail = runtime ? `${runtime.decision}${runtime.reasonCode ? ` (${runtime.reasonCode})` : ""}` : "runtime probe unavailable";
-  console.error(`${out("err", "not-live")} ${out("bold", adapter)} ${detail} ${out("dim", target)}`);
-  for (const reason of runtime?.reasons ?? []) console.error(`  ${out("dim", reason)}`);
-  console.error(`  Next: ${getAdapterSurface(adapter).hints.relaunch}`);
+  emitExpectLiveVerdict(adapter, target, runtime, "not-live");
   return EXIT.runtime;
 }
 function captureHelperHealth() {

package/dist/commands/farmslot-ready.js

@@ -0,0 +1,25 @@
+function selectedDevice(devices) {
+  return devices.find((d) => d.selected) ?? devices[0];
+}
+function mobileWalletReady(device) {
+  if (device.liveState === "no-bridge" || device.liveState === "bridge-absent") return false;
+  return device.walletState === "unlocked";
+}
+function farmslotReadyIndicator(adapter, devices) {
+  switch (adapter) {
+    case "extension":
+      return "OK";
+    case "core":
+      return "ready";
+    case "mobile": {
+      const device = selectedDevice(devices);
+      if (!device) return "";
+      return mobileWalletReady(device) ? "OK" : "";
+    }
+    default:
+      return "";
+  }
+}
+export {
+  farmslotReadyIndicator
+};

package/dist/commands/parse-args.js

@@ -29,6 +29,7 @@ function parseArgs(argv, command) {
     "force",
     "resolveOnly",
     "expectLive",
+    "printReady",
     "fast",
     "allDevices",
     "help"

package/dist/mm-harness-cli.js

@@ -171,19 +171,20 @@ Example:
   sections so there is no hunting for files.
 
   --fix                              Repair the overlay/runtime-context WITHOUT launching (no fixture reseed); --json adds fixed[]/failed[]
-  --expect-live                      Exit 0 iff the runtime is live (extension: watcher+CDP; mobile: Metro+bridge; core: deps), non-zero + teaching escape otherwise
+  --expect-live                      Exit-coded liveness gate only (human verdict on stderr). Use without --print-ready when callers need pass/fail without a Farmslot indicator line
+  --print-ready                      Farmslot health_check mode: implies --expect-live and prints health.ready_indicator on stdout (extension/mobile: OK; core: ready)
   --cdp-port <port>                  Extension CDP port for the liveness probe (env: CDP_PORT / RECIPE_CDP_PORT)
   --device <udid|serial|name>        Mobile only: target this device (env: IOS_SIMULATOR / ADB_SERIAL). doctor reports the connected devices; it never gates on ambiguity.
   --all-devices                      Mobile only: show every connected device instead of the slot-scoped target
   --adapter <mobile|extension|core>  Target adapter (auto-detected inside a checkout)
   --target <path>                    Checkout path (default: cwd)
   --runtime-dir <dir>                Runtime dir containing agentic-runtime.json (relative to target)
-  --json                             Machine-readable output
+  --json                             Machine-readable output (incompatible with --print-ready)
 
 Example:
   mm-harness doctor
   mm-harness doctor --fix --json
-  mm-harness doctor --adapter extension --target /path/to/checkout --cdp-port 6662 --expect-live
+  mm-harness doctor --adapter extension --target /path/to/checkout --cdp-port 6662 --print-ready
   mm-harness doctor --adapter mobile --target /path/to/checkout`
   },
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.14.4",
+  "version": "0.14.7",
   "type": "module",
   "bin": {
     "mm-harness": "bin/mm-harness"
@@ -20,7 +20,8 @@
     "@farmslot/protocol": "^0.7.6",
     "@farmslot/recipe-harness": "^0.4.3",
     "commander": "^12.0.0",
-    "viem": "^2.54.3"
+    "viem": "^2.54.3",
+    "ws": "8.21.0"
   },
   "resolutions": {
     "esbuild": "0.28.1",