mobile-automator 0.23.9 → 0.24.0

package/bin/mauto-session-daemon.js

@@ -46,6 +46,15 @@ function cleanupWorkspaceIfOwned(projectRoot) {
 }
 
 async function main() {
+  // First write of the process, so every later line in the shared append-only
+  // log is attributable to a spawn. Written HERE rather than by the spawning
+  // parent because only this process knows its own pid, and because a parent
+  // banner races the child's own first output (#163). Under the degraded
+  // `stdio: 'ignore'` handle this lands in /dev/null, which is correct.
+  process.stderr.write(
+    `\n=== mauto daemon ${new Date().toISOString()} pid=${process.pid} ===\n`
+  );
+
   const projectRoot = process.env.MAUTO_SESSION_PROJECT_ROOT;
   if (!projectRoot) {
     process.stderr.write('mauto-session-daemon: MAUTO_SESSION_PROJECT_ROOT is required\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-automator",
-  "version": "0.23.9",
+  "version": "0.24.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": {

package/src/cli.js

@@ -995,8 +995,13 @@ async function handleSessionStart(
 
   const started = await connection.startSession({ projectRoot, device, idleMs, spawn });
   if (!started) {
+    // The daemon's stdout/stderr are captured to the workspace log, so the
+    // "why" of a startup crash exists on disk — but only this hint tells the
+    // user (or agent) that it does. Same sentence the transparent-autostart
+    // fallback uses, so the log is named identically wherever it surfaces.
+    const logHint = connection.daemonLogHint(projectRoot);
     return {
-      envelope: fail('device', 'failed to start the device session daemon', 'Ensure a device or simulator is connected, or run verbs directly (they fall back to one-shot).'),
+      envelope: fail('device', 'failed to start the device session daemon', `Ensure a device or simulator is connected, or run verbs directly (they fall back to one-shot). ${logHint}`),
       exitKind: 'device',
     };
   }

package/src/device/connection.js

@@ -14,6 +14,8 @@
 // handlers.
 
 const { resolveDeviceConnection } = require('./resolve-connection');
+const { daemonLogHint } = require('./session-log');
+const paths = require('./session-paths');
 const sessionClient = require('./session-client');
 const sessionSpawn = require('./session-spawn');
 
@@ -40,10 +42,20 @@ function isSessionAlive(projectRoot, { client = sessionClient } = {}) {
   return client.isAlive(projectRoot);
 }
 
-// Rich status: running + in-flight call count + pinned device. `null`s when not
-// running. The in-flight count exposes the double-execution window.
-function sessionStatus(projectRoot, { client = sessionClient } = {}) {
-  return client.getSessionStatus(projectRoot);
+// Rich status: running + in-flight call count + pinned device (`null`s when not
+// running), plus log_path, which is reported unconditionally. The in-flight
+// count exposes the double-execution window.
+//
+// log_path is computed HERE from the project root rather than read out of the
+// daemon's ping reply, and that is deliberate: getSessionStatus() collapses
+// every failure branch — no socket, non-ok ping, or a throw — into the same
+// not-running shape, so a daemon-supplied path would go missing in exactly the
+// case where a user is reaching for `session status` to find out why the daemon
+// is dead. The path is a pure function of the workspace, so we can always
+// answer it. Do not "simplify" this into the ping payload.
+async function sessionStatus(projectRoot, { client = sessionClient } = {}) {
+  const status = await client.getSessionStatus(projectRoot);
+  return { ...status, log_path: paths.logFilePath(projectRoot) };
 }
 
 // Spawn a daemon and wait until it answers. Resolves true on success.
@@ -58,6 +70,10 @@ function endSession(projectRoot, { client = sessionClient } = {}) {
 
 module.exports = {
   acquireConnection,
+  // Re-exported from session-log so cli.js can name the daemon log through the
+  // one device facade it already imports, instead of reaching into a
+  // connection-strategy module for a string.
+  daemonLogHint,
   isSessionAlive,
   sessionStatus,
   startSession,

package/src/device/resolve-connection.js

@@ -14,7 +14,9 @@
 //   (c) autostart && no reachable daemon
 //         -> spawn a daemon, then connect daemon-backed (no-op close).
 //   (d) spawn failed, or autostart:false
-//         -> one-shot fallback via the real createCall (real close).
+//         -> one-shot fallback via the real createCall (real close). When the
+//            spawn is what failed, a thrown one-shot error is decorated with a
+//            hint naming the daemon log so the crash stays findable (#163).
 //
 // Everything device-touching is injected so the whole matrix is unit-testable
 // with a fake daemon + fake createCall + fake spawn.
@@ -24,6 +26,7 @@ const fs = require('fs');
 const { DeviceBridge } = require('./bridge');
 const paths = require('./session-paths');
 const sessionClient = require('./session-client');
+const { daemonLogHint } = require('./session-log');
 const sessionSpawn = require('./session-spawn');
 
 function defaultCreateCall(opts) {
@@ -135,17 +138,34 @@ async function resolveDeviceConnection({
     requestedDevice: device,
     autostart,
   });
+  let spawnFailed = false;
   if (strategy === 'spawn-then-daemon') {
     // (c) spawn a daemon, then connect daemon-backed.
     const started = await spawn.spawnDaemon({ projectRoot, device, idleMs });
     if (started) {
       const conn = await daemonBacked();
       if (conn) return conn;
+      // Spawn worked; the daemon just wasn't reachable. Its log has nothing to
+      // say about a subsequent one-shot failure, so no hint — fall through.
+    } else {
+      spawnFailed = true;
     }
   }
 
-  // (d) explicit one-shot, or spawn failed / unreachable.
-  return oneShot();
+  // (d) explicit one-shot, or spawn failed / unreachable. When the SPAWN is
+  // what failed, the daemon's log is the only record of why, and transparent
+  // autostart is the common path — most users never type `mauto session start`,
+  // so without this the log stays invisible to almost everyone. The signal
+  // rides err.hint because deviceFail() in cli.js already surfaces it on every
+  // device verb, so acquireConnection's deliberately narrow contract is
+  // untouched (#163).
+  try {
+    return await oneShot();
+  } catch (err) {
+    // Never clobber a more specific hint the transport already attached.
+    if (spawnFailed && !err.hint) err.hint = daemonLogHint(projectRoot);
+    throw err;
+  }
 }
 
 module.exports = {

package/src/device/session-daemon.js

@@ -225,7 +225,11 @@ async function startDaemon({
               `mauto-session-daemon: undeliverable reply id=${info.id}: ${info.reason}\n`
             );
           } catch (_) {
-            /* stderr gone */
+            // fd 2 is unwritable (full disk, or the workspace log could not be
+            // opened and this is /dev/null's successor). Since #163 it normally
+            // reaches mobile-automator/.session/daemon.log; either way an
+            // undeliverable reply is already recorded in `undeliverable`, so
+            // losing the warning must not take the daemon down.
           }
         };
 

package/src/device/session-log.js

@@ -0,0 +1,95 @@
+'use strict';
+
+// Lifecycle of the daemon's log file, so session-spawn.js can stay
+// filesystem-free and just hand the stdio triple to child_process.spawn.
+//
+// Failure policy is PER-STEP, not whole-module. Rotation is a disk guard;
+// the diagnostics are the point. A rotation that cannot run — a race with a
+// concurrent spawn, a permissions problem — must not cost us the log. Only an
+// unopenable log degrades, and it degrades to today's `stdio: 'ignore'`:
+// a read-only or full workspace loses diagnostics, never the CLI.
+
+const realFs = require('fs');
+
+const { sessionDir, logFilePath } = require('./session-paths');
+
+const MAX_LOG_BYTES = 1024 * 1024;
+
+// The degraded handle, expressed as a VALUE so callers never branch on null.
+// `stdio: 'ignore'` is the behaviour that predates #163.
+const IGNORED = Object.freeze({ stdio: 'ignore', write() {}, close() {} });
+
+// The one sentence pointing a user at the daemon's captured output (#163).
+// It lives here because it is a fact about the log, and it is re-exported
+// through connection.js so cli.js reaches it via the device facade it already
+// imports rather than reaching into a connection-strategy module.
+function daemonLogHint(projectRoot) {
+  return `The daemon's output (including stack traces) was captured to ${logFilePath(projectRoot)}.`;
+}
+
+// Best-effort rotation to a single previous generation; clobbering an existing
+// .1 is the intended bound. Every failure here is survivable — no log yet
+// (ENOENT on stat), a concurrent spawn that already rotated (ENOENT on rename),
+// an unreadable directory (EACCES) — so we swallow and carry on to the open.
+// An oversized log beats no log.
+function rotateIfLarge(logPath, maxBytes, fs) {
+  try {
+    if (fs.statSync(logPath).size >= maxBytes) fs.renameSync(logPath, `${logPath}.1`);
+  } catch (_) {
+    /* nothing to rotate, or someone beat us to it */
+  }
+}
+
+// Returns { stdio, write, close } — NEVER null.
+//
+//   stdio  the triple for child_process.spawn. stdout AND stderr point at the
+//          same fd on purpose: the child gets dups sharing one O_APPEND file
+//          description, so the two streams interleave without clobbering. That
+//          one descriptor also captures mobile-mcp, whose MCP stdio transport
+//          defaults its stderr to 'inherit' and therefore writes to whatever
+//          fd 2 the daemon has. Point fd 2 at /dev/null and its crashes vanish.
+//   write  for diagnostics only the PARENT can see. A spawn that fails to exec
+//          leaves the child with nothing to say, so this is the sole record of
+//          EMFILE/EACCES/ENOENT-on-the-bin (#163).
+//   close  releases the parent's dup; the child holds its own.
+function openDaemonLog(projectRoot, { maxBytes = MAX_LOG_BYTES, fs = realFs } = {}) {
+  let fd;
+  try {
+    // The parent must create .session/: only startDaemon creates it today, and
+    // that runs in the child — too late for an fd the parent has to open first.
+    fs.mkdirSync(sessionDir(projectRoot), { recursive: true });
+
+    const logPath = logFilePath(projectRoot);
+    rotateIfLarge(logPath, maxBytes, fs);
+
+    // Append, never 'w'. Lock-race losers exit ELOCKED through
+    // bin/mauto-session-daemon.js and write to this same file; truncating on
+    // open would let a loser erase the winner's just-written crash trace.
+    fd = fs.openSync(logPath, 'a');
+  } catch (_) {
+    return IGNORED;
+  }
+
+  const write = (text) => {
+    try {
+      fs.writeSync(fd, text);
+    } catch (_) {
+      // Full disk, closed fd — the diagnostics are optional, the spawn is not.
+    }
+  };
+
+  let closed = false;
+  const close = () => {
+    if (closed) return;
+    closed = true;
+    try {
+      fs.closeSync(fd);
+    } catch (_) {
+      // Already reaped by the runtime; nothing left to do.
+    }
+  };
+
+  return { stdio: ['ignore', fd, fd], write, close };
+}
+
+module.exports = { MAX_LOG_BYTES, IGNORED, daemonLogHint, openDaemonLog };

package/src/device/session-paths.js

@@ -6,6 +6,7 @@
 //   mauto.sock    — Unix domain socket the daemon listens on
 //   daemon.pid    — pidfile written once the daemon is listening
 //   session.json  — handle describing the live session (device pin, socket, pid)
+//   daemon.log    — bounded stdout/stderr capture from the detached daemon
 //
 // These are intentionally side-effect-free so they can be unit-tested without
 // touching the filesystem.
@@ -19,6 +20,7 @@ const SOCKET_NAME = 'mauto.sock';
 const PID_NAME = 'daemon.pid';
 const HANDLE_NAME = 'session.json';
 const LOCK_NAME = 'daemon.lock';
+const LOG_NAME = 'daemon.log';
 
 // Unix domain socket paths have a hard length limit (~104 bytes on macOS,
 // ~108 on Linux). Deep project roots blow past it, so when the in-workspace
@@ -50,6 +52,14 @@ function socketPath(projectRoot) {
   return path.join(os.tmpdir(), `mauto-${hash}.sock`);
 }
 
+// Deliberately has no os.tmpdir() fallback, unlike socketPath(). That fallback
+// exists solely because Unix domain socket paths hit a ~104-byte sockaddr
+// limit; a regular file has no such limit, so the log stays in the workspace
+// unconditionally and is always findable next to the session it describes.
+function logFilePath(projectRoot) {
+  return path.join(sessionDir(projectRoot), LOG_NAME);
+}
+
 function pidFilePath(projectRoot) {
   return path.join(sessionDir(projectRoot), PID_NAME);
 }
@@ -70,10 +80,12 @@ module.exports = {
   PID_NAME,
   HANDLE_NAME,
   LOCK_NAME,
+  LOG_NAME,
   SOCKET_PATH_LIMIT,
   sessionDir,
   workspaceSocketPath,
   socketPath,
+  logFilePath,
   pidFilePath,
   handlePath,
   lockPath,

package/src/device/session-spawn.js

@@ -1,13 +1,17 @@
 'use strict';
 
 // Spawns the device session daemon as a DETACHED background process and waits
-// until it is reachable. The spawn fn is injectable so the spawn args and the
-// readiness-poll contract are unit-testable without launching a real daemon.
+// until it is reachable. The daemon's output is captured to the workspace log
+// (mobile-automator/.session/daemon.log) instead of /dev/null, so a crashing
+// engine leaves a readable trace behind. The spawn and openLog fns are
+// injectable so the spawn args, the log wiring and the readiness-poll contract
+// are all unit-testable without launching a real daemon or touching disk.
 
 const path = require('path');
 const childProcess = require('child_process');
 
 const sessionClient = require('./session-client');
+const sessionLog = require('./session-log');
 
 const DAEMON_BIN = path.join(__dirname, '..', '..', 'bin', 'mauto-session-daemon.js');
 const DEFAULT_READY_TIMEOUT_MS = 15000;
@@ -26,6 +30,7 @@ async function spawnDaemon({
   readyTimeoutMs = DEFAULT_READY_TIMEOUT_MS,
   pollMs = DEFAULT_POLL_MS,
   isAlive = sessionClient.isAlive,
+  openLog = sessionLog.openDaemonLog,
 } = {}) {
   if (!projectRoot) throw new TypeError('spawnDaemon requires projectRoot');
 
@@ -33,35 +38,55 @@ async function spawnDaemon({
   if (device) env.MAUTO_SESSION_DEVICE = device;
   if (idleMs !== undefined && idleMs !== null) env.MAUTO_SESSION_IDLE_MS = String(idleMs);
 
-  const child = spawn(process.execPath, [DAEMON_BIN], {
-    detached: true,
-    stdio: 'ignore',
-    env,
-  });
+  // Must precede the spawn: the fd has to exist before the child can inherit it.
+  // Never null — a workspace we cannot write to yields the `stdio: 'ignore'`
+  // handle, so there is nothing to branch on here. The daemon writes its own
+  // spawn banner (bin/mauto-session-daemon.js), which is why this file no
+  // longer needs the child's pid.
+  const log = openLog(projectRoot);
 
-  // A spawn that fails synchronously (EMFILE, EACCES, ENOENT on the bin) emits
-  // an 'error' event instead of throwing. Without a listener that error would
-  // crash the one-shot verb process; with it we bail out of the readiness poll
-  // immediately instead of waiting out the full 15s window for a child that can
-  // never come up. No 'exit' short-circuit here: a loser exiting ELOCKED is
-  // expected, and the winner may still come up within the poll window.
-  let spawnError = null;
-  if (child && typeof child.on === 'function') {
-    child.on('error', (err) => {
-      spawnError = err;
+  try {
+    const child = spawn(process.execPath, [DAEMON_BIN], {
+      detached: true,
+      stdio: log.stdio,
+      env,
     });
-  }
 
-  // Let the daemon outlive this one-shot verb process.
-  if (child && typeof child.unref === 'function') child.unref();
+    // A spawn that fails to exec (EMFILE, EACCES, ENOENT on the bin) emits an
+    // 'error' event instead of throwing. Without a listener that error would
+    // crash the one-shot verb process; with it we bail out of the readiness
+    // poll immediately instead of waiting out the full 15s window for a child
+    // that can never come up. No 'exit' short-circuit here: a loser exiting
+    // ELOCKED is expected, and the winner may still come up within the window.
+    //
+    // The error is also WRITTEN to the log, not just used as a flag: a child
+    // that never execs has no stdout/stderr of its own, so the parent is the
+    // only witness. Dropping it here would rebuild the exact hole #163 fixes,
+    // one layer up.
+    let spawnError = null;
+    if (child && typeof child.on === 'function') {
+      child.on('error', (err) => {
+        spawnError = err;
+        log.write(`mauto: daemon spawn failed: ${err && err.stack ? err.stack : err}\n`);
+      });
+    }
+
+    // Let the daemon outlive this one-shot verb process.
+    if (child && typeof child.unref === 'function') child.unref();
 
-  const deadline = Date.now() + readyTimeoutMs;
-  while (Date.now() < deadline) {
-    if (spawnError) return false;
-    if (await isAlive(projectRoot)) return true;
-    await sleep(pollMs);
+    const deadline = Date.now() + readyTimeoutMs;
+    while (Date.now() < deadline) {
+      if (spawnError) return false;
+      if (await isAlive(projectRoot)) return true;
+      await sleep(pollMs);
+    }
+    return false;
+  } finally {
+    // The child holds its own dup, so the parent releases its descriptor rather
+    // than leaking one per verb invocation. In `finally` because the 'error'
+    // listener above fires asynchronously — the handle has to outlive the poll.
+    log.close();
   }
-  return false;
 }
 
 module.exports = { spawnDaemon, DAEMON_BIN };