@deeeed/metamask-harness 0.42.0 → 0.44.0

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 ## Unreleased
 
+## 0.44.0 - 2026-08-25
+
+### Fixed
+
+- Remove `cold_disk_cache` from the `perps.performance` lifecycle enum because disk hydration is a cache source within a lifecycle, not a standalone lifecycle.
+- Await promise-returning Mobile `press-test-id` and `set-input` bridge handlers so recipe nodes finish only after the in-app operation settles.
+- Keep Mobile broker commands available while Hermes installs the in-app bridge after a target handoff, instead of reconnecting the inspector until actions time out.
+- Honor `launch --build` when a healthy Mobile runtime is already connected; the explicit native build can no longer return a false pass without invoking the build leaf.
+- Let resident Homepage and short-resume performance recipes finish from the ordered visible-content sequence without requiring a new live takeover.
+- Make Mobile reload stay on the pinned device, fail before an active Android Hermes sampler can abort the app, and fail if the process exits or a replacement target never appears; reload never relaunches the app.
+- Bind run evidence to the executable Harness source, build, bin, package, library, and adapter inputs plus task-local command/config helpers, and reject input drift or symlink swaps.
+- Persist recovery and mutation lists in recipe packages, include a redacted run-scoped application log, reject failed recovery before retrying, and prove lifecycle continuity with native process IDs, including opaque runtimes when requested.
+- Refuse stale Mobile source under every heal policy unless an authored `app.lifecycle restart` reloads it, and invalidate run evidence if recipe, library, or product provenance drifts after preparation.
+- Require Homepage demand, committed UI, resolved content, and live-current frame records before the canonical Mobile Perps performance recipe can pass.
+- Fail a Mobile recipe or action without implicitly restarting Metro or the app; process restarts remain explicit lifecycle actions.
+- Keep one Mobile inspector connection open while React Native replays its console buffer, avoiding repeated `Runtime.enable` requests that can stall Metro after unlock.
+- Allow `metamask.wallet.lock` to use the same visible Android controls on development and opaque clients.
+- Keep account-selection proof attached across the temporary Hermes/CDP stall caused by the account switch itself.
+- Add `metamask.perps.ensure_mode` so recipes can reach Lite or Pro through the visible mode control without inheriting prior device state.
+- Preserve Homepage boundary source and content-variant metadata in performance summaries, and bind recipe manifests to the exact product checkout commit.
+- Accept only structured, generation-coherent Perps live-stream records as performance proof, and keep Mobile wallet and mode probes inside one absolute action deadline.
+- Keep the latest automatic Mobile HUD update in the CDP broker and retry it until the in-app bridge applies it when the pinned Hermes target returns, without restarting the app.
+- Keep the Perps performance recipe's empty-account setup read-only and allow its setup-only prime capture to contain no performance records.
+- Redact quoted JSON credential fields before persisting run-scoped application logs.
+
+## 0.43.0 - 2026-08-21
+
+### Added
+
+- Add platform-neutral `app.performance_capture` and `app.performance_assert` actions that attribute Mobile or Extension CDP trace samples to exact recipe-node boundaries and emit JSON plus self-contained HTML evidence.
+- Mobile native UI FPS requires a development client that reports `unstable_frameRecordingEnabled: true`; unpatched clients report partial or unavailable native coverage. Extension uses Chromium CDP and needs no client patch.
+
+### Fixed
+
+- Bound performance capture duration, discard raw samples after node attribution, correct iOS frame completion timestamps, fail closed on unresolved Extension renderers, and reset CDP collector state after trace failures.
+- Scope Mobile Hermes broker ownership by checkout runtime and Metro port so a forwarder from a prior port cannot intercept bridge, HUD, or observation commands after a slot port change.
+- Preserve explicit Mobile `--device` pins when slot defaults load so HUD and live-adapter child processes cannot target another device.
+- Resume broker commands on the next Hermes session generation without losing the pinned logical device.
+- Keep Hermes session recovery inside the caller's RPC deadline, pass only the remaining time to the recovered command, and classify broker connection or request timeouts so transient HUD updates do not abort a recipe.
+- Accept React Native trace response chunks up to 16 MiB while keeping broker requests capped at 8 MiB, and never retry the non-idempotent `Tracing.end` command.
+- Limit Mobile UI captures to clock and native-frame categories; keep browser timeline and JavaScript task categories on Extension.
+
 ## 0.42.0 - 2026-08-20
 
 ### Added

