@deeeed/metamask-harness 0.14.3 → 0.14.5

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 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
+
+### Fixed
+- Include the new extension viewer cleanup scripts in the adapter manifest so published packages pass adapter-surface validation.
+
 ## 0.14.3 - 2026-07-09
 
 ### Fixed

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/adapters/manifest.json

@@ -106,6 +106,14 @@
       "inputs": "--target --runtime-dir --runner-bin --summary",
       "outputs": "<runtime-dir>/recipe-harness-webpack.{pid,log}; optional summary; exit 0/1/2"
     },
+    {
+      "id": "extension/stop-viewers",
+      "entry": "adapters/extension/stop-viewers.sh",
+      "kind": "bash",
+      "purpose": "Close extension webpack/console tmux viewers and the checkout-scoped console tail.",
+      "inputs": "--target <metamask-extension>",
+      "outputs": "removes viewer markers and closes matching run-owned windows; exit 0/1/2"
+    },
     {
       "id": "extension/console-tail",
       "entry": "adapters/extension/console-tail.mjs",
@@ -306,6 +314,14 @@
       "inputs": "resolve_run_tmux_session [runtime-dir]; env RECIPE_TMUX_SESSION, RECIPE_RUNTIME_CONTEXT, TMUX",
       "outputs": "resolved session name on stdout (empty when none)"
     },
+    {
+      "id": "lib/tmux-viewer",
+      "entry": "adapters/shared/tmux-viewer.sh",
+      "kind": "lib",
+      "purpose": "Run-owned tmux log viewer helpers that open, replace, and clean prefixed viewer windows without slot-name inference.",
+      "inputs": "tmux_viewer_open/close_marker/sweep_prefix functions; env RECIPE_TMUX_SESSION, RECIPE_RUNTIME_CONTEXT, TMUX",
+      "outputs": "viewer windows and marker files; no-op when no run-owned session is available"
+    },
     {
       "id": "lib/activate-repo-node",
       "entry": "adapters/shared/activate-repo-node.sh",

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deeeed/metamask-harness",
-  "version": "0.14.3",
+  "version": "0.14.5",
   "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",
@@ -69,4 +70,4 @@
     "url": "https://github.com/MetaMask/experimental-metamask-harness/issues"
   },
   "homepage": "https://github.com/MetaMask/experimental-metamask-harness#readme"
-}
+}