mobile-automator 0.24.0 → 0.26.0

package/src/observe/failure-capture.js

@@ -0,0 +1,166 @@
+'use strict';
+
+// Photograph a device failure while the bridge is still live.
+//
+// The value is in what it replaces: today a failed run's result file carries
+// the agent's NARRATIVE of what the screen looked like. This makes it carry the
+// screen.
+//
+// It is a module rather than four lines inside connectBridge because every one
+// of its rules is a rule about failure handling, and they are easier to state —
+// and to test — where they are not interleaved with commander:
+//
+//   1. It never throws. A capture is a daemon round-trip and can fail for
+//      exactly the reasons the original call failed.
+//   2. It never touches the caller's result. The original error is what the
+//      agent needs; the screenshot is a footnote. The return value is
+//      deliberately ignored at the call site, and the envelope reaches emit()
+//      byte-identical whether this succeeded, failed, or never ran.
+//   3. It captures only what it can correlate. With no run id there is no trace
+//      to reference the file from and no finalize to collect it, so the PNG
+//      would be litter in a directory the user did not ask us to fill — the
+//      same argument the file sink already makes about creating
+//      mobile-automator/. It also makes the run id the single switch for this
+//      whole slice: export it and you get traces, measured durations and
+//      failure evidence; leave it unset and 0.24.0's behaviour is unchanged.
+
+const realFs = require('fs');
+const path = require('path');
+
+const { record } = require('./recorder');
+const { runTracePath, workspaceDir } = require('./paths');
+
+// The failure kinds worth a picture.
+//
+// `device` is the ordinary "the device said no". `timeout` is included
+// deliberately and is arguably the more valuable of the two: a timed-out call
+// may have PARTIALLY executed — session-client's own hint says so — and the
+// screen is the only way to find out what actually happened.
+//
+// `invalid_input` is excluded: nothing reached the device, so the picture would
+// show the state BEFORE the verb and be evidence of nothing. `internal` is
+// excluded for the same reason, and because a crashed CLI has a stack trace,
+// which is the artifact that actually helps.
+const CAPTURED_KINDS = new Set(['device', 'timeout']);
+
+function isCapturable(result) {
+  return Boolean(
+    result && result.envelope && result.envelope.ok === false && CAPTURED_KINDS.has(result.exitKind)
+  );
+}
+
+// verb becomes a filename, not a correlation key the way runId does (see
+// runTracePath's comment in ./paths.js) — the event this module records
+// carries the raw verb in its own field regardless of what the filename
+// says, so nothing downstream reads the filename to learn which verb failed.
+// That means a REJECT-and-fall-back is enough here; there is no
+// isValidRunId-style argument that sanitizing would corrupt a measurement.
+//
+// It is safe today only because verb is always command.name() from a
+// commander command that already parsed successfully — a guarantee this
+// module does not control and must not depend on. Anything that is not a
+// plain token falls back to the same 'device' literal the module already
+// used for a missing verb, so the ordinary case is unaffected.
+const SAFE_VERB_TOKEN = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+
+function safeVerbToken(verb) {
+  return typeof verb === 'string' && SAFE_VERB_TOKEN.test(verb) ? verb : 'device';
+}
+
+// mobile-automator/screenshots/<runId>/<verb>-<ts>.png.
+//
+// Under screenshots/, NOT results/<run_id>/screenshots/ which the execute guide
+// uses for agent-directed captures, because `mauto setup` writes
+// mobile-automator/.gitignore covering `screenshots/` and not the results tree.
+// A photograph of a failing app is precisely the artifact that must not ride
+// into a user's commit on a `git add -A`.
+function failureShotPath(projectRoot, runId, verb) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return path.join(
+    projectRoot,
+    'mobile-automator',
+    'screenshots',
+    runId,
+    `${safeVerbToken(verb)}-${stamp}.png`
+  );
+}
+
+async function captureOnFailure({
+  bridge,
+  result,
+  projectRoot,
+  runId,
+  verb,
+  env = process.env,
+  fs = realFs,
+} = {}) {
+  // Resolved once and reused as BOTH the trace target and the is-this-id-safe
+  // predicate — one gate rather than a second check that can disagree with it.
+  // Declared here and assigned inside the try so a non-string projectRoot
+  // (path.join throws via logsDir for a VALID run id) is caught by this
+  // function's own catch instead of escaping to a caller that has none.
+  let tracePath = null;
+  try {
+    tracePath = runTracePath(projectRoot, runId, env);
+    if (!isCapturable(result)) return null;
+    if (!tracePath) return null;
+    // The same permission the file sink requires (see sinks/file.js): an
+    // observability artifact may not create mobile-automator/ where no
+    // workspace exists. A valid run id is not consent to litter — without this
+    // gate a failing verb would mkdir screenshots/ into an undiscoverable
+    // tree, the #188 pathology.
+    if (!fs.existsSync(workspaceDir(projectRoot))) return null;
+    if (!bridge || typeof bridge.screenshot !== 'function') return null;
+
+    const dest = failureShotPath(projectRoot, runId, verb);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    // Bounded by the layers below, not here: the daemon fails a call at
+    // DAEMON_CALL_TIMEOUT_MS and the client gives up on a reply at its own
+    // timeout, so this cannot wait forever. A third bound would be a third
+    // policy to keep in step with the other two.
+    const saved = (await bridge.screenshot(dest)) || dest;
+
+    record(
+      {
+        // info, not warn — the inverse of slice 2's daemon choice, for slice
+        // 2's own reason. The daemon's stderr is a log file; the CLI's is a
+        // human's terminal, and the envelope has already told them the verb
+        // failed. A second line about the screenshot is noise on top of noise.
+        level: 'info',
+        src: 'cli',
+        event: 'screenshot.on_failure',
+        verb,
+        run_id: runId,
+        error_kind: result.envelope.error && result.envelope.error.kind,
+        // sends:false in the event catalog — a path leaks usernames and project
+        // layout, so it stays local. `result finalize` reads it back from here.
+        path: saved,
+      },
+      { projectRoot, env, tracePath }
+    );
+    return saved;
+  } catch (err) {
+    // Recorded and discarded. Replacing the original error with "could not take
+    // a screenshot" would answer a question nobody asked and lose the answer to
+    // the one they did.
+    try {
+      record(
+        {
+          level: 'info',
+          src: 'cli',
+          event: 'screenshot.capture_failed',
+          verb,
+          run_id: runId,
+          message: (err && (err.message || String(err))) || 'unknown capture failure',
+        },
+        { projectRoot, env, tracePath }
+      );
+    } catch (_) {
+      // record() is already total; this exists so the outer catch cannot itself
+      // be the thing that throws.
+    }
+    return null;
+  }
+}
+
+module.exports = { captureOnFailure, isCapturable, CAPTURED_KINDS };