package/README.md

@@ -116,6 +116,11 @@ explicit `app.network_capture` and `app.network_assert` nodes for filtered
 windows and machine-checked request expectations. See
 [Recipe-scoped network capture](docs/NETWORK-CAPTURE.md).
 
+Mobile and Extension recipes can bracket explicit UI-smoothness windows with
+`app.performance_capture` and verify their evidence with
+`app.performance_assert`. Capture is never automatic. See
+[UI smoothness capture](docs/PERFORMANCE-CAPTURE.md).
+
 ## Discover and prove
 
 ```bash

package/adapters/mobile/bridge-runtime/cdp-bridge.cjs

@@ -18,10 +18,10 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { execFileSync } = require('node:child_process');
 const { loadPort } = require('./lib/config.cjs');
 const {
   discoverTarget,
-  rankRuntimeCandidates,
 } = require('./lib/target-discovery.cjs');
 const { createWSClient } = require('./lib/ws-client.cjs');
 const {
@@ -37,6 +37,126 @@ const {
 } = require('./lib/bridge-errors.cjs');
 const { cdpEval, cdpEvalAsync } = require('./lib/cdp-eval.cjs');
 const { buildArmSnippet, buildCollectSnippet } = require('./lib/issue-capture.cjs');
+const APPLY_HUD_UPDATE_FUNCTION = `function(step) {
+  const bridge = this.__AGENTIC__;
+  if (step === null) {
+    if (typeof bridge?.hideStep !== 'function') return false;
+    setTimeout(() => bridge.hideStep(), 0);
+    return true;
+  }
+  if (typeof bridge?.showStep !== 'function') return false;
+  setTimeout(() => bridge.showStep(step), 0);
+  return true;
+}`;
+
+function mobileToolPath(tool) {
+  return process.env[`MM_HARNESS_${tool.toUpperCase()}_PATH`] || tool;
+}
+
+function bootedIosDevice(deviceName) {
+  if (!deviceName) return null;
+  try {
+    const devices = JSON.parse(
+      execFileSync('xcrun', ['simctl', 'list', 'devices', 'available', '-j'], {
+        encoding: 'utf8',
+      }),
+    );
+    const device = Object.values(devices.devices || {})
+      .flat()
+      .find(
+        (candidate) =>
+          (candidate?.name === deviceName || candidate?.udid === deviceName) &&
+          candidate?.state === 'Booted',
+      );
+    return device?.udid ? device : null;
+  } catch {
+    return null;
+  }
+}
+
+function tapVisibleIosAccessibilityTarget(testId, deviceName, platform) {
+  if (platform !== 'ios') return null;
+  const device = bootedIosDevice(deviceName);
+  if (!device) return null;
+  try {
+    const idb = mobileToolPath('idb');
+    const elements = JSON.parse(
+      execFileSync(
+        idb,
+        ['ui', 'describe-all', '--udid', device.udid, '--json'],
+        { encoding: 'utf8' },
+      ),
+    );
+    const windowFrame = elements
+      .map((element) => element?.frame)
+      .filter(
+        (frame) =>
+          frame &&
+          frame.x === 0 &&
+          frame.y === 0 &&
+          frame.width > 0 &&
+          frame.height > 0,
+      )
+      .sort(
+        (first, second) =>
+          second.width * second.height - first.width * first.height,
+      )[0];
+    if (!windowFrame) return null;
+    const target = elements.find((element) => {
+      const frame = element?.frame;
+      return (
+        element?.AXUniqueId === testId &&
+        element?.enabled !== false &&
+        element?.hittable !== false &&
+        frame &&
+        frame.width > 0 &&
+        frame.height > 0 &&
+        frame.x >= 0 &&
+        frame.y >= 0 &&
+        frame.x + frame.width <= windowFrame.width &&
+        frame.y + frame.height <= windowFrame.height
+      );
+    });
+    if (!target) return null;
+    const x = Math.round(target.frame.x + target.frame.width / 2);
+    const y = Math.round(target.frame.y + target.frame.height / 2);
+    execFileSync(
+      idb,
+      ['ui', 'tap', String(x), String(y), '--udid', device.udid],
+      { encoding: 'utf8' },
+    );
+    return { ok: true, testId, deviceName, provider: 'idb-accessibility' };
+  } catch {
+    return null;
+  }
+}
+
+async function applyHudUpdate(client, step) {
+  const globalObject = await client.send('Runtime.evaluate', {
+    expression: 'globalThis',
+    returnByValue: false,
+    awaitPromise: false,
+  });
+  const objectId = globalObject?.result?.objectId;
+  if (!objectId) {
+    throw new Error('Mobile HUD runtime did not expose globalThis');
+  }
+  const result = await client.send('Runtime.callFunctionOn', {
+    objectId,
+    functionDeclaration: APPLY_HUD_UPDATE_FUNCTION,
+    arguments: [{ value: step }],
+    returnByValue: true,
+    awaitPromise: false,
+  });
+  if (result?.exceptionDetails) {
+    throw new Error(
+      result.exceptionDetails.exception?.description ||
+        result.exceptionDetails.text ||
+        'Mobile HUD update failed',
+    );
+  }
+  return result?.result?.value === true;
+}
 
 function parsePerformanceConsoleEvent(params) {
   const markers = ['[PerpsPerf] ', '[HomepagePerf] '];
@@ -98,7 +218,7 @@ async function setInput(client, testId, value, { deviceName } = {}, redact = fal
     throw new Error('Usage: set-input <testId> <value>');
   }
   const expr = `(function() {
-    if (globalThis.__AGENTIC__?.setInput) return globalThis.__AGENTIC__.setInput(${JSON.stringify(testId)}, ${JSON.stringify(value)});
+    if (globalThis.__AGENTIC__?.setInput) return Promise.resolve(globalThis.__AGENTIC__.setInput(${JSON.stringify(testId)}, ${JSON.stringify(value)}));
     var hook = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
     if (!hook) return { ok: false, error: 'No React DevTools hook' };
     var renderers = hook.renderers;
@@ -134,7 +254,7 @@ async function setInput(client, testId, value, { deviceName } = {}, redact = fal
   })()`;
   let result;
   try {
-    result = await cdpEval(client, expr);
+    result = await cdpEvalAsync(client, expr);
   } catch (error) {
     if (redact) {
       throw new Error(`Secret input could not be applied for testID ${testId}.`);
@@ -152,6 +272,26 @@ async function setInput(client, testId, value, { deviceName } = {}, redact = fal
   };
 }
 
+function parseHudStep(args) {
+  const raw = args.join(' ');
+  let step;
+  try {
+    step = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`show-step-json requires a JSON step payload: ${error.message}`);
+  }
+  if (!step || typeof step !== 'object' || Array.isArray(step)) {
+    throw new Error('show-step-json requires a JSON object step payload');
+  }
+  if (typeof step.intent !== 'string' || !step.intent.trim()) {
+    throw new Error('show-step-json requires step.intent');
+  }
+  if (step.id !== undefined && typeof step.id !== 'string') {
+    throw new Error('show-step-json step.id must be a string when provided');
+  }
+  return step;
+}
+
 const COMMANDS = {
   async navigate(client, args, { deviceName, platform } = {}) {
     const routeName = ROUTE_ALIASES[args[0]] || args[0];
@@ -301,14 +441,15 @@ const COMMANDS = {
     return await cdpEval(client, `globalThis.__AGENTIC__?.switchAccount(${JSON.stringify(address)})`);
   },
 
-  async 'press-test-id'(client, args, { deviceName } = {}) {
+  async 'press-test-id'(client, args, { deviceName, platform } = {}) {
     const testId = args[0];
     if (!testId) {
       throw new Error('Usage: press-test-id <testId>');
     }
-    // Try __AGENTIC__ bridge first, fall back to inline fiber walking
+    // Try the app bridge first. Native accessibility remains an iOS fallback
+    // for controls whose React handler cannot be invoked directly.
     const expr = `(function() {
-      if (globalThis.__AGENTIC__?.pressTestId) return globalThis.__AGENTIC__.pressTestId(${JSON.stringify(testId)});
+      if (globalThis.__AGENTIC__?.pressTestId) return Promise.resolve(globalThis.__AGENTIC__.pressTestId(${JSON.stringify(testId)}));
       var hook = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
       if (!hook) return { ok: false, error: 'No React DevTools hook' };
       var renderers = hook.renderers;
@@ -331,10 +472,72 @@ const COMMANDS = {
       }
       return { ok: false, error: 'No component with testID=' + ${JSON.stringify(testId)} + ' found or no onPress' };
     })()`;
-    const result = await cdpEval(client, expr);
+    let result;
+    let bridgeError;
+    try {
+      result = await cdpEvalAsync(client, expr);
+      if (result?.ok !== false) {
+        return { ...result, testId, deviceName };
+      }
+    } catch (error) {
+      bridgeError = error;
+    }
+    const nativeResult = tapVisibleIosAccessibilityTarget(
+      testId,
+      deviceName,
+      platform,
+    );
+    if (nativeResult) return nativeResult;
+    if (bridgeError) throw bridgeError;
     return { ...result, testId, deviceName };
   },
 
+  async 'key-press'(_client, args, { deviceName, platform } = {}) {
+    const requestedKey = String(args[0] || 'Enter').toLowerCase();
+    const isEnter = requestedKey === 'enter' || requestedKey === 'return';
+    const isBack = requestedKey === 'escape' || requestedKey === 'back';
+    if (!isEnter && !isBack) {
+      throw new Error(`Unsupported Mobile key ${JSON.stringify(args[0])}`);
+    }
+    if (platform === 'android') {
+      const serial = process.env.ADB_SERIAL || process.env.ANDROID_SERIAL;
+      if (!serial) throw new Error('key-press requires a selected Android device');
+      const keyCode = isEnter ? '66' : '4';
+      execFileSync(
+        mobileToolPath('adb'),
+        ['-s', serial, 'shell', 'input', 'keyevent', keyCode],
+        { encoding: 'utf8' },
+      );
+      return {
+        ok: true,
+        key: args[0] || 'Enter',
+        keyCode,
+        deviceName,
+        provider: 'adb-key',
+      };
+    }
+    if (platform !== 'ios') {
+      throw new Error(`key-press requires a selected Mobile platform`);
+    }
+    const device = bootedIosDevice(deviceName);
+    if (!device) {
+      throw new Error(`No booted simulator named ${JSON.stringify(deviceName)}`);
+    }
+    const keyCode = isEnter ? '40' : '41';
+    execFileSync(
+      mobileToolPath('idb'),
+      ['ui', 'key', keyCode, '--udid', device.udid],
+      { encoding: 'utf8' },
+    );
+    return {
+      ok: true,
+      key: args[0] || 'Enter',
+      keyCode,
+      deviceName,
+      provider: 'idb-key',
+    };
+  },
+
   async 'long-press-test-id'(client, args, { deviceName } = {}) {
     const testId = args[0];
     if (!testId) {
@@ -407,6 +610,9 @@ const COMMANDS = {
       // selector fiber. For into-view requests the scroll container is commonly
       // an ancestor (for example, a Wallet Home section row), so use the
       // ancestor-aware bridge fallback below instead.
+      if (${intoView} && globalThis.__AGENTIC__?.scrollIntoView) {
+        return globalThis.__AGENTIC__.scrollIntoView(${JSON.stringify(testId)}, ${animated});
+      }
       if (!${intoView} && globalThis.__AGENTIC__?.scrollView) return globalThis.__AGENTIC__.scrollView(${optsJson});
       var hook = globalThis.__REACT_DEVTOOLS_GLOBAL_HOOK__;
       if (!hook) return { ok: false, error: 'No React DevTools hook' };
@@ -428,14 +634,56 @@ const COMMANDS = {
         }
         return false;
       }
+      function findMeasurable(fiber) {
+        if (!fiber) return null;
+        var sn = fiber.stateNode;
+        if (sn && typeof sn.measureLayout === 'function') return sn;
+        return findMeasurable(fiber.child);
+      }
       function tryScrollNear(anchor) {
         if (!opts.intoView && tryScroll(anchor, false)) return true;
+        var target = opts.intoView ? findMeasurable(anchor) : null;
         var current = anchor ? anchor.return : null;
         while (current) {
           var sn = current.stateNode;
+          var currentProps = current.memoizedProps;
           if (sn) {
-            if (typeof sn.scrollTo === 'function') { sn.scrollTo({ y: opts.offset, animated: opts.animated }); return true; }
-            if (typeof sn.scrollToOffset === 'function') { sn.scrollToOffset({ offset: opts.offset, animated: opts.animated }); return true; }
+            if (typeof sn.scrollTo === 'function' && !(currentProps && currentProps.horizontal === true)) {
+              if (target) {
+                return new Promise(function(resolve) {
+                  target.measureLayout(
+                    sn,
+                    function(x, y) {
+                      sn.scrollTo({ y: y, animated: opts.animated });
+                      resolve({ ok: true, testId: opts.testId, measuredOffset: y, animated: opts.animated });
+                    },
+                    function() {
+                      resolve({ ok: false, error: 'Unable to measure testID=' + opts.testId + ' relative to its scroll container' });
+                    }
+                  );
+                });
+              }
+              sn.scrollTo({ y: opts.offset, animated: opts.animated });
+              return true;
+            }
+            if (typeof sn.scrollToOffset === 'function' && !(currentProps && currentProps.horizontal === true)) {
+              if (target) {
+                return new Promise(function(resolve) {
+                  target.measureLayout(
+                    sn,
+                    function(x, y) {
+                      sn.scrollToOffset({ offset: y, animated: opts.animated });
+                      resolve({ ok: true, testId: opts.testId, measuredOffset: y, animated: opts.animated });
+                    },
+                    function() {
+                      resolve({ ok: false, error: 'Unable to measure testID=' + opts.testId + ' relative to its scroll container' });
+                    }
+                  );
+                });
+              }
+              sn.scrollToOffset({ offset: opts.offset, animated: opts.animated });
+              return true;
+            }
           }
           current = current.return;
         }
@@ -444,7 +692,23 @@ const COMMANDS = {
       function findTestId(fiber) {
         if (!fiber) return null;
         var props = fiber.memoizedProps;
-        if (props && props.testID === opts.testId) return fiber;
+        if (props && props.testID === opts.testId) {
+          var ancestor = fiber;
+          var inactive = false;
+          while (ancestor) {
+            var ancestorProps = ancestor.memoizedProps;
+            var ancestorStyle = ancestorProps && ancestorProps.style;
+            if (
+              (ancestorProps && ancestorProps.activityState === 0) ||
+              (ancestorStyle && ancestorStyle.display === 'none')
+            ) {
+              inactive = true;
+              break;
+            }
+            ancestor = ancestor.return;
+          }
+          if (!inactive) return fiber;
+        }
         return findTestId(fiber.child) || findTestId(fiber.sibling);
       }
       for (var [id] of renderers) {
@@ -460,11 +724,16 @@ const COMMANDS = {
             scrolled = tryScroll(r.current);
           }
         });
-        if (scrolled) return { ok: true, testId: opts.testId, offset: opts.offset, animated: opts.animated };
+        if (scrolled) {
+          if (typeof scrolled.then === 'function') return scrolled;
+          return { ok: true, testId: opts.testId, offset: opts.offset, animated: opts.animated };
+        }
       }
       return { ok: false, error: opts.testId ? 'No scrollable near testID=' + opts.testId : 'No scrollable found' };
     })()`;
-    const result = await cdpEval(client, expr);
+    const result = intoView
+      ? await cdpEvalAsync(client, expr)
+      : await cdpEval(client, expr);
     return { ...result, deviceName };
   },
 
