mobile-automator 0.26.0 → 0.28.0

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,69 @@ function resolveServerEntry() {
   return path.join(pkgDir, binRel);
 }
 
+// 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],
+//
+// `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,
     // 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,
   });
 
-  const client = new Client(
-    { name: 'mauto', version: '0.1.0' },
-    { capabilities: {} }
-  );
+  const client = new sdk.Client({ name: 'mauto', version: '0.1.0' }, { capabilities: {} });
 
-  await client.connect(transport);
+  // 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();
+  };
+
+  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 +117,7 @@ async function createCall({ device } = {}) {
   const { call } = makeCall({ rawCall, device });
 
   async function close() {
+    closing = true;
     try {
       await client.close();
     } catch (_e) {
@@ -63,6 +128,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
@@ -160,4 +246,13 @@ function parseToolResult(res) {
   return res;
 }
 
-module.exports = { createCall, makeCall, parseToolResult };
+// 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,
+  CONNECT_TIMEOUT_MS,
+  ENGINE_REAP_MAX_MS,
+};

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,
+};