mobile-automator 0.26.0 → 0.28.0

package/README.md

@@ -8,13 +8,13 @@ Claude Code, Cursor, Gemini CLI, GitHub Copilot, and OpenAI Agents all have one-
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 [![Platform](https://img.shields.io/badge/Platform-Android%20%7C%20iOS%20%7C%20Flutter%20%7C%20RN%20%7C%20KMP%20%7C%20CMP-green.svg)](#)
-[![Node](https://img.shields.io/badge/Node-%E2%89%A520-brightgreen.svg)](#)
+[![Node](https://img.shields.io/badge/Node-%E2%89%A522.12-brightgreen.svg)](#)
 
 ---
 
 ## ⏱️ Quick start (5 minutes)
 
-**You need:** Node ≥ 20 · an AI coding agent · a running emulator/simulator or a connected device.
+**You need:** Node ≥ 22.12 · an AI coding agent · a running emulator/simulator or a connected device.
 
 > This quick start uses **Claude Code** as the example agent. For Cursor, swap `--agent claude` → `--agent cursor`. For any other agent, see [Using another agent](#-using-another-agent).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-automator",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Host-agnostic mauto CLI for AI-driven mobile QA automation — analyzes a mobile project and drives devices through mobile-mcp.",
   "homepage": "https://github.com/sh3lan93/mobile-automator#readme",
   "repository": {
@@ -33,7 +33,7 @@
     "test:all": "jest"
   },
   "dependencies": {
-    "@mobilenext/mobile-mcp": "0.0.55",
+    "@mobilenext/mobile-mcp": "1.0.5",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "ajv": "^8.20.0",
     "commander": "^12.1.0"
@@ -45,6 +45,6 @@
     "toml": "^3.0.0"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.12.0"
   }
 }

package/src/cli.js

@@ -8,6 +8,7 @@ const { version: PKG_VERSION } = require('../package.json');
 const { ok, fail, render, exitCodeFor } = require('./output/envelope');
 const { DeviceBridge } = require('./device/bridge');
 const selectionStore = require('./device/selection');
+const { engineHint } = require('./device/engine-hints');
 const { ScenarioValidator } = require('./scenario/validator');
 const { evaluate, MECHANICAL_TYPES } = require('./assertion/evaluator');
 const { ResultStore } = require('./result/store');
@@ -158,6 +159,16 @@ function toEnvelope(err) {
   };
 }
 
+// The hint for any device-kind failure. Precedence: an explicit err.hint wins
+// (our own code attached it knowing the exact cause — a DeviceResolutionError,
+// the daemon-log pointer, a timeout); then engineHint, which recognises engine
+// messages that are useless on their own (the 1.0.5 engine's missing iOS agent
+// and changed Android device ids, #199); then the handler's generic fallback.
+// Every device fail() below goes through here so no handler can miss it.
+function deviceHint(err, fallback) {
+  return (err && err.hint) || engineHint(err && err.message) || fallback;
+}
+
 // ---------------------------------------------------------------------------
 // Handlers — pure-ish: accept injected deps, return { envelope, exitKind }.
 // No process.exit / printing here so they are trivially unit-testable.
@@ -172,7 +183,7 @@ async function handleElements({ deviceBridge }) {
       envelope: fail(
         'device',
         err.message || String(err),
-        err.hint || 'Ensure a device or simulator is connected and the app is running.'
+        deviceHint(err, 'Ensure a device or simulator is connected and the app is running.')
       ),
       exitKind: 'device',
     };
@@ -188,7 +199,7 @@ async function handleScreenshot({ deviceBridge }, destPath) {
       envelope: fail(
         'device',
         err.message || String(err),
-        err.hint || 'Ensure a device or simulator is connected.'
+        deviceHint(err, 'Ensure a device or simulator is connected.')
       ),
       exitKind: 'device',
     };
@@ -247,7 +258,7 @@ function deviceFail(err) {
     envelope: fail(
       kind,
       err.message || String(err),
-      err.hint || 'Ensure a device or simulator is connected and the app is running.'
+      deviceHint(err, 'Ensure a device or simulator is connected and the app is running.')
     ),
     exitKind: kind,
   };
@@ -279,7 +290,20 @@ function parseCoordinates(raw) {
       error: fail('invalid_input', `coordinates must be numbers, got "${raw}"`, 'Pass --at <x,y>, e.g. --at 100,250.'),
     };
   }
-  return { x: Math.round(x), y: Math.round(y) };
+  // Check AFTER rounding: the device receives the rounded ints, so -0.4 (-> 0)
+  // is a valid on-screen point while -0.6 (-> -1) is not. `+ 0` normalizes -0
+  // to 0 so neither the envelope nor the engine sees a signed zero. Negatives
+  // must be caught here because mobile-mcp 1.0.5 declares coordinates .min(0)
+  // and would reject them device-side, misclassified as a device failure that
+  // triggers the crash probe (#199).
+  const rx = Math.round(x) + 0;
+  const ry = Math.round(y) + 0;
+  if (rx < 0 || ry < 0) {
+    return {
+      error: fail('invalid_input', `coordinates must be non-negative, got "${raw}"`, 'Coordinates must be >= 0 (screen pixels from the top-left), e.g. --at 100,250.'),
+    };
+  }
+  return { x: rx, y: ry };
 }
 
 async function handleTap({ deviceBridge }, raw) {
@@ -1210,17 +1234,54 @@ async function handleSessionStatus(
   { projectRoot, client = require('./device/session-client') } = {}
 ) {
   const status = await connection.sessionStatus(projectRoot, { client });
-  return { envelope: ok(status), exitKind: 'ok' };
+  const hint =
+    status.reason === 'engine_exited'
+      ? `The device engine exited; this session is shutting down and the next verb starts a fresh one. ${connection.daemonLogHint(projectRoot)}`
+      : null;
+  return { envelope: ok(status, hint), exitKind: 'ok' };
 }
 
+// endSession's failure outcomes (#156), each with the hint that is true for it.
+// All three may leave a daemon alive and holding the workspace lock; what
+// differs is WHY, and so what the user should do about it. One vague hint used
+// to cover all three.
+const SESSION_END_FAILURE_HINTS = {
+  survived: (pid, pidFile) =>
+    `It is still alive after SIGTERM and SIGKILL and may still hold the workspace lock. Check it with \`ps -p ${pid}\` and stop it with \`kill -9 ${pid}\` (pidfile: ${pidFile}).`,
+  foreign: (pid, pidFile) =>
+    `It answered the shutdown, but its command line does not name this workspace (possibly started by mauto < 0.28), so it was not signalled. Check it with \`ps -p ${pid}\` and stop it manually (pidfile: ${pidFile}).`,
+  unverified: (pid, pidFile) =>
+    `It could not be identified (\`ps\` failed), so it was not signalled. Check it with \`ps -p ${pid}\` and stop it manually if it is this workspace's mauto daemon (pidfile: ${pidFile}).`,
+};
+
 async function handleSessionEnd(
-  { projectRoot, client = require('./device/session-client') } = {}
+  { projectRoot, client = require('./device/session-client'), end = {} } = {}
 ) {
-  const stopped = await connection.endSession(projectRoot, { client });
-  return {
-    envelope: ok({ stopped, already_stopped: !stopped }),
-    exitKind: 'ok',
+  const { outcome, pid } = await connection.endSession(projectRoot, { client, ...end });
+  const logHint = connection.daemonLogHint(projectRoot);
+  if (Object.prototype.hasOwnProperty.call(SESSION_END_FAILURE_HINTS, outcome)) {
+    const pidFile = require('./device/session-paths').pidFilePath(projectRoot);
+    return {
+      envelope: fail(
+        'device',
+        `device session daemon pid ${pid} did not exit`,
+        `${SESSION_END_FAILURE_HINTS[outcome](pid, pidFile)} ${logHint}`,
+        { stopped: false, already_stopped: false, pid }
+      ),
+      exitKind: 'device',
+    };
+  }
+  // 'stopped' | 'forced' | 'already_stopped'. The ok envelope keeps the boolean
+  // shape it had before endSession returned an outcome.
+  const data = {
+    stopped: outcome === 'stopped' || outcome === 'forced',
+    already_stopped: outcome === 'already_stopped',
+    forced: outcome === 'forced',
   };
+  const hint = outcome === 'forced'
+    ? `The daemon did not exit after shutdown; terminated pid ${pid}. ${logHint}`
+    : null;
+  return { envelope: ok(data, hint), exitKind: 'ok' };
 }
 
 // --- Issue #92: device discovery + persisted selection -------------------
@@ -1241,7 +1302,7 @@ async function handleDevices({ deviceBridge }) {
       envelope: fail(
         'device',
         err.message || String(err),
-        err.hint || 'Ensure a device or simulator is connected and reachable.'
+        deviceHint(err, 'Ensure a device or simulator is connected and reachable.')
       ),
       exitKind: 'device',
     };
@@ -1265,7 +1326,7 @@ async function handleDevicesUse({ deviceBridge, store = selectionStore, projectR
     devices = await deviceBridge.listDevices();
   } catch (err) {
     return {
-      envelope: fail('device', err.message || String(err), err.hint || 'Ensure a device or simulator is connected and reachable.'),
+      envelope: fail('device', err.message || String(err), deviceHint(err, 'Ensure a device or simulator is connected and reachable.')),
       exitKind: 'device',
     };
   }
@@ -1376,7 +1437,7 @@ async function handleCrashList({ deviceBridge, projectRoot }, opts = {}) {
     // "Could not look" is NOT "found none". Reporting ok:true with an empty
     // list here would be this slice's own bug with the sign flipped.
     return {
-      envelope: fail(err.kind || 'device', err.message || String(err), err.hint || CRASH_LIST_HINT),
+      envelope: fail(err.kind || 'device', err.message || String(err), deviceHint(err, CRASH_LIST_HINT)),
       exitKind: err.kind || 'device',
     };
   }
@@ -1408,7 +1469,7 @@ async function handleCrashGet({ deviceBridge, fs: fsDep = fs }, id, opts = {}) {
     report = await deviceBridge.getCrash(id);
   } catch (err) {
     return {
-      envelope: fail(err.kind || 'device', err.message || String(err), err.hint || CRASH_LIST_HINT),
+      envelope: fail(err.kind || 'device', err.message || String(err), deviceHint(err, CRASH_LIST_HINT)),
       exitKind: err.kind || 'device',
     };
   }

package/src/device/action-catalog.js

@@ -16,7 +16,7 @@
 //   'composed'    — no dedicated verb; the agent composes it from existing verbs
 //                   (e.g. poll `mauto elements`, repeat `mauto swipe`). The
 //                   execute guide documents the composition.
-//   'unsupported' — mobile-mcp 0.0.55 exposes no primitive for it. Not
+//   'unsupported' — mobile-mcp 1.0.5 exposes no primitive for it. Not
 //                   mechanically executable; the guide must NOT promise a verb,
 //                   and the agent reports it honestly / handles it manually.
 //
@@ -84,7 +84,7 @@ const ACTION_CATALOG = {
   wait_for_loading_complete: { resolution: 'composed' },
   capture_value: { resolution: 'composed' },
 
-  // --- unsupported (no mobile-mcp 0.0.55 primitive) ----------------------
+  // --- unsupported (no mobile-mcp 1.0.5 primitive) -----------------------
   clear_app_data: { resolution: 'unsupported' },
   enable_wifi: { resolution: 'unsupported' },
   disable_wifi: { resolution: 'unsupported' },

package/src/device/bridge.js

@@ -4,6 +4,7 @@ const { normalize, parseElements } = require('./element-model');
 const { normalizeDevices } = require('./device-model');
 const { normalizeCrashes } = require('./crash-model');
 const { resolveSingleDevice } = require('./device-resolver');
+const { centredSwipe } = require('./swipe-geometry');
 
 // Thin wrapper over an injected mobile-mcp `call(toolName, args)` function.
 // Returns the agnostic element model and exposes only the primitives the CLI needs.
@@ -24,8 +25,11 @@ class DeviceBridge {
     return normalizeDevices(result);
   }
 
+  // format:"json" is required from mobile-mcp 1.0.5, which defaults this tool
+  // to a line-per-element text format parseElements cannot read (#199). 0.0.55
+  // ignores the unknown key (its zod schema is non-strict), so it is safe on both.
   async listElements() {
-    const result = await this._call('mobile_list_elements_on_screen', {});
+    const result = await this._call('mobile_list_elements_on_screen', { format: 'json' });
     return normalize(parseElements(result));
   }
 
@@ -62,10 +66,26 @@ class DeviceBridge {
     return this._call('mobile_type_keys', { text, submit: false });
   }
 
-  // Swipe in a cardinal direction. Optional x/y set the start point and
-  // distance the travel — used by the iOS edge-swipe back gesture. Absent keys
-  // are not sent so the cardinal-from-center default is preserved.
+  // Swipe in a cardinal direction.
+  //
+  // Direction-only (x, y and distance all undefined): mauto sends explicit
+  // centre ± 30% geometry from centredSwipe rather than trusting the engine
+  // default, which mobile-mcp 1.x changed from that proportional travel to a
+  // fixed 400px on Android and real iOS (#199; see swipe-geometry.js). This
+  // costs one extra mobile_get_screen_size round trip per direction-only swipe
+  // — acceptable because each verb is one-shot and swipes are not hot-path, so
+  // no caching. getScreenSize throws on a zero/unreadable size, so a 0x0 screen
+  // can never produce a degenerate swipe.
+  //
+  // Any explicit key (e.g. the iOS edge-swipe back's x/y/distance) means the
+  // caller owns the geometry: everything given is passed through as-is and
+  // absent keys are not sent — including partial input such as x,y without
+  // distance, which leaves the travel to the engine exactly as before.
   async swipe({ direction, x, y, distance } = {}) {
+    if (x === undefined && y === undefined && distance === undefined) {
+      const geometry = centredSwipe(await this.getScreenSize(), direction);
+      return this._call('mobile_swipe_on_screen', { direction, ...geometry });
+    }
     const args = { direction };
     if (x !== undefined) args.x = x;
     if (y !== undefined) args.y = y;
@@ -92,18 +112,25 @@ class DeviceBridge {
   // object), so we parse the WxH out of it; a structured {width,height} shape is
   // also accepted in case a future engine returns one. An unreadable size is a
   // hard error — never silently 0/NaN, which would make geometry gestures no-ops.
+  // That includes a READABLE zero: mobile-mcp 1.0.5's mobilecli path returns
+  // {width:0,height:0,scale:1} for an unknown size instead of throwing (#199).
   async getScreenSize() {
     const r = await this._call('mobile_get_screen_size', {});
+    let size = null;
     if (r && typeof r === 'object' && r.width != null && r.height != null) {
-      return { width: Number(r.width), height: Number(r.height) };
+      size = { width: Number(r.width), height: Number(r.height) };
+    } else {
+      const m = /(\d+)\s*x\s*(\d+)/i.exec(String(r));
+      if (m) size = { width: Number(m[1]), height: Number(m[2]) };
     }
-    const m = /(\d+)\s*x\s*(\d+)/i.exec(String(r));
-    if (!m) {
-      const err = new Error(`Could not read the device screen size from "${r}".`);
+    const positive = (n) => Number.isFinite(n) && n > 0;
+    if (!size || !positive(size.width) || !positive(size.height)) {
+      const shown = r && typeof r === 'object' ? JSON.stringify(r) : String(r);
+      const err = new Error(`Could not read the device screen size from "${shown}".`);
       err.hint = 'Ensure a device or simulator is connected.';
       throw err;
     }
-    return { width: Number(m[1]), height: Number(m[2]) };
+    return size;
   }
 
   // Press a hardware/system button (BACK, HOME, ENTER, ...).

package/src/device/connection.js

@@ -19,6 +19,9 @@ const { daemonLogHint } = require('./session-log');
 const paths = require('./session-paths');
 const sessionClient = require('./session-client');
 const sessionSpawn = require('./session-spawn');
+const sessionDaemon = require('./session-daemon');
+const processIdentity = require('./process-identity');
+const processReaper = require('./process-reaper');
 
 // Acquire a device connection, transparently reusing a live daemon when one
 // fits and falling back to a one-shot mobile-mcp spawn otherwise. Returns
@@ -63,6 +66,8 @@ async function sessionStatus(projectRoot, { client = sessionClient } = {}) {
   const status = await client.getSessionStatus(projectRoot);
   return {
     ...status,
+    // Always present (#156): null, or why a reachable daemon is not running.
+    reason: (status && status.reason) || null,
     log_path: paths.logFilePath(projectRoot),
     // Read from the handle, not from the ping reply. The handle is written once
     // the daemon is listening and removed by stop(), so it is the same fact
@@ -82,9 +87,72 @@ function startSession({ projectRoot, device = null, idleMs, spawn = sessionSpawn
   return spawn.spawnDaemon({ projectRoot, device, idleMs });
 }
 
-// Ask a live daemon to shut down. Resolves true when one acknowledged.
-function endSession(projectRoot, { client = sessionClient } = {}) {
-  return client.requestShutdown(projectRoot);
+// How long `session end` waits for an acknowledged daemon to exit before it
+// treats it as stuck: stop() drains in-flight calls (bounded by the daemon call
+// timeout) and then closes the engine (the SDK's ~4s ladder). Derived, not
+// restated; pinned by tests/unit/device/timeout-invariant.test.js.
+const END_BUDGET_MS = sessionDaemon.DAEMON_CALL_TIMEOUT_MS + 10000;
+
+// Stop the daemon and report only what is true (#156). The daemon acks the
+// shutdown frame BEFORE its teardown runs, so an ack is a promise, not a fact:
+// 'stopped' is reported only once the pid is gone.
+//
+// Returns { outcome, pid } — ONE discriminated answer, so a caller dispatches
+// on what happened instead of re-deriving it from a bag of booleans:
+//   'stopped'         - acked, and the pid exited (or there was no pid to watch)
+//   'already_stopped' - nothing acked and nothing of ours was running
+//   'forced'          - ours, stuck in teardown, terminated by a group kill
+//   'survived'        - ours, stuck, and still alive after SIGTERM + SIGKILL
+//   'foreign'         - acked, but the live pid's command line does not name
+//                       this workspace, so it was reported, never signalled
+//   'unverified'      - the pid could not be identified (`ps` failed), so it
+//                       was never signalled
+// The last three are failures: a daemon may still be alive.
+async function endSession(
+  projectRoot,
+  {
+    client = sessionClient,
+    reaper = processReaper,
+    // Bound to THIS workspace (#156): a group kill must never reach another
+    // workspace's daemon through a copied or recycled pidfile.
+    identify = (pid) => processIdentity.pidIdentity(pid, { projectRoot }),
+    readPid = () => processIdentity.readPidFile(paths.pidFilePath(projectRoot)),
+    budgetMs = END_BUDGET_MS,
+  } = {}
+) {
+  // Read BEFORE asking: a daemon that exits cleanly removes its pidfile, and we
+  // need to know whom to watch.
+  const pid = readPid();
+  const acked = await client.requestShutdown(projectRoot);
+  const report = (outcome) => ({ outcome, pid: pid || null });
+  // The daemon is gone: it stopped because we asked, or was never running.
+  const gone = () => report(acked ? 'stopped' : 'already_stopped');
+
+  // No pidfile: nothing to watch, so the ack is all we have (as before). Our
+  // own pid: the in-process daemon of a test — never wait on it, never signal it.
+  if (!pid || pid === process.pid) return gone();
+
+  // A non-acking daemon whose pidfile names a live process is checked at once
+  // (budget 0): either it is gone, or it is stuck too badly to answer.
+  if (await reaper.waitForDeath(pid, { budgetMs: acked ? budgetMs : 0 })) return gone();
+
+  switch (identify(pid)) {
+    case 'dead':
+    case 'other': // the pid was recycled: our daemon is gone
+      return gone();
+    case 'foreign':
+      // A mauto daemon whose command line does not name this workspace:
+      // another workspace's, reached through a copied or recycled pidfile.
+      // Never signalled. Without an ack nothing answered on OUR socket, so none
+      // of ours was running. With an ack the daemon that answered is ours, but
+      // its command line cannot prove it (one started before the workspace
+      // marker), so it is reported rather than killed.
+      return report(acked ? 'foreign' : 'already_stopped');
+    case 'ours':
+      return report((await reaper.terminate(pid, { group: true })) === 'dead' ? 'forced' : 'survived');
+    default: // 'unknown': never signal a process we cannot identify
+      return report('unverified');
+  }
 }
 
 module.exports = {
@@ -97,4 +165,5 @@ module.exports = {
   sessionStatus,
   startSession,
   endSession,
+  END_BUDGET_MS,
 };

package/src/device/device-resolver.js

@@ -11,7 +11,8 @@ class DeviceResolutionError extends Error {
   }
 }
 
-// mobile-mcp 0.0.55 requires a concrete device id on every action/read tool.
+// mobile-mcp 1.0.5 requires a concrete device id on every action/read tool
+// (tests/integration/mobile-mcp-contract.test.js pins this against the engine).
 // When the caller pinned nothing (no --device, no persisted selection), we
 // auto-discover: exactly one active device is used; zero or many is a clear,
 // actionable failure rather than a silent empty result.

package/src/device/element-model.js

@@ -58,25 +58,47 @@ function normalize(rawElements) {
   return out;
 }
 
-// mobile-mcp 0.0.55 returns elements as the string
-// `Found these elements on screen: <JSON array>`. Earlier/other shapes may be
-// a bare array or `{elements:[...]}`. Parse all three into the raw element
-// array. Parse the WHOLE JSON array (never per-element regex) so labels
-// containing brackets/quotes/newlines survive.
+// Short, single-line excerpt of an unparseable payload for the error message:
+// the FIRST non-empty line only, capped, so a multi-kilobyte screen dump never
+// floods the envelope but the reader still sees what shape came back.
+const EXCERPT_MAX = 120;
+function excerptOf(text) {
+  const line = (text.split(/\r?\n/).find((l) => l.trim() !== '') || '').trim();
+  return line.length > EXCERPT_MAX ? `${line.slice(0, EXCERPT_MAX)}…` : line;
+}
+
+// mobile-mcp returns elements as the string
+// `Found these elements on screen: <JSON array>` (0.0.55, and 1.0.5 when called
+// with format:"json"). Earlier/other shapes may be a bare array or
+// `{elements:[...]}`. Parse all three into the raw element array. Parse the
+// WHOLE JSON array (never per-element regex) so labels containing
+// brackets/quotes/newlines survive.
+//
+// A non-empty string we cannot parse THROWS rather than returning []: mobile-mcp
+// 1.0.5 defaults this tool to a line-per-element text format whose header
+// contains `[focused] ... [disabled]`, and a silent [] there reported `ok:true`
+// with an empty screen — the failure probe then blamed the app (#199). An empty
+// or whitespace-only string stays [] because it carries no content to misread:
+// it is not evidence of a format change. null / non-string values stay [] for
+// the same reason.
 function parseElements(raw) {
   if (Array.isArray(raw)) return raw;
   if (raw && Array.isArray(raw.elements)) return raw.elements;
-  if (typeof raw === 'string') {
-    const start = raw.indexOf('[');
-    const end = raw.lastIndexOf(']');
-    if (start !== -1 && end > start) {
-      try {
-        const parsed = JSON.parse(raw.slice(start, end + 1));
-        if (Array.isArray(parsed)) return parsed;
-      } catch (_e) { /* fall through */ }
-    }
+  if (typeof raw !== 'string' || raw.trim() === '') return [];
+
+  const start = raw.indexOf('[');
+  const end = raw.lastIndexOf(']');
+  if (start !== -1 && end > start) {
+    try {
+      const parsed = JSON.parse(raw.slice(start, end + 1));
+      if (Array.isArray(parsed)) return parsed;
+    } catch (_e) { /* fall through to the loud failure below */ }
   }
-  return [];
+  const err = new Error(`The element list could not be parsed. Engine returned: "${excerptOf(raw)}"`);
+  err.hint =
+    'The mobile-mcp engine likely changed its element output format (e.g. text instead of JSON). ' +
+    'Check the installed @mobilenext/mobile-mcp version matches the one mobile-automator pins.';
+  throw err;
 }
 
 module.exports = { normalize, parseElements };

package/src/device/engine-hints.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Actionable hints for device-engine failures whose raw message alone does not
+// tell the user what to do. Pure: message in, hint string (or null) out. It
+// never throws — a hint classifier that crashes would turn a device failure
+// into an internal one. Found by the #199 real-device run against mobile-mcp
+// 1.0.5 / mobilecli 1.0.13.
+//
+// mauto only TELLS the user which command to run; it never runs mobilecli
+// itself (the device is driven only through mauto verbs, which wrap
+// mobile-mcp).
+
+const ISSUE_459 = 'https://github.com/mobile-next/mobile-mcp/issues/459';
+
+// The mobilecli that the pinned mobile-mcp actually spawns — resolved from
+// mobile-mcp's own directory, since that is the copy whose agent the device
+// must match. Null when it cannot be resolved; the caller omits `@<version>`.
+function resolveMobilecliVersion() {
+  const mcpDir = path.dirname(require.resolve('@mobilenext/mobile-mcp/package.json'));
+  const pkgPath = require.resolve('mobilecli/package.json', { paths: [mcpDir] });
+  // Read, not require(): a non-literal require specifier is unverifiable to
+  // tests/lint/telemetry-transport-isolation.test.js.
+  return JSON.parse(fs.readFileSync(pkgPath, 'utf8')).version || null;
+}
+
+function safeVersion(resolver) {
+  try {
+    const v = resolver();
+    return typeof v === 'string' && v ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+// B1 (iOS): mobilecli `agent status` exits 1 when the DeviceKit agent is
+// missing and mobile-mcp runs it via execFileSync, so the throw skips its own
+// auto-install (upstream mobile-mcp#459). Every verb fails until the agent is
+// installed once by hand.
+function missingAgentHint(message, resolver) {
+  const version = safeVersion(resolver);
+  const pkg = version ? `mobilecli@${version}` : 'mobilecli';
+  const cmd = `npx -y ${pkg} agent install --device`;
+  const m = /--device\s+(\S+)/.exec(message);
+  const install = m
+    ? `\`${cmd} ${m[1]}\``
+    : `\`${cmd}\` followed by the simulator's id from \`mauto devices\``;
+  return (
+    'The simulator is missing the device agent the engine needs, and the engine cannot install it ' +
+    `itself (upstream bug ${ISSUE_459}). Install it once with ${install} ` +
+    '(needs network, takes a few seconds), then retry.'
+  );
+}
+
+// B2: mobile-mcp 1.0.5's default robot lists Android emulators by AVD name,
+// MOBILEMCP_LEGACY_ROBOT=1 (and 0.0.55) by adb serial, and each rejects the
+// other's id — so a selection persisted before the upgrade fails every verb.
+function deviceNotFoundHint(id) {
+  return (
+    `Device "${id}" is not known to the current engine. Device ids can differ between engines: ` +
+    "mauto 0.27's default engine lists Android emulators by AVD name (e.g. Pixel_9_Pro), while " +
+    'MOBILEMCP_LEGACY_ROBOT=1 uses the adb serial (e.g. emulator-5554). Run `mauto devices`, then ' +
+    '`mauto devices use` with an id from that list (or pass that id to --device).'
+  );
+}
+
+function engineHint(message, { mobilecliVersion = resolveMobilecliVersion } = {}) {
+  try {
+    if (typeof message !== 'string' || !message) return null;
+    if (/Agent is not installed on the device/.test(message)) {
+      return missingAgentHint(message, mobilecliVersion);
+    }
+    const notFound = /Device "([^"]+)" not found/.exec(message);
+    if (notFound) return deviceNotFoundHint(notFound[1]);
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { engineHint };