@@ -842,34 +1111,33 @@ const COMMANDS = {
   },
 
   async 'show-step-json'(client, args) {
-    const raw = args.join(' ');
-    let step;
-    try {
-      step = JSON.parse(raw);
-    } catch (error) {
-      throw new Error(`show-step-json requires a JSON step payload: ${error.message}`);
-    }
-    if (!step || typeof step !== 'object' || Array.isArray(step)) {
-      throw new Error('show-step-json requires a JSON object step payload');
-    }
-    if (typeof step.intent !== 'string' || !step.intent.trim()) {
-      throw new Error('show-step-json requires step.intent');
-    }
-    // HUD derives status/progress from step.id when status is omitted; a
-    // non-string id makes statusForStep throw during render. Reject at the boundary.
-    if (step.id !== undefined && typeof step.id !== 'string') {
-      throw new Error('show-step-json step.id must be a string when provided');
-    }
-    const payload = JSON.stringify(step);
-    await cdpEval(client, `globalThis.__AGENTIC__?.showStep && globalThis.__AGENTIC__.showStep(${payload})`);
+    const step = parseHudStep(args);
+    await applyHudUpdate(client, step);
     return { ok: true };
   },
 
+  async 'show-step-json-deferred'(client, args) {
+    const step = parseHudStep(args);
+    if (typeof client.control === 'function') {
+      return client.control('hud-update', { step });
+    }
+    await applyHudUpdate(client, step);
+    return { ok: true, status: 'applied' };
+  },
+
   async 'hide-step'(client) {
-    await cdpEval(client, `globalThis.__AGENTIC__?.hideStep && globalThis.__AGENTIC__.hideStep()`);
+    await applyHudUpdate(client, null);
     return { ok: true };
   },
 