package/src/observe/flush.js

@@ -0,0 +1,177 @@
+'use strict';
+
+// Drains the spool. The only caller of src/observe/transport.js.
+//
+// Delivery is AT-LEAST-ONCE, deliberately. A batch can be posted successfully
+// and then fail to unlink (a SIGKILLed daemon, a read-only .logs), or chunk 1
+// can succeed while chunk 2 fails retryably — and in both cases the batch is
+// re-sent. Two things make that the right trade:
+//
+//   * every spooled line carries msg_id, sent as the PostHog event's `uuid`,
+//     so ingestion deduplicates;
+//   * the alternative — rewriting the claimed file with the unsent remainder —
+//     is a write performed on the failure path, whose own failure mode is
+//     LOSING records rather than duplicating them. Duplicates are recoverable
+//     at the sink; a lost record is not.
+
+const realFs = require('fs');
+
+const spool = require('./spool');
+const realTransport = require('./transport');
+const { decideForProject } = require('./telemetry');
+
+// Two chunks covers a full 256 KiB spool at ~250 bytes/line, so the duplicate
+// window on a partial failure is at most one chunk.
+const BATCH_SIZE = 250;
+
+const FLUSH_INTERVAL_MS = 60 * 1000;
+const MAX_FLUSH_INTERVAL_MS = 30 * 60 * 1000;
+
+// A permanently-offline machine converges to <= 256 KiB of spool plus this many
+// claimed batches, all inside .logs/, which `mauto setup` gitignores.
+const MAX_CLAIMED = 3;
+
+function chunk(items, size) {
+  const out = [];
+  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+  return out;
+}
+
+function makeFlusher({
+  projectRoot,
+  env = process.env,
+  transport = realTransport,
+  observe = () => {},
+  fs = realFs,
+} = {}) {
+  let nextDelayMs = FLUSH_INTERVAL_MS;
+
+  return async function flush() {
+    const decision = decideForProject(projectRoot, env);
+    // Layer two of "no upload path is reachable while disabled": the transport
+    // is not merely unused here, it is not REACHED. The unit suite injects a
+    // transport that throws if called and asserts this line returns first.
+    if (!decision.enabled) {
+      return { skipped: decision.reason, sent: 0, dropped: 0, kept: 0, kept_events: 0, ok: true, nextDelayMs };
+    }
+
+    const startedAt = Date.now();
+    let sent = 0;
+    let dropped = 0;
+    let kept = 0;
+    // Payload count of batches left claimed for retry — distinct from `kept`,
+    // which counts BATCHES (files), not events. Needed so a flush that only
+    // ever retries (nothing sent or dropped yet) still reports how many
+    // events it actually touched.
+    let keptEvents = 0;
+    let lastStatus = 0;
+    let retryable = false;
+
+    try {
+      // Leftovers first, oldest first, then whatever has accumulated since.
+      const batches = spool.listClaimed({ projectRoot, env, fs });
+      const fresh = spool.claim({ projectRoot, env, fs });
+      if (fresh) batches.push(fresh);
+
+      for (const file of batches) {
+        const payloads = spool.readBatch(file, { fs });
+        if (payloads.length === 0) {
+          safeUnlink(file, fs);
+          continue;
+        }
+
+        let batchRetryable = false;
+        let batchSent = 0;
+        let batchDropped = 0;
+
+        for (const part of chunk(payloads, BATCH_SIZE)) {
+          let r;
+          try {
+            r = await transport.postBatch(part, { env });
+          } catch (_) {
+            // postBatch is documented never to reject; this is the guarantee
+            // restated locally so an injected transport cannot break the daemon.
+            r = { ok: false, retry: true, status: 0 };
+          }
+          lastStatus = r.status;
+          if (r.ok) {
+            batchSent += part.length;
+            continue;
+          }
+          if (r.retry) {
+            batchRetryable = true;
+            break; // stop at the first retryable chunk; the file stays claimed
+          }
+          // Permanent (4xx other than 429): a malformed body or a revoked token
+          // would retry forever and the queue would never drain. Drop it.
+          batchDropped += part.length;
+        }
+
+        sent += batchSent;
+        dropped += batchDropped;
+
+        if (batchRetryable) {
+          kept += 1;
+          keptEvents += payloads.length;
+          retryable = true;
+          break; // the network is down; do not hammer the remaining batches
+        }
+        safeUnlink(file, fs);
+      }
+
+      // Converge: beyond the cap, the oldest claimed batches go.
+      const remaining = spool.listClaimed({ projectRoot, env, fs });
+      for (const stale of remaining.slice(0, Math.max(0, remaining.length - MAX_CLAIMED))) {
+        safeUnlink(stale, fs);
+      }
+    } catch (_) {
+      // Observability is never load-bearing. A flush that blew up in an
+      // unanticipated way costs a log line, not a daemon.
+      retryable = true;
+    }
+
+    // Not merely !retryable: a permanently-rejected batch is dropped rather
+    // than retried, so `retryable` stays false for it, but it is still a
+    // failed flush — data was lost, not merely delayed. `ok` must reflect
+    // both failure shapes, and only the retryable one feeds the backoff
+    // below (a permanent drop is definitionally never going to succeed by
+    // waiting longer).
+    const ok = !retryable && dropped === 0;
+
+    nextDelayMs = retryable
+      ? Math.min(nextDelayMs * 2, MAX_FLUSH_INTERVAL_MS)
+      : FLUSH_INTERVAL_MS;
+
+    // `debug`, not `warn`. Slice 2 made warn/error the daemon's genuine-failure
+    // levels, and daemon.log is where a human debugging a dead daemon looks. A
+    // user's flaky wifi is not a daemon failure, and putting it at warn would
+    // train that reader to ignore the level that matters.
+    if (sent + dropped + kept > 0) {
+      observe({
+        level: 'debug',
+        event: 'telemetry.flush',
+        ok,
+        count: sent + dropped + keptEvents,
+        http_status: lastStatus || undefined,
+        dur_ms: Date.now() - startedAt,
+      });
+    }
+
+    // Units: `kept` counts BATCHES (files) left claimed for retry; `sent`,
+    // `dropped` and `kept_events` count events. `kept_events` exists because a
+    // flush that only ever retries (nothing sent or dropped yet) still needs
+    // to report how many events it actually touched.
+    return { sent, dropped, kept, kept_events: keptEvents, ok, nextDelayMs };
+  };
+}
+
+function safeUnlink(file, fs) {
+  try {
+    fs.unlinkSync(file);
+  } catch (_) {
+    // Already gone, or a read-only .logs. Either way the next flush's
+    // MAX_CLAIMED prune is the backstop.
+  }
+}
+
+module.exports = { BATCH_SIZE, FLUSH_INTERVAL_MS, MAX_FLUSH_INTERVAL_MS, MAX_CLAIMED, makeFlusher };

