mobile-automator 0.25.0 → 0.26.0

package/src/device/mobile-mcp-tools.js

@@ -0,0 +1,64 @@
+'use strict';
+
+// The mobile-mcp primitives mauto actually calls, as a closed set.
+//
+// It exists so `tool` can be sends:true in the event catalog. That field's
+// justification — an enumerated primitive name — is only true if the recorded
+// value is enforced to be one, exactly as `verb` is enforced against
+// commander's resolved command rather than argv (see src/observe/event.js).
+// The daemon's `tool` arrives inside a socket frame and the daemon's socket is
+// reachable by anything on the machine, so an unchecked value is caller-
+// supplied text.
+//
+// tests/lint/mobile-mcp-tool-coverage.test.js pins this set to the primitives
+// src/device/bridge.js calls, in BOTH directions, so neither a new bridge call
+// nor a stale entry can drift. The guard being bidirectional is why the crash
+// primitives and DeviceBridge#listCrashes/#getCrash landed in one commit: either
+// half alone fails one of its two assertions.
+
+// The vocabulary, as a frozen ARRAY, exported only so the lint guard can
+// enumerate it in both directions.
+//
+// Deliberately not a frozen Set. Object.freeze on a Set is decorative: a Set's
+// entries live in its [[SetData]] internal slot, which `.add` / `.delete` /
+// `.clear` mutate without ever consulting the object's extensibility, so
+// freezing reaches only the Set's own properties. The result reports
+// Object.isFrozen === true over a wide-open allowlist, which is worse than an
+// unfrozen set — a reader who checks is actively misled. On an array the
+// entries ARE ordinary indexed properties, so the freeze is real: push throws
+// (it must define a property on a non-extensible object) and no element
+// assignment can land.
+const MOBILE_MCP_TOOL_NAMES = Object.freeze([
+  'mobile_list_available_devices',
+  'mobile_list_elements_on_screen',
+  'mobile_save_screenshot',
+  'mobile_click_on_screen_at_coordinates',
+  'mobile_long_press_on_screen_at_coordinates',
+  'mobile_double_tap_on_screen',
+  'mobile_type_keys',
+  'mobile_swipe_on_screen',
+  'mobile_get_screen_size',
+  'mobile_press_button',
+  'mobile_launch_app',
+  'mobile_install_app',
+  'mobile_uninstall_app',
+  'mobile_open_url',
+  'mobile_set_orientation',
+  // Diagnostic, not a scenario action — see DeviceBridge#listCrashes.
+  'mobile_list_crashes',
+  'mobile_get_crash',
+]);
+
+// The structure isKnownTool actually queries is module-PRIVATE, and that — not
+// the freeze above — is what closes the set. Freezing protects the enumeration;
+// withholding the reference protects the decision. No consumer can hold the
+// thing `.has()` is called on, so there is nothing to call `.add()` on.
+// tests/lint/mobile-mcp-tool-coverage.test.js attempts the widening and the
+// narrowing through every export and then asks isKnownTool for the verdict.
+const TOOL_SET = new Set(MOBILE_MCP_TOOL_NAMES);
+
+function isKnownTool(name) {
+  return typeof name === 'string' && TOOL_SET.has(name);
+}
+
+module.exports = { MOBILE_MCP_TOOL_NAMES, isKnownTool };

package/src/device/resolve-connection.js

@@ -21,10 +21,8 @@
 // Everything device-touching is injected so the whole matrix is unit-testable
 // with a fake daemon + fake createCall + fake spawn.
 
-const fs = require('fs');
-
 const { DeviceBridge } = require('./bridge');
-const paths = require('./session-paths');
+const { readHandle } = require('./session-handle');
 const sessionClient = require('./session-client');
 const { daemonLogHint } = require('./session-log');
 const sessionSpawn = require('./session-spawn');
@@ -38,14 +36,14 @@ const NOOP_CLOSE = () => Promise.resolve();
 // Read the live daemon's pinned device from its handle, or null. A null pin
 // means the daemon serves whatever device mobile-mcp selected (matches any
 // request that doesn't pin a specific device).
