mobile-automator 0.27.1 → 0.28.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-automator",
-  "version": "0.27.1",
+  "version": "0.28.1",
   "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": {
@@ -41,8 +41,7 @@
   "devDependencies": {
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
-    "js-yaml": "^4.3.2",
-    "toml": "^3.0.0"
+    "js-yaml": "^4.3.2"
   },
   "engines": {
     "node": ">=22.12.0"

package/src/cli.js

@@ -1234,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 -------------------

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/mobile-mcp-client.js

@@ -6,6 +6,26 @@ const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio
 const { injectDeviceArg } = require('./tool-args');
 const { resolveSingleDevice } = require('./device-resolver');
 const { normalizeDevices } = require('./device-model');
+const { ErrorCode } = require('@modelcontextprotocol/sdk/types.js');
+
+// Bound on mobile-mcp's MCP initialize handshake (#156). Measured at ~200ms on
+// mobile-mcp 1.0.5 — initialize touches no device — so 10s is ~50x headroom.
+// The spawner kills an unready daemon when its readiness window closes, and a
+// failed connect is reported only once the engine is reaped, so
+// CONNECT_TIMEOUT_MS + ENGINE_REAP_MAX_MS, plus headroom for the daemon's own
+// boot, MUST stay below session-spawn's DEFAULT_READY_TIMEOUT_MS — or the
+// daemon is killed instead of failing with its own daemon.connect_failure.
+// Pinned by tests/unit/device/timeout-invariant.test.js.
+// (The SDK's own default is 60s, which is longer than the window watching it.)
+const CONNECT_TIMEOUT_MS = 10000;
+
+// A failed connect terminates the engine at once rather than waiting out the
+// SDK's fire-and-forget close (stdin end → 2s → SIGTERM → 2s → SIGKILL): an
+// engine that never initialized has nothing to flush, and every second spent
+// here is spent inside the spawner's readiness window. SIGTERM, SIGKILL after
+// ENGINE_KILL_GRACE_MS, then up to ENGINE_KILL_GRACE_MS more for the death.
+const ENGINE_KILL_GRACE_MS = 1000;
+const ENGINE_REAP_MAX_MS = 2 * ENGINE_KILL_GRACE_MS;
 
 // Resolve the mobile-mcp server entry point from the bundled, pinned
 // dependency rather than fetching `@latest` at runtime. We read the package's
@@ -26,25 +46,92 @@ function resolveServerEntry() {
   return path.join(pkgDir, binRel);
 }
 
+// The environment mauto's own engine process is spawned with. Pure: returns a
+// new object and never mutates baseEnv.
+//
+// MOBILEMCP_ALLOW_UNSAFE_URLS defaults to "1" (#212). mobile-mcp rejects every
+// non-http(s) URL in mobile_open_url unless it is set, which blocks the
+// documented `open_url` deep-link capability (myapp://...). That guard exists to
+// stop an LLM whose ONLY reach is MCP from opening arbitrary schemes; an agent
+// driving mauto already has a shell and could open the same URL via adb or
+// simctl, so under mauto it protects nothing. The URL reaches the device as an
+// argv element on the default mobilecli robot (no shell), and the legacy adb
+// robot escapes shell metacharacters. A user-set value wins: the engine only
+// accepts the exact string "1", so MOBILEMCP_ALLOW_UNSAFE_URLS=0 restores the
+// guard. The env is read when the engine spawns, so a running session daemon
+// must be ended (`mauto session end`) before a change takes effect.
+function buildEngineEnv({ device = null, baseEnv = process.env } = {}) {
+  const env = {
+    ...baseEnv,
+    MOBILEMCP_ALLOW_UNSAFE_URLS: baseEnv.MOBILEMCP_ALLOW_UNSAFE_URLS ?? '1',
+  };
+  // mobile-mcp reads the target device from the environment / its own
+  // selection; we pass it through when provided so callers can pin a device.
+  if (device) env.MOBILE_MCP_DEVICE = device;
+  return env;
+}
+
+// The SDK transport, remembering the engine pid the moment the child is spawned
+// (#156). It has to be remembered: on a failed connect the SDK runs
+// `void this.close()`, and StdioClientTransport.close() clears its pid
+// synchronously — so by the time createCall's catch runs, `pid` is already null
+// while the child may still be alive. `spawnedPid` is never cleared.
+// Client.connect() awaits transport.start(), which is what makes start() the
+// place to read it; tests/integration/engine-lifecycle.test.js pins that against
+// the real SDK (a failed connect still reaps the engine).
+function pidTracking(Transport) {
+  return class PidTrackingTransport extends Transport {
+    async start() {
+      await super.start();
+      this.spawnedPid = this.pid;
+    }
+  };
+}
+
 // Integration glue: spawns mobile-mcp over stdio and returns a `call`
 // function shaped exactly like the one DeviceBridge expects.
-// NOT unit-tested (would require spawning mobile-mcp); see the smoke test.
-async function createCall({ device } = {}) {
-  const serverEntry = resolveServerEntry();
-  const transport = new StdioClientTransport({
-    command: process.execPath,
-    args: [serverEntry],
-    // mobile-mcp reads the target device from the environment / its own
-    // selection; we pass it through when provided so callers can pin a device.
-    env: device ? { ...process.env, MOBILE_MCP_DEVICE: device } : process.env,
+//
+// `sdk`, `server` and `reaper` are test seams: production passes none of them.
+// tests/unit/device/mobile-mcp-client-lifecycle.test.js drives this against a
+// fake SDK; tests/integration/engine-lifecycle.test.js against the real SDK and
+// a fixture MCP server.
+async function createCall({
+  device,
+  connectTimeoutMs = CONNECT_TIMEOUT_MS,
+  onEngineExit = null,
+  sdk = { Client, StdioClientTransport },
+  server = null,
+  reaper = require('./process-reaper'),
+} = {}) {
+  // Resolved lazily, here, so the module still loads without mobile-mcp installed.
+  const { command, args } = server || { command: process.execPath, args: [resolveServerEntry()] };
+  const Transport = pidTracking(sdk.StdioClientTransport);
+  const transport = new Transport({
+    command,
+    args,
+    env: buildEngineEnv({ device }),
   });
 
-  const client = new Client(
-    { name: 'mauto', version: '0.1.0' },
-    { capabilities: {} }
-  );
+  const client = new sdk.Client({ name: 'mauto', version: '0.1.0' }, { capabilities: {} });
+
+  // Engine liveness (#156). The SDK fires onclose on EVERY child close — a real
+  // engine death and our own close() alike — so `closing` separates the two.
+  // A failed connect also sets it: that failure is reported by the throw.
+  let closing = false;
+  let reported = false;
+  client.onclose = () => {
+    if (closing || reported) return;
+    reported = true;
+    if (typeof onEngineExit === 'function') onEngineExit();
+  };
 
-  await client.connect(transport);
+  try {
+    await client.connect(transport, { timeout: connectTimeoutMs });
+  } catch (err) {
+    closing = true;
+    await reapEngine(transport.spawnedPid, reaper);
+    throw connectError(err, connectTimeoutMs);
+  }
 
   async function rawCall(toolName, args = {}) {
     const res = await client.callTool({ name: toolName, arguments: args });
@@ -53,6 +140,7 @@ async function createCall({ device } = {}) {
   const { call } = makeCall({ rawCall, device });
 
   async function close() {
+    closing = true;
     try {
       await client.close();
     } catch (_e) {
@@ -63,6 +151,27 @@ async function createCall({ device } = {}) {
   return { call, close };
 }
 
+// The SDK's connect-failure cleanup is fire-and-forget, so the engine is
+// terminated here, at once, and the error leaves createCall only once it is
+// gone — nothing may outlive the failure it reports. The budget-0 check first:
+// an engine that already exited (the ConnectionClosed path) is not signalled.
+// group:false: the engine is not a process-group leader.
+async function reapEngine(pid, reaper) {
+  if (!pid) return;
+  if (await reaper.waitForDeath(pid, { budgetMs: 0 })) return;
+  await reaper.terminate(pid, { group: false, graceMs: ENGINE_KILL_GRACE_MS });
+}
+
+// A timed-out initialize becomes an error that names the bound; anything else
+// (spawn ENOENT, a protocol mismatch) passes through untouched.
+function connectError(err, timeoutMs) {
+  if (!(err && err.code === ErrorCode.RequestTimeout)) return err;
+  const e = new Error(`mobile-mcp did not finish initializing within ${timeoutMs}ms`);
+  e.code = 'ENGINE_CONNECT_TIMEOUT';
+  e.cause = err;
+  return e;
+}
+
 // Pure orchestration over a low-level rawCall(toolName, args) => Promise<parsed>.
 // Threads a concrete device id into every tool call except the discovery verb,
 // lazily auto-discovering a single device when none was pinned (cached after
@@ -162,4 +271,12 @@ function parseToolResult(res) {
 
 // resolveServerEntry is exported so tests/integration/mobile-mcp-contract.test.js
 // spawns the pinned engine by the exact path production does, not a copy of it.
-module.exports = { createCall, makeCall, parseToolResult, resolveServerEntry };
+module.exports = {
+  createCall,
+  makeCall,
+  parseToolResult,
+  resolveServerEntry,
+  CONNECT_TIMEOUT_MS,
+  ENGINE_REAP_MAX_MS,
+  buildEngineEnv,
+};

package/src/device/process-identity.js

@@ -0,0 +1,124 @@
+'use strict';
+
+// Process identity for the device session lifecycle (#156): is a pid alive,
+// is it a zombie awaiting a reaper, is it OUR daemon, and which pid does a
+// pid/lock file name. A leaf module on purpose — session-daemon.js (cleanStale),
+// process-reaper.js (its waits) and connection.js (`session end`) all ask these
+// questions, and none of them should have to load the daemon to do so.
+//
+// Every effect that can fail on a slim host (`ps`, /proc) is injectable, so the
+// classification is unit-testable against a fake process table.
+
+const childProcess = require('child_process');
+const fs = require('fs');
+
+const paths = require('./session-paths');
+
+// True when a pid is a live process we own. ESRCH => dead; EPERM => alive.
+// cleanStale routes through pidIdentity, which also checks the process's
+// identity (not just liveness).
+function pidAlive(pid) {
+  if (!pid || !Number.isInteger(pid)) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+// Has `pid` exited and is only awaiting a parent to reap it? kill(pid, 0)
+// succeeds on a zombie, so pidAlive alone calls an exited process alive (#156).
+// That is the normal end state of a daemon wherever PID 1 does not reap
+// adopted orphans — Docker without --init, CI job containers whose PID 1 is
+// `tail -f /dev/null`, a Node agent host running as PID 1 — because the
+// detached daemon is reparented to it when the verb that spawned it exits.
+// Any failure to tell answers "not a zombie", so liveness decides as before.
+// Used by process-reaper.js's waits; lives here, beside pidAlive and
+// pidIdentity, because this is the module that runs `ps`.
+function isZombie(
+  pid,
+  { platform = process.platform, readFile = fs.readFileSync, execFile = childProcess.execFileSync } = {}
+) {
+  try {
+    if (platform === 'linux') {
+      // "pid (comm) S ..." — comm may itself contain spaces or ')', so the state
+      // is the field after the LAST ')'. Reading /proc needs no `ps`, which
+      // slim container images do not ship.
+      const stat = String(readFile(`/proc/${pid}/stat`, 'utf8'));
+      return /^\s*[ZX]/.test(stat.slice(stat.lastIndexOf(')') + 1));
+    }
+    const out = execFile('ps', ['-o', 'stat=', '-p', String(pid)], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return /^\s*Z/.test(String(out));
+  } catch (_) {
+    return false;
+  }
+}
+
+// Classify a pid by liveness AND identity. Liveness alone is not enough: a
+// recycled pid (an unrelated process that inherited the dead daemon's pid) is
+// "alive" but is NOT our daemon, so a stale lock/pidfile pointing at it must be
+// cleaned rather than respected. Returns one of:
+//   'dead'    - no such process (ESRCH or any non-EPERM kill error)
+//   'ours'    - alive AND its command line contains `mauto-session-daemon`
+//               (and, when `projectRoot` is given, names THAT workspace)
+//   'foreign' - only with `projectRoot`: alive and a mauto daemon, but its
+//               command line does not name that workspace (#156) — another
+//               workspace's daemon, one started before the workspace marker
+//               existed, or an editor open on the bin. Never ours to signal.
+//   'other'   - alive AND its command line does NOT (recycled pid)
+//   'unknown' - alive but `ps` itself failed (e.g. no `ps` on the host) —
+//               treated as 'ours' by cleanStale: never clean when unsure.
+// `execFile` is injectable for tests; a failure there must never crash the
+// daemon, hence the 'unknown' fallback.
+//
+// cleanStale passes no projectRoot and keeps the binary-level answer: there a
+// wrong 'ours' only means stale files are left alone. `session end` passes one,
+// because there a wrong 'ours' sends a process-group kill (src/device/connection.js).
+function pidIdentity(pid, { execFile = childProcess.execFileSync, projectRoot = null } = {}) {
+  if (!pid || !Number.isInteger(pid)) return 'dead';
+  // Our own pid is the in-process daemon (unit tests run startDaemon in the
+  // test process, so the lock/pidfile carry the test runner's pid). Never clean
+  // files that point at ourselves. In production cleanStale runs before the
+  // daemon writes its own pid/lock, so this branch only fires in-process.
+  if (pid === process.pid) return 'ours';
+  let alive;
+  try {
+    process.kill(pid, 0);
+    alive = true;
+  } catch (err) {
+    if (err.code === 'EPERM') alive = true;
+    else return 'dead';
+  }
+  if (!alive) return 'dead';
+  try {
+    // -ww: never truncate the line — the workspace marker is at its END. stderr
+    // ignored: a failing `ps` is already the 'unknown' answer, not verb output.
+    const out = String(
+      execFile('ps', ['-ww', '-p', String(pid), '-o', 'command='], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }) || ''
+    );
+    if (!/mauto-session-daemon/.test(out)) return 'other';
+    if (projectRoot == null) return 'ours';
+    return paths.commandNamesWorkspace(out, projectRoot) ? 'ours' : 'foreign';
+  } catch (_) {
+    return 'unknown';
+  }
+}
+
+// Read a pid out of a one-line pid/lock file, or null when absent/garbage.
+function readPidFile(file) {
+  try {
+    const pid = parseInt(fs.readFileSync(file, 'utf8').trim(), 10);
+    return Number.isInteger(pid) ? pid : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = { pidAlive, isZombie, pidIdentity, readPidFile };

package/src/device/process-reaper.js

@@ -0,0 +1,123 @@
+'use strict';
+
+// Process termination for the device session lifecycle (#156). Two callers:
+// session-spawn.js kills a daemon that never became ready, and `session end`
+// (connection.js) escalates a daemon stuck in teardown.
+//
+// Mechanism only. This module never decides WHOSE pid it is signalling — the
+// spawner holds its own ChildProcess, and `session end` runs pidIdentity first.
+// Every effect (kill, liveness, clock) is injected so the escalation policy is
+// tested once, here, against a fake process table.
+
+const { pidAlive, isZombie } = require('./process-identity');
+
+// Alive, and not merely awaiting a reaper (#156): kill(pid, 0) succeeds on a
+// zombie, so plain liveness waits out a whole budget for a daemon that has
+// already exited wherever PID 1 does not reap (see isZombie). The default
+// liveness for every wait below; the zombie check runs only for a pid that
+// kill(pid, 0) calls alive.
+function processAlive(pid) {
+  return pidAlive(pid) && !isZombie(pid);
+}
+
+// Deliberately NOT unref'd: `session end` is a one-shot verb process with
+// nothing else on its event loop while it waits, so an unref'd timer would let
+// the process exit mid-wait and report nothing.
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Resolves true as soon as `done()` holds, false once `budgetMs` has elapsed.
+// budgetMs 0 is a single check.
+async function waitUntil(done, { budgetMs, pollMs, sleep, now }) {
+  const deadline = now() + budgetMs;
+  for (;;) {
+    if (done()) return true;
+    const left = deadline - now();
+    if (left <= 0) return false;
+    await sleep(Math.min(pollMs, left));
+  }
+}
+
+// Resolves true as soon as `pid` is dead, false once `budgetMs` has elapsed.
+// budgetMs 0 is a single check.
+function waitForDeath(
+  pid,
+  { budgetMs, pollMs = 100, isAlive = processAlive, sleep = defaultSleep, now = Date.now } = {}
+) {
+  return waitUntil(() => !isAlive(pid), { budgetMs, pollMs, sleep, now });
+}
+
+// Does process group `pgid` still have a member? kill(-pgid, 0) succeeds while
+// any member exists; EPERM means members we may not signal, which still exist.
+function groupExists(kill, pgid) {
+  try {
+    kill(-pgid, 0);
+    return true;
+  } catch (err) {
+    return !!(err && err.code === 'EPERM');
+  }
+}
+
+// One signal. 'denied' (EPERM) means a process we may not signal, which is not
+// ours to report as killed. ESRCH is NOT trusted as death: for a group kill it
+// can mean "no such group" while the pid itself is alive, so the caller always
+// confirms with isAlive.
+function send(kill, target, sig) {
+  try {
+    kill(target, sig);
+    return 'sent';
+  } catch (err) {
+    if (err && err.code === 'EPERM') return 'denied';
+    if (err && err.code === 'ESRCH') return 'gone';
+    throw err;
+  }
+}
+
+// SIGTERM, wait up to graceMs, SIGKILL, wait up to graceMs, report.
+//
+// group:true signals -pid, the process GROUP. That only works for a group
+// leader: the daemon is one because session-spawn.js spawns it with
+// `detached: true`, which is also what makes -pid reach the mobile-mcp engine
+// and its mobilecli (spawned non-detached, so in the daemon's group). Remove
+// `detached` there and -pid becomes ESRCH — reported here as 'survived', never
+// as a false 'dead'. group:false is for the engine child, which leads no group.
+//
+// For a group, SIGTERM is enough only once the leader AND every member are
+// gone (#156). The leader alone is not the group: a daemon before listen() has
+// no SIGTERM handler and dies at once, while mobile-mcp installs one that a
+// blocked event loop cannot run — so the engine outlives the leader and must
+// still get the SIGKILL. SIGKILL cannot be caught, so after it the leader's
+// death is the answer (a member left behind is a zombie awaiting its reaper).
+async function terminate(
+  pid,
+  {
+    group = true,
+    graceMs = 2000,
+    pollMs = 50,
+    kill = process.kill.bind(process),
+    isAlive = processAlive,
+    sleep = defaultSleep,
+    now = Date.now,
+  } = {}
+) {
+  // kill(0) / kill(-1) / a negative pid would signal our own group or every
+  // process we own. Refuse rather than guess. A GROUP kill of pid 1 is
+  // kill(-1) — the same broadcast — so it is refused too.
+  if (!Number.isInteger(pid) || pid <= 0 || (group && pid === 1)) {
+    throw new TypeError(`terminate requires a positive integer pid${group ? ' above 1' : ''}, got ${pid}`);
+  }
+  const target = group ? -pid : pid;
+  const wait = { budgetMs: graceMs, pollMs, sleep, now };
+  const gone = group
+    ? () => !isAlive(pid) && !groupExists(kill, pid)
+    : () => !isAlive(pid);
+
+  if (send(kill, target, 'SIGTERM') === 'denied') return isAlive(pid) ? 'survived' : 'dead';
+  if (await waitUntil(gone, wait)) return 'dead';
+  if (send(kill, target, 'SIGKILL') === 'denied') return isAlive(pid) ? 'survived' : 'dead';
+  if (await waitUntil(() => !isAlive(pid), wait)) return 'dead';
+  return 'survived';
+}
+
+module.exports = { waitForDeath, terminate, processAlive };

package/src/device/session-client.js

@@ -150,21 +150,27 @@ async function requestShutdown(projectRoot) {
 // Rich status probe: connect + ping and report whether a daemon is running,
 // how many device calls are currently in flight (the double-execution window
 // is visible here), and which device it is pinned to. `null`s when not running.
+//
+// A daemon whose engine has died is NOT running (#156): it is draining toward
+// its own exit and can never serve a call. Only an explicit engine_alive:false
+// counts — a pre-0.28 daemon omits the field and is treated as alive.
 async function getSessionStatus(projectRoot) {
+  const down = { running: false, reason: null, in_flight: null, device: null };
   const socket = await connectSocket(paths.socketPath(projectRoot));
-  if (!socket) return { running: false, in_flight: null, device: null };
+  if (!socket) return down;
   const client = wrapSocket(socket);
   try {
     const res = await client.request({ type: 'ping' }, { timeoutMs: 2000 });
-    if (!(res && res.ok)) return { running: false, in_flight: null, device: null };
+    if (!(res && res.ok)) return down;
     const result = res.result || {};
-    return {
-      running: true,
+    const seen = {
       in_flight: typeof result.in_flight === 'number' ? result.in_flight : null,
       device: result.device != null ? result.device : null,
     };
+    if (result.engine_alive === false) return { running: false, reason: 'engine_exited', ...seen };
+    return { running: true, reason: null, ...seen };
   } catch (_) {
-    return { running: false, in_flight: null, device: null };
+    return down;
   } finally {
     await client.close();
   }

package/src/device/session-daemon.js

@@ -18,7 +18,6 @@
 // Everything that touches a real device is injected, so the full lifecycle is
 // unit-testable with a fake createCall and a mkdtemp project root.
 
-const childProcess = require('child_process');
 const fs = require('fs');
 const net = require('net');
 
@@ -28,6 +27,7 @@ const { newSessionId } = require('./session-handle');
 const { makeDeviceCall } = require('./device-call');
 const { safeObserve: guardObserve } = require('../observe/recorder');
 const { FLUSH_INTERVAL_MS } = require('../observe/flush');
+const { pidIdentity, readPidFile } = require('./process-identity');
 
 const DEFAULT_IDLE_MS = 5 * 60 * 1000;
 
@@ -62,64 +62,6 @@ function safeUnlink(p) {
   }
 }
 
-// True when a pid is a live process we own. ESRCH => dead; EPERM => alive.
-// Kept exported for back-compat; cleanStale routes through pidIdentity, which
-// also checks the process's identity (not just liveness).
-function pidAlive(pid) {
-  if (!pid || !Number.isInteger(pid)) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === 'EPERM';
-  }
-}
-
-// Classify a pid by liveness AND identity. Liveness alone is not enough: a
-// recycled pid (an unrelated process that inherited the dead daemon's pid) is
-// "alive" but is NOT our daemon, so a stale lock/pidfile pointing at it must be
-// cleaned rather than respected. Returns one of:
-//   'dead'    - no such process (ESRCH or any non-EPERM kill error)
-//   'ours'    - alive AND its command line contains `mauto-session-daemon`
-//   'other'   - alive AND its command line does NOT (recycled pid)
-//   'unknown' - alive but `ps` itself failed (e.g. no `ps` on the host) —
-//               treated as 'ours' by cleanStale: never clean when unsure.
-// `execFile` is injectable for tests; a failure there must never crash the
-// daemon, hence the 'unknown' fallback.
-function pidIdentity(pid, { execFile = childProcess.execFileSync } = {}) {
-  if (!pid || !Number.isInteger(pid)) return 'dead';
-  // Our own pid is the in-process daemon (unit tests run startDaemon in the
-  // test process, so the lock/pidfile carry the test runner's pid). Never clean
-  // files that point at ourselves. In production cleanStale runs before the
-  // daemon writes its own pid/lock, so this branch only fires in-process.
-  if (pid === process.pid) return 'ours';
-  let alive;
-  try {
-    process.kill(pid, 0);
-    alive = true;
-  } catch (err) {
-    if (err.code === 'EPERM') alive = true;
-    else return 'dead';
-  }
-  if (!alive) return 'dead';
-  try {
-    const out = execFile('ps', ['-p', String(pid), '-o', 'command='], { encoding: 'utf8' });
-    return /mauto-session-daemon/.test(String(out || '')) ? 'ours' : 'other';
-  } catch (_) {
-    return 'unknown';
-  }
-}
-
-// Read a pid out of a one-line pid/lock file, or null when absent/garbage.
-function readPidFile(file) {
-  try {
-    const pid = parseInt(fs.readFileSync(file, 'utf8').trim(), 10);
-    return Number.isInteger(pid) ? pid : null;
-  } catch (_) {
-    return null;
-  }
-}
-
 // Remove stale socket/pidfile/handle/lock left by a crashed daemon so a fresh
 // daemon can bind. Identity is decided from the LOCK file first (acquired before
 // the connection is built, so it covers a daemon still mid-startup) then the
@@ -161,7 +103,9 @@ async function startDaemon({
   createCall = defaultCreateCall,
   onUndeliverable = null,
   scheduleTimeout = defaultScheduleTimeout,
-  execFile = childProcess.execFileSync,
+  // `ps` seam for cleanStale's identity check; undefined keeps
+  // process-identity.js's real execFileSync, so this module runs no `ps` itself.
+  execFile,
   // Structured observability, injected as a FACTORY rather than as a ready-made
   // recorder. See the binding below for why it has to be a factory.
   //
@@ -296,12 +240,31 @@ async function startDaemon({
     safeUnlink(lockFile);
   }
 
+  // Engine liveness (#156). `serving` flips once the daemon is listening and
+  // about to write its handle. Before that an engine exit only clears
+  // `engineAlive` — the check after listen() below turns it into a failed start,
+  // so no handle is ever written for a dead engine. After it, an engine exit
+  // reaps the daemon: recorded first and synchronously, like the crash guards,
+  // because stop() can block on the in-flight drain. stop() is the existing path
+  // unchanged: drain, destroy sockets, close the server, close() (a no-op on a
+  // dead engine), unlink, release the lock, resolve whenStopped. The next verb
+  // autostarts a fresh daemon.
+  let engineAlive = true;
+  let serving = false;
+  function onEngineExit() {
+    if (!engineAlive) return;
+    engineAlive = false;
+    if (!serving) return;
+    safeObserve({ level: 'error', event: 'daemon.engine_exit', dur_ms: Date.now() - startedAtMs });
+    stop('engine_exit').catch(() => {});
+  }
+
   // Build the single shared connection up front. If it rejects, never leak the
   // lock (and the child it may have started is the connection's own to clean).
   let call;
   let close;
   try {
-    ({ call, close } = await createCall({ device }));
+    ({ call, close } = await createCall({ device, onEngineExit }));
   } catch (err) {
     // #156's core symptom: mobile-mcp never came up, and until now the only
     // trace was a 15s readiness timeout in the spawning verb.
@@ -599,7 +562,11 @@ async function startDaemon({
           continue;
         }
         if (req.type === 'ping') {
-          await reply({ id: req.id, ok: true, result: { pong: true, device, in_flight: inFlight } });
+          await reply({
+            id: req.id,
+            ok: true,
+            result: { pong: true, device, in_flight: inFlight, engine_alive: engineAlive },
+          });
           armIdle();
           continue;
         }
@@ -661,25 +628,23 @@ async function startDaemon({
 
   const socketPath = paths.socketPath(projectRoot);
 
-  try {
-    await new Promise((resolve, reject) => {
-      server.once('error', reject);
-      server.listen(socketPath, () => {
-        server.removeListener('error', reject);
-        resolve();
-      });
-    });
-  } catch (err) {
-    // listen failed (e.g. EADDRINUSE from a double-spawn that beat us to the
-    // bind, or a recycled-pid wedge). The connection was already built — close
-    // it so we never leak the mobile-mcp child, and release the lock.
+  // A start that fails once the connection exists: record why, undo what was
+  // built (the listening socket, if any, then the engine), release the lock, and
+  // rethrow — so a failed start never leaks the mobile-mcp child or wedges the
+  // next spawn behind a held lock. The connect failure above has no `close` yet
+  // and so does its own, smaller teardown.
+  async function abortStart({ event, err, listening }) {
     safeObserve({
       level: 'error',
-      event: 'daemon.listen_failure',
+      event,
       error_code: err && err.code,
       message: err && (err.message || String(err)),
       dur_ms: Date.now() - startedAtMs,
     });
+    if (listening) {
+      await new Promise((resolve) => server.close(() => resolve()));
+      safeUnlink(socketPath);
+    }
     try {
       await close();
     } catch (_) {
@@ -689,6 +654,35 @@ async function startDaemon({
     throw err;
   }
 
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(socketPath, () => {
+        server.removeListener('error', reject);
+        resolve();
+      });
+    });
+  } catch (err) {
+    // listen failed (e.g. EADDRINUSE from a double-spawn that beat us to the
+    // bind, or a recycled-pid wedge). Nothing is listening, so only the engine
+    // and the lock are undone.
+    await abortStart({ event: 'daemon.listen_failure', err, listening: false });
+  }
+
+  // The engine died between connect and listen. Fail the start exactly like a
+  // listen failure — before the handle exists, so nothing reading it is told a
+  // dead session is ready. The bin's main().catch exits 1; the spawner sees a
+  // start that never became ready.
+  if (!engineAlive) {
+    const err = new Error('mobile-mcp exited before the device session daemon was ready');
+    err.code = 'ENGINE_EXITED';
+    await abortStart({ event: 'daemon.connect_failure', err, listening: true });
+  }
+
+  // Serving from here on: an engine exit reaps the daemon (see onEngineExit).
+  // Set synchronously after the check above, so no exit can fall between them.
+  serving = true;
+
   // Persist handle + pidfile now that we are actually listening.
   const handle = {
     pid: process.pid,
@@ -741,4 +735,9 @@ async function startDaemon({
   };
 }
 
-module.exports = { startDaemon, cleanStale, pidAlive, pidIdentity, DAEMON_CALL_TIMEOUT_MS, DEFAULT_IDLE_MS };
+module.exports = {
+  startDaemon,
+  cleanStale,
+  DAEMON_CALL_TIMEOUT_MS,
+  DEFAULT_IDLE_MS,
+};

package/src/device/session-paths.js

@@ -74,6 +74,26 @@ function lockPath(projectRoot) {
   return path.join(sessionDir(projectRoot), LOCK_NAME);
 }
 
+// The workspace a daemon serves, as it appears on its command line (#156).
+// The daemon itself reads its root from env (MAUTO_SESSION_PROJECT_ROOT), which
+// `ps` cannot see, so every daemon's command line used to be identical. This
+// marker is what lets `session end` tell THIS workspace's daemon from another
+// workspace's before it signals a process group: a copied workspace (`cp -R`
+// carries daemon.pid) or a recycled pid can name a different live daemon.
+// The root is the LAST argument so a match can be anchored at the end.
+const DAEMON_ROOT_FLAG = '--project-root';
+
+function daemonArgv(projectRoot) {
+  return [DAEMON_ROOT_FLAG, path.resolve(projectRoot)];
+}
+
+// Does a `ps -o command=` line name exactly this workspace? Anchored at the end
+// of the line so `/a/proj` never matches a daemon serving `/a/proj2`.
+function commandNamesWorkspace(command, projectRoot) {
+  const line = String(command || '').replace(/\s+$/, '');
+  return line.endsWith(` ${DAEMON_ROOT_FLAG} ${path.resolve(projectRoot)}`);
+}
+
 module.exports = {
   SESSION_DIRNAME,
   SOCKET_NAME,
@@ -89,4 +109,7 @@ module.exports = {
   pidFilePath,
   handlePath,
   lockPath,
+  DAEMON_ROOT_FLAG,
+  daemonArgv,
+  commandNamesWorkspace,
 };

package/src/device/session-spawn.js

@@ -12,6 +12,8 @@ const childProcess = require('child_process');
 
 const sessionClient = require('./session-client');
 const sessionLog = require('./session-log');
+const paths = require('./session-paths');
+const reaper = require('./process-reaper');
 
 const DAEMON_BIN = path.join(__dirname, '..', '..', 'bin', 'mauto-session-daemon.js');
 const DEFAULT_READY_TIMEOUT_MS = 15000;
@@ -31,6 +33,10 @@ async function spawnDaemon({
   pollMs = DEFAULT_POLL_MS,
   isAlive = sessionClient.isAlive,
   openLog = sessionLog.openDaemonLog,
+  // Kills a daemon that never became ready (#156). group:true reaches the
+  // daemon AND its mobile-mcp engine: `detached: true` below makes the daemon
+  // a process-group leader, and the engine is spawned into its group.
+  terminate = (pid) => reaper.terminate(pid, { group: true }),
 } = {}) {
   if (!projectRoot) throw new TypeError('spawnDaemon requires projectRoot');
 
@@ -46,7 +52,9 @@ async function spawnDaemon({
   const log = openLog(projectRoot);
 
   try {
-    const child = spawn(process.execPath, [DAEMON_BIN], {
+    // The root in argv is an identity marker only (see paths.daemonArgv): env
+    // stays the daemon's source of truth, but `ps` can only see argv.
+    const child = spawn(process.execPath, [DAEMON_BIN, ...paths.daemonArgv(projectRoot)], {
       detached: true,
       stdio: log.stdio,
       env,
@@ -80,6 +88,18 @@ async function spawnDaemon({
       if (await isAlive(projectRoot)) return true;
       await sleep(pollMs);
     }
+
+    // Not ready in time. Without this the child lives on — typically still
+    // inside createCall, holding the O_EXCL lock — and every later verb burns
+    // its own readiness window against it (#156). Only OUR child, and only if
+    // it is still running: an ELOCKED spawn-race loser has already exited and
+    // must never signal anything. Node tracked this exact child, so its state
+    // needs no pidIdentity check and has no pid-reuse window.
+    if (child && child.pid && child.exitCode === null && child.signalCode === null) {
+      const outcome = await terminate(child.pid);
+      // The parent is the only witness to this kill — write it down (#163).
+      log.write(`mauto: daemon not ready after ${readyTimeoutMs}ms; terminated pid=${child.pid} (${outcome})\n`);
+    }
     return false;
   } finally {
     // The child holds its own dup, so the parent releases its descriptor rather
@@ -89,4 +109,4 @@ async function spawnDaemon({
   }
 }
 
-module.exports = { spawnDaemon, DAEMON_BIN };
+module.exports = { spawnDaemon, DAEMON_BIN, DEFAULT_READY_TIMEOUT_MS };

package/src/guide/content/generate.agnostic.md

@@ -112,7 +112,7 @@ Translate user language to action types and `mauto` verbs:
 | **"allow permission", "grant the permission"** | **`grant_permission`** | **`mauto press grant_permission`** | **Semantic — set optional `permission_name` if specific.** |
 | **"deny permission", "don't allow"** | **`deny_permission`** | **`mauto press deny_permission`** | **Semantic.** |
 | "navigate to [tab]" | `tap` | `mauto elements` to find the tab, then `mauto tap --at <x,y>` | |
-| "open URL", "navigate to URL" | `open_url` | `mauto press` / open the URL | |
+| "open URL", "open deep link", "navigate to URL" | `open_url` | `mauto open-url <url>` | |
 | "wait until visible" | `wait_for_element` | Poll `mauto elements` until present | Set `wait_config.type: "element_visible"` |
 | "wait until gone" | `wait_for_element_gone` | Poll `mauto elements` until absent | |
 | "wait until loaded", "wait for shimmer to stop" | `wait_for_loading_complete` | Poll `mauto screenshot <path>` + visual check | Set `wait_config.indicator` to match project's loading style |

package/src/guide/content/generate.aware.md

@@ -241,7 +241,7 @@ Translate user language to `mauto` verbs and schema actions:
 | "scroll to", "scroll until visible", "scroll down to find" | `scroll_to_element` | `mauto swipe --direction <dir>` (repeated) | Target is the element to scroll to |
 | "go back", "press back" | `press_button` | `mauto press <button>` | Use the back button |
 | "navigate to [tab]" | `tap` | `mauto elements` to find the tab, then `mauto tap --at <x,y>` | |
-| "open URL", "navigate to URL" | `open_url` | `mauto press` / open the URL | |
+| "open URL", "open deep link", "navigate to URL" | `open_url` | `mauto open-url <url>` | |
 | "wait until visible", "wait for [element] to appear" | `wait_for_element` | Poll `mauto elements` until present | Set `wait_config.type: "element_visible"` |
 | "wait until gone", "wait for [element] to disappear" | `wait_for_element_gone` | Poll `mauto elements` until absent | Set `wait_config.type: "element_gone"` |
 | "wait until loaded", "wait for shimmer to stop", "wait for loading to complete" | `wait_for_loading_complete` | Poll `mauto screenshot <path>` + visual check | Set `wait_config.indicator` to match project's loading style (shimmer/spinner/skeleton) |

package/src/observe/event.js

@@ -120,10 +120,10 @@ const EVENT_FIELDS = {
   // src/device/mobile-mcp-tools.js. A daemon-minted counter needs no redaction
   // argument at all, on exactly the grounds dur_ms is cleared.
   call_id: sendable(integer({ min: 1 }), 'daemon-minted counter scoped to one session; never the client-supplied frame id'),
-  stop_reason: sendable(oneOf(STOP_REASONS), 'enumerated: idle|signal|shutdown|crash|explicit'),
+  stop_reason: sendable(oneOf(STOP_REASONS), 'enumerated: idle|signal|shutdown|crash|explicit|engine_exit'),
   // Errno NAMES only: the numeric codes an MCP server reports, and Node's
   // ERR_* codes, fail the check and are dropped rather than sent.
-  error_code: sendable(oneOf(ERROR_CODES), 'Node/libuv errno string (EADDRINUSE|EACCES|…) plus our own ELOCKED'),
+  error_code: sendable(oneOf(ERROR_CODES), 'Node/libuv errno string (EADDRINUSE|EACCES|…) plus our own ELOCKED|ENGINE_CONNECT_TIMEOUT|ENGINE_EXITED'),
 
   // --- crash (slice 4) ---------------------------------------------------
   // The ONLY new field slice 4 mints. As with `verb`, `tool` and `session_id`,

package/src/observe/vocab.js

@@ -43,6 +43,7 @@ const EVENT_NAMES = Object.freeze([
   'daemon.start_failure',
   'daemon.listen_failure',
   'daemon.connect_failure',
+  'daemon.engine_exit',
   'daemon.lock_conflict',
   'daemon.undeliverable',
   // Emitted by the flush path, which lands in a later slice-5 task; declared
@@ -86,11 +87,20 @@ const VERB_NAMES = Object.freeze([
 ]);
 
 // Why the daemon stopped. 'crash' is documented but not yet produced.
-const STOP_REASONS = Object.freeze(['idle', 'signal', 'shutdown', 'crash', 'explicit']);
+// 'engine_exit': the mobile-mcp engine died under a serving daemon (#156).
+const STOP_REASONS = Object.freeze(['idle', 'signal', 'shutdown', 'crash', 'explicit', 'engine_exit']);
 
-// Node/libuv errno names for this platform, plus our own ELOCKED (a lock
-// conflict, recorded by src/device/session-daemon.js). Names only: the numeric codes an MCP
-// server reports are not in this set and so never pass.
-const ERROR_CODES = Object.freeze([...Object.keys(os.constants.errno), 'ELOCKED']);
+// Node/libuv errno names for this platform, plus our own codes, all recorded by
+// src/device/: ELOCKED (a lock conflict, session-daemon.js),
+// ENGINE_CONNECT_TIMEOUT (initialize exceeded its bound, mobile-mcp-client.js)
+// and ENGINE_EXITED (the engine died before the daemon was serving,
+// session-daemon.js). Names only: the numeric codes an MCP server reports are
+// not in this set and so never pass.
+const ERROR_CODES = Object.freeze([
+  ...Object.keys(os.constants.errno),
+  'ELOCKED',
+  'ENGINE_CONNECT_TIMEOUT',
+  'ENGINE_EXITED',
+]);
 
 module.exports = { OS_NAMES, EVENT_NAMES, VERB_NAMES, STOP_REASONS, ERROR_CODES };