package/src/observe/paths.js

@@ -0,0 +1,125 @@
+'use strict';
+
+// Pure path helpers for the structured event logs. Side-effect-free so they
+// can be unit-tested without touching the filesystem, matching
+// src/device/session-paths.js.
+//
+// NOTE: this is NOT where the daemon's raw stdio goes. That lives at
+// mobile-automator/.session/daemon.log (session-paths.logFilePath, PR #176).
+// Two artifacts, two homes: raw process output there, structured events here.
+
+const path = require('path');
+
+const LOGS_DIRNAME = '.logs';
+const MAIN_LOG_NAME = 'mauto.ndjson';
+const DAEMON_LOG_NAME = 'daemon.ndjson';
+const RUN_TRACE_PREFIX = 'run-';
+const SPOOL_NAME = 'telemetry.spool';
+
+// The workspace root `mauto setup` creates. The file sink treats its existence
+// as permission to log: mauto runs from whatever directory a user is standing
+// in, so creating this tree as a side effect of logging would litter unrelated
+// repos with a directory that has no .gitignore in it.
+function workspaceDir(projectRoot) {
+  return path.join(projectRoot, 'mobile-automator');
+}
+
+function logsDir(projectRoot, env = process.env) {
+  if (env && env.MAUTO_LOG_DIR) return path.resolve(env.MAUTO_LOG_DIR);
+  return path.join(projectRoot, 'mobile-automator', LOGS_DIRNAME);
+}
+
+function mainLogPath(projectRoot, env = process.env) {
+  return path.join(logsDir(projectRoot, env), MAIN_LOG_NAME);
+}
+
+// The DAEMON's structured event stream — deliberately a different file from
+// mauto.ndjson. Two reasons, in the order they actually carry weight:
+//
+// VOLUME. A 40-step scenario writes ~40 CLI verb.end lines against 40+ daemon
+// call.end lines. Sharing one 1 MiB budget would rotate the CLI's history out
+// roughly twice as fast, and the two streams are read for different questions.
+//
+// PRECEDENT. .session/daemon.log is already a daemon-owned file distinct from
+// the CLI's diagnostics. Two writers, two files is the shape this codebase
+// already chose.
+//
+// What this does NOT do is make rotation single-writer, and an earlier version
+// of this comment claimed it did. rotateIfLarge is statSync-then-renameSync, so
+// concurrent rotations can clobber a generation — but mauto.ndjson is ALREADY
+// multi-writer (any two concurrent `mauto` verbs race it), and daemon.ndjson is
+// not strictly single-writer either, because a spawn-race lock loser also runs
+// bin/mauto-session-daemon.js and writes daemon.lock_conflict here. Splitting
+// the files removes the daemon from one instance of that race; it does not
+// remove the race. The exposure is a handful of ~200-byte appends in a window of
+// milliseconds, worst case one lost generation of a bounded log, and
+// rotateIfLarge already swallows the ENOENT a losing rename produces.
+//
+// It is also not .session/daemon.log, which is the same process's RAW stdio
+// (PR #176). Same writer, two artifacts: unstructured text a human reads there,
+// parseable events here.
+function daemonEventLogPath(projectRoot, env = process.env) {
+  return path.join(logsDir(projectRoot, env), DAEMON_LOG_NAME);
+}
+
+// The telemetry queue. Deliberately NOT a .ndjson name even though its content
+// is NDJSON: TROUBLESHOOTING.md documents `cat mobile-automator/.logs/*.ndjson`
+// as the merged CLI+daemon timeline, and the spool is not part of that timeline
+// — it is a queue that gets renamed out from under a reader mid-flush. The
+// extension is the interface that keeps the two apart.
+function spoolPath(projectRoot, env = process.env) {
+  return path.join(logsDir(projectRoot, env), SPOOL_NAME);
+}
+
+// A run id becomes a FILENAME, so it is validated rather than sanitized.
+//
+// Sanitizing — replacing the offending characters — is the tempting move and it
+// is wrong here: `login/smoke` and `login-smoke` would collapse onto one trace,
+// and `result finalize` would then derive a duration spanning two unrelated
+// runs. A contaminated measurement presented as measured is worse than no
+// measurement, which is the whole premise of this slice. An id that cannot be a
+// filename gets NO trace and everything degrades to the MAUTO_RUN_ID-unset
+// case, which is 0.24.0's behaviour.
+//
+// The charset is deliberately WIDER than the result schema's
+// ^run_\d{8}_\d{6}$: MAUTO_RUN_ID is agent-chosen and this is not the place to
+// start enforcing a pattern the CLI has never enforced. It is narrow enough
+// that no accepted value can contain a path separator, a NUL, a drive colon or
+// a leading dot, so `..`, `../../etc/x`, `/etc/x` and `C:\x` are all rejected
+// by construction rather than by a list of cases someone has to keep complete.
+const RUN_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+function isValidRunId(runId) {
+  if (typeof runId !== 'string' || !RUN_ID_PATTERN.test(runId)) return false;
+  // Belt and braces against a future widening of the charset: an accepted id
+  // must survive path.basename unchanged, so it can never be a path.
+  return path.basename(runId) === runId;
+}
+
+// The per-run trace file, or null when the id cannot safely name one.
+//
+// Returning null rather than throwing is what lets every call site treat "no
+// usable run id" and "no run id at all" as one already-handled case, and makes
+// this the SINGLE gate: a hostile id cannot be turned into a write target
+// anywhere in the codebase, because this is the only function that builds the
+// path. src/observe/failure-capture.js reuses it as its own safety check for
+// exactly that reason.
+function runTracePath(projectRoot, runId, env = process.env) {
+  if (!isValidRunId(runId)) return null;
+  return path.join(logsDir(projectRoot, env), `${RUN_TRACE_PREFIX}${runId}.ndjson`);
+}
+
+module.exports = {
+  LOGS_DIRNAME,
+  MAIN_LOG_NAME,
+  DAEMON_LOG_NAME,
+  RUN_TRACE_PREFIX,
+  SPOOL_NAME,
+  workspaceDir,
+  logsDir,
+  mainLogPath,
+  daemonEventLogPath,
+  isValidRunId,
+  runTracePath,
+  spoolPath,
+};