+  async 'hide-step-deferred'(client) {
+    if (typeof client.control === 'function') {
+      return client.control('hud-update', { step: null });
+    }
+    await applyHudUpdate(client, null);
+    return { ok: true, status: 'applied' };
+  },
+
   async 'profiler-start'(client) {
     // Hermes CDP exposes the sampling profiler via the Profiler domain.
     // Output of Profiler.stop is a Chrome-compatible .cpuprofile object.
@@ -961,7 +1229,6 @@ const BRIDGE_LOCK_FILE = path.join(
   process.env.RECIPE_RUNTIME_DIR || path.join('temp', 'recipe', 'runtime'),
   'cdp-bridge.lock',
 );
-const BROKER_SOCKET_FILE = brokerSocketPath(path.dirname(BRIDGE_LOCK_FILE));
 const BRIDGE_LOCK_OWNER_PID = /^\d+$/.test(
   process.env.CDP_BRIDGE_LOCK_OWNER_PID || '',
 )
@@ -1063,30 +1330,70 @@ Environment:
   }
 
   const port = loadPort();
+  const brokerSocketFile = brokerSocketPath(
+    path.dirname(BRIDGE_LOCK_FILE),
+    port,
+  );
   const timeout = Number.parseInt(process.env.CDP_TIMEOUT || '5000', 10);