+//
+// Reading and parsing the handle belongs to session-handle.js, which owns that
+// file and is already total (absent/unreadable/malformed all mean "no
+// session"). This is the projection onto the one field this module cares about,
+// not a second reader of the same JSON.
 function readHandleDevice(projectRoot) {
-  try {
-    const raw = fs.readFileSync(paths.handlePath(projectRoot), 'utf8');
-    const handle = JSON.parse(raw);
-    return handle && handle.device ? handle.device : null;
-  } catch (_) {
-    return null;
-  }
+  const handle = readHandle(projectRoot);
+  return (handle && handle.device) || null;
 }
 
 // Does a daemon pinned to `handleDevice` satisfy a request for `requested`?

package/src/device/session-daemon.js

@@ -24,6 +24,10 @@ const net = require('net');
 
 const paths = require('./session-paths');
 const { FrameParser } = require('./session-protocol');
+const { newSessionId } = require('./session-handle');
+const { makeDeviceCall } = require('./device-call');
+const { safeObserve: guardObserve } = require('../observe/recorder');
+const { FLUSH_INTERVAL_MS } = require('../observe/flush');
 
 const DEFAULT_IDLE_MS = 5 * 60 * 1000;
 
@@ -158,11 +162,93 @@ async function startDaemon({
   onUndeliverable = null,
   scheduleTimeout = defaultScheduleTimeout,
   execFile = childProcess.execFileSync,
+  // 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.
+  //
+  // Defaulted to an inert one for the same reason the old `observe` parameter
+  // was: startDaemon also runs IN-PROCESS across ~40 unit tests, where a live
+  // stderr sink would write into jest's reporter output. The only process that
+  // is actually a daemon — bin/mauto-session-daemon.js — injects boundRecorder,
+  // and tests/unit/bin/mauto-session-daemon-observe.test.js proves it does. The
+  // factory must be construction-total (boundRecorder is: recorder.js degrades
+  // to an inert observe rather than throwing), because a recorder that cannot
+  // be built must not be the reason a device session fails to start.
+  recorderFor = () => () => {},
+  // The spool flusher, as a FACTORY — exactly recorderFor's shape, and for
+  // the same reason: it needs THIS daemon's own safeObserve (bound to the
+  // sessionId minted below), which doesn't exist until this function is
+  // already running. Defaulted to null: startDaemon runs IN-PROCESS across
+  // ~40 unit tests, and a default that built a real flusher would put
+  // network I/O in the unit suite. bin/mauto-session-daemon.js — the only
+  // process that is actually a daemon — injects makeFlusher.
+  flushFor = null,
+  flushIntervalMs = FLUSH_INTERVAL_MS,
 } = {}) {
   if (!projectRoot) throw new TypeError('startDaemon requires projectRoot');
 
+  // This daemon's identity, minted HERE and nowhere else.
+  //
+  // startDaemon is the SOLE owner of session_id: it mints it, binds it onto
+  // every event it records, and writes it into the handle below — so the handle
+  // and the event stream cannot name different sessions, because there is no
+  // second parameter for them to disagree through. Callers read it back off the
+  // return value.
+  //
+  // It used to arrive as `sessionId = newSessionId()`, an optional parameter
+  // sitting alongside an already-bound `observe`, with nothing forcing the two
+  // to agree: a caller that wired observability but not an id got a handle
+  // advertising one session and a stream stamped with none, silently. That is
+  // exactly the class of failure device-call.js refuses to allow for its own
+  // four inputs ("every one of these has a failure mode that is silent if it is
+  // wrong"), and it is why the id cannot be a parameter at all — requiring one
+  // would still leave two ways in. Pinned by the last test in
+  // tests/unit/device/daemon-observability.test.js, which reads the handle and
+  // the log file and demands one value.
+  const sessionId = newSessionId();
+
+  // Which is why the seam is a factory: the identity a recorder must be bound
+  // to does not exist until the line above. The caller owns WHERE events go;
+  // the daemon owns WHOSE they are. `pid` is bound here too, being the same
+  // kind of fact, so no daemon call site can hand-stamp either one.
+  const observe = recorderFor({ src: 'daemon', session_id: sessionId, pid: process.pid });
+
+  // The injected seam, guarded once at the boundary with the canonical wrapper
+  // (src/observe/recorder.js) rather than a fourth hand-rolled try/catch. Two
+  // failure modes this closes, both proved by
+  // tests/unit/device/daemon-observability.test.js: the daemon dying at startup
+  // killed by the code whose only job is to explain why daemons die, and — on
+  // the failure paths, which observe BEFORE releaseLock() — a telemetry fault
+  // masking the real error and leaking the lock, wedging every later spawn.
+  const safeObserve = guardObserve(observe);
+
+  // Built here, unwrapped, on the same trust as recorderFor above: the
+  // factory must be construction-total (makeFlusher just destructures
+  // options and returns a closure — it cannot throw), so this is not a
+  // second hand-rolled guard, it is the same contract applied twice.
+  const flush = typeof flushFor === 'function' ? flushFor({ observe: safeObserve }) : null;
+
+  // Zero point for every dur_ms this daemon reports: startup duration on
+  // daemon.start, total session lifetime on daemon.stop.
+  const startedAtMs = Date.now();
+
+  // Guarded like the lock failure below, and for the same reason: this is the
+  // FIRST filesystem operation the daemon performs, and it fails on exactly the
+  // conditions daemon.start_failure exists to report (EACCES, EROFS, ENOSPC on
+  // the workspace). An unguarded throw here is the earliest invisible death
+  // there is — nothing else in the system records it, and the spawning verb
+  // sees only a readiness timeout.
   const dir = paths.sessionDir(projectRoot);
-  fs.mkdirSync(dir, { recursive: true });
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch (err) {
+    safeObserve({
+      level: 'error',
+      event: 'daemon.start_failure',
+      error_code: err && err.code,
+      message: err && (err.message || String(err)),
+    });
+    throw err;
+  }
 
   // Reap a crashed daemon's leftovers before we bind.
   cleanStale(projectRoot, { execFile });
@@ -179,10 +265,22 @@ async function startDaemon({
     fs.writeSync(lockFd, String(process.pid) + '\n');
   } catch (err) {
     if (err && err.code === 'EEXIST') {
+      // warn, not error: a spawn-race loser failing here is the lock DOING ITS
+      // JOB. It is worth seeing (a workspace where it repeats means two agents
+      // are fighting over one device) but it is not a malfunction.
+      safeObserve({ level: 'warn', event: 'daemon.lock_conflict', error_code: 'ELOCKED' });
       const e = new Error('device session daemon already starting for this workspace (lock held)');
       e.code = 'ELOCKED';
       throw e;
     }
+    // Not a race — EACCES, EROFS, ENOSPC on .session/. An invisible death that
+    // nothing else in the system reports.
+    safeObserve({
+      level: 'error',
+      event: 'daemon.start_failure',
+      error_code: err && err.code,
+      message: err && (err.message || String(err)),
+    });
     throw err;
   }
 
@@ -205,10 +303,49 @@ async function startDaemon({
   try {
     ({ call, close } = await createCall({ device }));
   } 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.
+    safeObserve({
+      level: 'error',
+      event: 'daemon.connect_failure',
+      error_code: err && err.code,
+      message: err && (err.message || String(err)),
+      dur_ms: Date.now() - startedAtMs,
+    });
     releaseLock();
     throw err;
   }
 
+  // One bounded, measured call, built ONCE and shared by every connection: the
+  // timeout, the sink and the connection are all per-daemon, so nothing about
+  // it is per-socket. Built HERE, before server.listen() below, or the first
+  // frame to arrive would hit a temporal dead zone.
+  //
+  // safeObserve, never the raw `observe` — device-call.js is deliberately not
+  // guarded a second time (pinned in tests/unit/device/device-call.test.js).
+  //
+  // The per-call correlation id is minted HERE, from a counter scoped to this
+  // daemon lifetime — the same scope as session_id, one level down. It is what
+  // makes call.start and call.end pairable: session_id cannot do it (every call
+  // in a lifetime shares one) and neither can position or timestamp, because
+  // the daemon multiplexes and two sockets' calls interleave and finish out of
+  // order. The counter lives at THIS scope rather than inside makeDeviceCall
+  // because that module's factory scope must stay free of mutable state (see
+  // its WARNING), and because "per daemon lifetime" is a fact this function
+  // owns.
+  //
+  // Deliberately NOT the frame's `req.id`, which the router discards: that
+  // value is client-chosen and the socket is reachable by any process on the
+  // machine, so it could not be sends:true in the event catalog. A
+  // daemon-minted integer can, on the same grounds as dur_ms.
+  let callSeq = 0;
+  const invoke = makeDeviceCall(call, {
+    scheduleTimeout,
+    observe: safeObserve,
+    timeoutMs: DAEMON_CALL_TIMEOUT_MS,
+    nextCallId: () => (callSeq += 1),
+  });
+
   let idleTimer = null;
   let stopping = false;
   let inFlight = 0; // device calls whose reply has not yet been sent
@@ -219,19 +356,21 @@ async function startDaemon({
   const notifyUndeliverable =
     typeof onUndeliverable === 'function'
       ? onUndeliverable
-      : (info) => {
-          try {
-            process.stderr.write(
-              `mauto-session-daemon: undeliverable reply id=${info.id}: ${info.reason}\n`
-            );
-          } catch (_) {
-            // 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.
-          }
-        };
+      : (info) =>
+          // Was a bespoke process.stderr.write with its own try/catch. It is
+          // the same destination — the stderr sink writes to fd 2, which since
+          // #176 IS mobile-automator/.session/daemon.log — but now structured,
+          // and safeObserve (plus record()'s own never-throw guarantee)
+          // subsumes the hand-rolled guard. That guard mattered: this runs
+          // inside reply(), on the socket's async data handler, so a throw here
+          // would surface as an unhandled rejection. The frame id and the
+          // transport reason go in `message`, which is sends:false: a socket
+          // errno is free text and free text never reaches the telemetry path.
+          safeObserve({
+            level: 'warn',
+            event: 'daemon.undeliverable',
+            message: `id=${info.id}: ${info.reason}`,
+          });
 
   function recordUndeliverable(info) {
     undeliverable.push(info);
@@ -252,16 +391,75 @@ async function startDaemon({
     if (stopping) return; // never re-arm once we have begun tearing down
     if (idleMs > 0 && Number.isFinite(idleMs)) {
       idleTimer = setTimeout(() => {
-        stop().catch(() => {});
+        stop('idle').catch(() => {});
       }, idleMs);
       if (typeof idleTimer.unref === 'function') idleTimer.unref();
     }
   }
 
-  async function stop() {
+  let flushTimer = null;
+
+  function clearFlush() {
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+  }
+
+  // Why the daemon does this at all: a one-shot verb cannot. process.exit()
+  // tears down a pending socket, so a verb's POST is dropped a large fraction
+  // of the time. The daemon is the only process here with an event loop, and
+  // between device calls it is doing nothing at all.
+  //
+  // A self-rescheduling setTimeout rather than setInterval: the flusher returns
+  // the delay it wants (exponential backoff on a retryable failure, reset on
+  // success), and setInterval cannot express that. unref'd, so a pending flush
+  // can never hold the process open past its idle reap or delay a stop().
+  //
+  // In-flight device calls are skipped rather than competed with — the flush is
+  // strictly lower priority than the device work the user is waiting on, and
+  // the very next tick picks it up.
+  function armFlush(delayMs) {
+    clearFlush();
+    if (!flush || stopping) return;
+    if (!(delayMs > 0) || !Number.isFinite(delayMs)) return;
+    flushTimer = setTimeout(async () => {
+      if (stopping) return;
+      if (inFlight > 0) {
+        armFlush(delayMs);
+        return;
+      }
+      let next = delayMs;
+      try {
+        const r = await flush();
+        if (r && Number.isFinite(r.nextDelayMs) && r.nextDelayMs > 0) next = r.nextDelayMs;
+      } catch (_) {
+        // flush() is already total (src/observe/flush.js); this is that
+        // guarantee restated as a property of the daemon rather than of its
+        // current caller.
+      }
+      armFlush(next);
+    }, delayMs);
+    if (typeof flushTimer.unref === 'function') flushTimer.unref();
+  }
+
+  async function stop(reason = 'explicit') {
     if (stopping) return;
     stopping = true;
     clearIdle();
+    clearFlush();
+
+    // Recorded HERE, before the drain, not after teardown. stop() can block on
+    // an in-flight device call and on close()ing a mobile-mcp child that will
+    // not die — the two hangs most worth seeing — and an event written after
+    // them would never be written at all. The `if (stopping) return` above is
+    // what keeps this to one event per daemon.
+    safeObserve({
+      level: 'info',
+      event: 'daemon.stop',
+      stop_reason: reason,
+      dur_ms: Date.now() - startedAtMs,
+    });
 
     // Drain-before-teardown: never destroy a socket or tear down the shared
     // connection while a device call is still in flight. The action already hit
@@ -299,7 +497,7 @@ async function startDaemon({
   }
 
   function onSignal() {
-    stop().catch(() => {});
+    stop('signal').catch(() => {});
   }
 
   server.on('connection', (socket) => {
@@ -397,7 +595,7 @@ async function startDaemon({
         if (req.type === 'shutdown') {
           await reply({ id: req.id, ok: true, result: { stopping: true } });
           // Reply already flushed (awaited) — now tear down.
-          setImmediate(() => stop().catch(() => {}));
+          setImmediate(() => stop('shutdown').catch(() => {}));
           continue;
         }
         if (req.type === 'ping') {
@@ -418,43 +616,30 @@ async function startDaemon({
             armIdle();
             continue;
           }
+          // inFlight/armIdle stay HERE, not in the decorator: they gate stop()'s
+          // drain and are reported by ping/getSessionStatus, which are facts
+          // about the daemon's sockets rather than about one device call.
           inFlight += 1;
           try {
-            // Bound the shared mobile-mcp call. The daemon's timeout (25s) is
-            // BELOW the client's (30s) so this error always reaches the client
-            // as an honest {kind:'timeout'} reply instead of being dropped by
-            // the client's own timeout — a dropped reply reads as a
-            // false-failure and prompts a retry → double-execution. The
-            // underlying call is NOT cancellable; it keeps running in the
-            // background, which is fine — the point is the agent gets a bounded,
-            // honest error. Swallow the loser's eventual settlement so it can't
-            // surface as an unhandled rejection after the race already settled.
-            const callPromise = call(req.tool, req.args || {});
-            callPromise.catch(() => {});
-            const result = await Promise.race([
-              callPromise,
-              scheduleTimeout(DAEMON_CALL_TIMEOUT_MS).then(() => {
-                const e = new Error(
-                  `${req.tool}: the mobile-mcp call did not respond within ${DAEMON_CALL_TIMEOUT_MS}ms`
-                );
-                e.kind = 'timeout';
-                e.hint = 'the action may have partially executed on the device — verify state before retrying';
-                throw e;
-              }),
-            ]);
+            const result = await invoke(req.tool, req.args || {});
             await reply({ id: req.id, ok: true, result });
           } catch (err) {
-            if (err && err.kind === 'timeout') {
-              await reply({
-                id: req.id,
-                ok: false,
-                error: { message: err.message, kind: 'timeout', hint: err.hint },
-              });
-            } else {
-              // Non-timeout failure: no kind → client/deviceFail default to
-              // 'device'. Only the timeout path sets kind:'timeout'.
-              await reply({ id: req.id, ok: false, error: { message: err.message || String(err) } });
-            }
+            // Only a timeout carries kind/hint outward; a non-timeout failure
+            // drops both so client/deviceFail defaults to 'device'. Do NOT
+            // "simplify" this to `kind: err && err.kind`: that would forward an
+            // engine-invented kind that exitCodeFor does not enumerate (turning
+            // a device failure's exit 2 into exit 1) and would emit "kind":null
+            // for a falsy rejection. daemon-timeout.test.js pins both.
+            const timedOut = Boolean(err && err.kind === 'timeout');
+            await reply({
+              id: req.id,
+              ok: false,
+              error: {
+                message: err && (err.message || String(err)),
+                kind: timedOut ? 'timeout' : undefined,
+                hint: timedOut ? err.hint : undefined,
+              },
+            });
           } finally {
             inFlight -= 1;
             armIdle(); // arm idle only after the reply has completed
@@ -488,6 +673,13 @@ async function startDaemon({
     // 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.
+    safeObserve({
+      level: 'error',
+      event: 'daemon.listen_failure',
+      error_code: err && err.code,
+      message: err && (err.message || String(err)),
+      dur_ms: Date.now() - startedAtMs,
+    });
     try {
       await close();
     } catch (_) {
@@ -500,6 +692,10 @@ async function startDaemon({
   // Persist handle + pidfile now that we are actually listening.
   const handle = {
     pid: process.pid,
+    // Correlates every event from this daemon lifetime, which run_id cannot:
+    // it lives in the handle so a verb reads it from a file that is already
+    // there instead of paying a socket round trip (src/device/session-handle.js).
+    session_id: sessionId,
     device: device || null,
     socket: socketPath,
     started_at: new Date().toISOString(),
@@ -512,10 +708,28 @@ async function startDaemon({
   process.on('SIGINT', onSignal);
 
   armIdle();
+  armFlush(flushIntervalMs);
+
+  // Recorded after the handle exists, so anything reading the log can also read
+  // the handle it names. device_id is sends:false — a device serial never
+  // leaves the machine.
+  safeObserve({
+    level: 'info',
+    event: 'daemon.start',
+    device_id: device || undefined,
+    dur_ms: Date.now() - startedAtMs,
+  });
 
   return {
     socketPath,
     device: device || null,
+    sessionId,
+    // This daemon's recorder, already bound to the identity above and already
+    // guarded. Handed back so a caller whose own instrumentation outlives
+    // startDaemon — the bin's crash guards — can adopt it instead of building a
+    // second one and binding the id by hand, which is how the two owners this
+    // replaced came about.
+    observe: safeObserve,
     stop,
     // Replies that could not be delivered (peer gone / unflushable). Surfaced so
     // callers/tests can observe transport failures instead of them being eaten.

package/src/device/session-handle.js

@@ -0,0 +1,53 @@
+'use strict';
+
+// Read side of mobile-automator/.session/session.json — the ONLY one — plus the
+// generator for the session id it carries. resolve-connection.js's
+// readHandleDevice() is a projection onto the `device` field and delegates here;
+// it used to parse the file itself, which meant two readers of one artifact.
+//
+// The handle is where session_id lives because it is a file that is ALREADY
+// there, already written at exactly the right moment (once the daemon is
+// listening) and already removed at exactly the right moment (stop()). A verb
+// that wants to stamp its events with the live session's id must not have to
+// pay a socket round trip for it, and a second copy in the ping reply would be
+// a second source of truth that can disagree with this one.
+//
+// Nothing here throws: an absent, unreadable or malformed handle means "no
+// session", which is a normal state, not an error.
+
+const realFs = require('fs');
+const crypto = require('crypto');
+
+const { handlePath } = require('./session-paths');
+const { SESSION_ID_PATTERN } = require('../observe/event');
+
+// 16 hex chars from the CSPRNG, derived from NOTHING — not the project root,
+// not the device, not the pid. That is what makes the event catalog's
+// `sends: true` on session_id true rather than merely asserted, and
+// tests/unit/device/session-handle.test.js is where the claim is enforced.
+// readSessionId() holds the read side to the same shape (SESSION_ID_PATTERN).
+//
+// Deliberately NOT persisted across daemon restarts. A stable id would be a
+// machine fingerprint; this one changes exactly when the daemon does, which is
+// the fact it exists to report — run_id cannot express "the daemon died and
+// respawned mid-run".
+function newSessionId() {
+  return crypto.randomBytes(8).toString('hex');
+}
+
+function readHandle(projectRoot, { fs = realFs } = {}) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(handlePath(projectRoot), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function readSessionId(projectRoot, { fs = realFs } = {}) {
+  const handle = readHandle(projectRoot, { fs });
+  const id = handle && handle.session_id;
+  return typeof id === 'string' && SESSION_ID_PATTERN.test(id) ? id : null;
+}
+
+module.exports = { newSessionId, readHandle, readSessionId };

package/src/device/session-log.js

@@ -12,8 +12,10 @@
 const realFs = require('fs');
 
 const { sessionDir, logFilePath } = require('./session-paths');
-
-const MAX_LOG_BYTES = 1024 * 1024;
+// Rotation lives in src/util/log-rotate.js because the structured event log
+// wants the identical policy. Re-exported below so this module's public surface
+// is unchanged for its existing callers.
+const { MAX_LOG_BYTES, rotateIfLarge } = require('../util/log-rotate');
 
 // The degraded handle, expressed as a VALUE so callers never branch on null.
 // `stdio: 'ignore'` is the behaviour that predates #163.
@@ -27,19 +29,6 @@ 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
@@ -60,7 +49,7 @@ function openDaemonLog(projectRoot, { maxBytes = MAX_LOG_BYTES, fs = realFs } =
     fs.mkdirSync(sessionDir(projectRoot), { recursive: true });
 
     const logPath = logFilePath(projectRoot);
-    rotateIfLarge(logPath, maxBytes, fs);
+    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