package/src/observe/recorder.js

@@ -0,0 +1,178 @@
+'use strict';
+
+// The single seam. Everything that wants to be observable calls record().
+//
+// Two properties are load-bearing and both are tested:
+//
+//   1. It never throws and never propagates. Observability is not allowed to
+//      be the reason a verb fails, so each sink is individually guarded and
+//      the whole body is wrapped again. A throwing sink must not deprive its
+//      neighbours of the event.
+//   2. It writes nothing to stdout. That is a property of the sinks, but the
+//      recorder is where the sink list is chosen, so it is the enforcement
+//      point for which sinks exist at all.
+//
+// Level filtering happens here rather than in the sinks because the two sinks
+// have DIFFERENT thresholds (stderr warn, file info) and only the recorder
+// knows which sink it is currently feeding.
+//
+// A sink is a { threshold, write } pair and ALWAYS states its own threshold —
+// there is no default filled in on its behalf. A test that wants the real
+// thresholds wraps defaultSinks(root, env) and swaps only `write`, so it
+// exercises the levels production resolves instead of a branch that exists
+// only for tests.
+
+const { makeEvent } = require('./event');
+const { resolveLevels, atLeast } = require('./settings');
+const stderrSink = require('./sinks/stderr');
+const fileSink = require('./sinks/file');
+const spoolSink = require('./spool');
+const { decideForProject } = require('./telemetry');
+
+// `logPath` is passed straight through to the file sink, which already takes it
+// (sinks/file.js:44) and falls back to mauto.ndjson when it is undefined. So
+// omitting it — as record() does — is exactly today's CLI behaviour, and naming
+// it is how a writer with its own log file (the daemon's daemon.ndjson) gets one
+// without a second copy of this list.
+//
+// `tracePath` adds a THIRD sink — the per-run trace — and two things about it
+// are deliberate:
+//
+//   ADDITIONAL, not a redirect. Sending a run's events to the trace instead of
+//   mauto.ndjson would punch a hole in the maintainer log across exactly the
+//   invocations a bug report is about, and would let the trace's cap silently
+//   drop CLI history. The cost of writing both is one extra ~300-byte
+//   open/write/close per verb against a 112ms process start.
+//
+//   INJECTED, never resolved from `env` here. A daemon reads MAUTO_RUN_ID from
+//   whichever verb spawned it and then outlives that run — its environment is
+//   pinned at spawn and cannot change. Resolving the trace from `env` would
+//   make boundRecorder pick it up, and the daemon would file every later run's
+//   device calls under the first run's id. Only cli.js's finish() passes this.
+//
+// The trace's threshold is levels.file (info), the same as the main log, not
+// levels.stderr (warn): a trace exists to reconstruct one run, and a threshold
+// that filtered out most of a passing run's own verb.end events would defeat
+// that purpose. It is deliberately not wider than `info` either — nothing in
+// this slice records below `info`, so there is no debug firehose to admit by
+// pinning the trace looser than the log it is bound to the same constant as.
+function defaultSinks(projectRoot, env, { logPath, tracePath } = {}) {
+  const levels = resolveLevels(env);
+  const sinks = [
+    { threshold: levels.stderr, write: (e) => stderrSink.write(e) },
+    { threshold: levels.file, write: (e) => fileSink.write(e, { projectRoot, env, logPath }) },
+  ];
+  if (tracePath) {
+    sinks.push({
+      threshold: levels.file,
+      // bound:'cap' — a trace must not rotate; see sinks/file.js.
+      write: (e) => fileSink.write(e, { projectRoot, env, logPath: tracePath, bound: 'cap' }),
+    });
+  }
+
+  // The spool is the ONLY path by which an event can leave this machine, so
+  // it is not merely level-gated — it is not CONSTRUCTED at all until a
+  // human has opted in. While telemetry is off there is no spool file,
+  // which means there is nothing for a flusher to find even if one ran.
+  // That is the first of the three layers behind "no upload path is
+  // reachable while disabled"; the other two are flush()'s own early
+  // return and the one-file transport lint guard.
+  //
+  // Its threshold is spool.SPOOL_LEVEL, deliberately NOT levels.file:
+  // telemetry has its own separate control, so MAUTO_LOG_LEVEL=debug must
+  // not multiply what leaves the machine by 40x, and MAUTO_LOG_LEVEL=silent
+  // must not be read as consent withdrawal (there is an explicit control for
+  // that: MAUTO_TELEMETRY=0 / DO_NOT_TRACK=1).
+  //
+  // decideForProject memoises per project root — one config.json read per
+  // process, not one per event. See src/observe/telemetry.js.
+  if (decideForProject(projectRoot, env).enabled) {
+    sinks.push({
+      threshold: spoolSink.SPOOL_LEVEL,
+      write: (e) => spoolSink.write(e, { projectRoot, env }),
+    });
+  }
+
+  return sinks;
+}
+
+function record(
+  fields = {},
+  { projectRoot = process.cwd(), env = process.env, sinks, tracePath } = {}
+) {
+  try {
+    const level = fields.level || 'info';
+    const list = sinks || defaultSinks(projectRoot, env, { tracePath });
+    const event = makeEvent({ ...fields, level });
+
+    for (const sink of list) {
+      if (!atLeast(level, sink.threshold)) continue;
+      try {
+        sink.write(event);
+      } catch (_) {
+        // One bad sink must not deprive the others.
+      }
+    }
+  } catch (_) {
+    // Belt and suspenders: a hostile event (cyclic, exotic getters) must not
+    // escape as an exception into the verb's own control flow.
+  }
+}
+
+// The never-load-bearing guarantee, as a function instead of as a warning.
+//
+// record() is already total; this is for the INJECTED seams, which exist so
+// that something OTHER than record() gets passed. In the daemon `call.start`
+// fires before the device call, so an unguarded sink there decides whether a
+// tap happens at all. Exported from here, with the seam it guards, so every
+// boundary shares one implementation.
+function safeObserve(observe) {
+  return (fields) => {
+    try {
+      observe(fields);
+    } catch (_) {
+      /* an observability fault is never worth the work it was describing */
+    }
+  };
+}
+
+// record() bound to one writer, for a process that records many times.
+//
+// record()'s own defaults are written for a one-shot verb that records once and
+// exits. Two of them are wrong for anything long-lived:
+//
+//   projectRoot  defaults to process.cwd(). A detached daemon inherits its cwd
+//                from whichever verb spawned it and then OUTLIVES that verb —
+//                the user can cd away or delete the directory. Bound once, here.
+//   sinks        record() resolves levels per call. For the CLI that is once
+//                per process; for a daemon it would be once per device call,
+//                re-reading an environment that CANNOT change — nothing can
+//                export a variable into a running detached process. So the sink
+//                list is built ONCE, at construction. The consequence is worth
+//                stating: MAUTO_LOG_LEVEL and MAUTO_LOG_DIR are captured at
+//                construction and pinned for the caller's lifetime; for the
+//                daemon, `mauto session end` is how you change them.
+//
+// `fields` are stamped on every event and applied AFTER the caller's, so no call
+// site can forge `src`, claim another session's id or misreport its pid. That
+// identity is the whole point of binding: it is what makes one process's events
+// a queryable group.
+//
+// CONSTRUCTION is total too, and the try/catch is here rather than around each
+// caller's boundRecorder() call because building sinks happens before any event
+// exists, outside the returned observe's own guarantee. A failure degrades to an
+// inert observe — session-log.js's frozen IGNORED handle, not a null every call
+// site has to branch on.
+function boundRecorder({ projectRoot, env = process.env, logPath, fields = {} } = {}) {
+  let sinks;
+  try {
+    sinks = defaultSinks(projectRoot, env, { logPath });
+  } catch (_) {
+    return () => {};
+  }
+  return function observe(extra = {}) {
+    record({ ...extra, ...fields }, { projectRoot, env, sinks });
+  };
+}
+
+module.exports = { record, defaultSinks, boundRecorder, safeObserve };