-  const brokerAvailable = fs.existsSync(BROKER_SOCKET_FILE);
+  const brokerAvailable = fs.existsSync(brokerSocketFile);
   if (!brokerAvailable) acquireBridgeLock();
 
-  async function brokerTargets() {
-    const response = await fetch(`http://127.0.0.1:${port}/json/list`);
-    if (!response.ok) throw new Error(`Metro target listing returned ${response.status}`);
-    const ranked = rankRuntimeCandidates(await response.json());
-    const picked = new Set();
-    return ranked.flatMap((target) => {
-      const deviceId = deviceIdFromUrl(target.webSocketDebuggerUrl);
-      if (picked.has(deviceId)) return [];
-      picked.add(deviceId);
-      return [{
-        wsUrl: target.webSocketDebuggerUrl,
-        deviceName: target.deviceName || '',
-      }];
-    });
+  function selectedTargetPin() {
+    const platform = String(process.env.MM_HARNESS_EXPLICIT_PLATFORM || '').toLowerCase();
+    const androidPin =
+      process.env.ANDROID_TARGET_DEVICE_NAME || process.env.ANDROID_DEVICE || '';
+    const iosPin = process.env.IOS_SIMULATOR || '';
+    return String(
+      platform === 'android'
+        ? androidPin
+        : platform === 'ios'
+          ? iosPin
+          : androidPin || iosPin,
+    ).trim();
+  }
+
+  async function brokerTargets({ retainIdentity = false } = {}) {
+    const discoveryClient = await createBrokerClient(
+      brokerSocketFile,
+      '',
+      timeout,
+    );
+    try {
+      const targets = await discoveryClient.control(
+        retainIdentity ? 'resolve-targets' : 'list-targets',
+        retainIdentity ? { nameIncludes: selectedTargetPin() } : {},
+        timeout,
+      );
+      return (Array.isArray(targets) ? targets : []).flatMap((target) => {
+        const deviceId = String(target?.deviceId || '');
+        return deviceId
+          ? [{ wsUrl: deviceId, deviceName: String(target?.name || '') }]
+          : [];
+      });
+    } finally {
+      discoveryClient.close();
+    }
+  }
+
+  function selectBrokerTarget(targets) {
+    const pin = selectedTargetPin();
+    const candidates = pin
+      ? targets.filter((target) =>
+          target.deviceName.toLowerCase().includes(pin.toLowerCase()),
+        )
+      : targets;
+    if (candidates.length !== 1) {
+      throw new Error(
+        `Mobile CDP broker target selection requires one target; found ${candidates.length}${pin ? ` for ${JSON.stringify(pin)}` : ''}.`,
+      );
+    }
+    return candidates[0];
   }
 
   async function clientFor(wsUrl) {
     if (brokerAvailable) {
       return createBrokerClient(
-        BROKER_SOCKET_FILE,
+        brokerSocketFile,
         deviceIdFromUrl(wsUrl),
         timeout,
       );
@@ -1125,15 +1432,16 @@ Environment:
     return;
   }
 
-  const { wsUrl, deviceName } = await discoverTarget(port, {
-    probe: !brokerAvailable,
-  });
+  const { wsUrl, deviceName } = brokerAvailable
+    ? selectBrokerTarget(await brokerTargets({ retainIdentity: true }))
+    : await discoverTarget(port, { probe: true });
   if (!wsUrl) throw new Error('No broker-owned Hermes target is available');
   const client = await clientFor(wsUrl);
 
   try {
-    // Detect platform from the running app (exposed by __AGENTIC__ bridge as Platform.OS)
-    const platform = await cdpEval(client, 'globalThis.__AGENTIC__?.platform') || '';
+    const platform = command.endsWith('-deferred')
+      ? ''
+      : await cdpEval(client, 'globalThis.__AGENTIC__?.platform') || '';
     const result = await handler(client, args.slice(1), { deviceName, platform });
     console.log(JSON.stringify(result, null, 2));
   } finally {