mobile-automator 0.25.0 → 0.26.0

package/src/device/bridge.js

@@ -2,6 +2,7 @@
 
 const { normalize, parseElements } = require('./element-model');
 const { normalizeDevices } = require('./device-model');
+const { normalizeCrashes } = require('./crash-model');
 const { resolveSingleDevice } = require('./device-resolver');
 
 // Thin wrapper over an injected mobile-mcp `call(toolName, args)` function.
@@ -134,6 +135,35 @@ class DeviceBridge {
   async setOrientation(orientation) {
     return this._call('mobile_set_orientation', { orientation });
   }
+
+  // Crash reports currently readable on the device, as the agnostic crash
+  // model. DIAGNOSTIC only — never invoked by a scenario action, which is why
+  // `crash` has no src/device/action-catalog.js entry (that catalog holds
+  // exactly the scenario-schema actions and its lint guard asserts parity).
+  //
+  // No `device` argument: src/device/tool-args.js injects the resolved id into
+  // every tool except discovery.
+  //
+  // Retention differs by platform and the caller must know it: Android reports
+  // come from the device log and AGE OUT; iOS device/simulator reports are files
+  // that PERSIST and accumulate across runs. Same call, under-inclusive on one
+  // platform and over-inclusive on the other — hence the `since` scoping in
+  // src/device/failure-probe.js. There is deliberately no platform branch here.
+  async listCrashes() {
+    return normalizeCrashes(await this._call('mobile_list_crashes', {}));
+  }
+
+  // The full text of one crash report. The engine returns a bare string (its
+  // `response.data.content`), so coerce rather than assume: an engine that
+  // starts wrapping it must not turn this into "[object Object]" at the CLI.
+  async getCrash(id) {
+    const result = await this._call('mobile_get_crash', { id });
+    if (typeof result === 'string') return result;
+    if (result && typeof result === 'object' && typeof result.content === 'string') {
+      return result.content;
+    }
+    return String(result == null ? '' : result);
+  }
 }
 
 module.exports = { DeviceBridge };

package/src/device/connection.js

@@ -14,6 +14,7 @@
 // handlers.
 
 const { resolveDeviceConnection } = require('./resolve-connection');
+const { readSessionId } = require('./session-handle');
 const { daemonLogHint } = require('./session-log');
 const paths = require('./session-paths');
 const sessionClient = require('./session-client');
@@ -24,14 +25,19 @@ const sessionSpawn = require('./session-spawn');
 // { bridge, close }; close() releases this verb's hold — a no-op for the shared
 // daemon, a real transport teardown for a one-shot.
 //
-// `resolve` is an internal test seam only; verbs call acquireConnection with
-// just { device, projectRoot }.
+// `autostart` (default true: the daemon is the normal connection path) is the
+// daemon-vs-oneshot policy. cli.js's connectBridge passes false when no
+// workspace was discovered (#188), so a workspace-less cwd gets a one-shot
+// bridge and no mobile-automator/.session/ tree. `resolve` is an internal test
+// seam only; verbs call acquireConnection with just
+// { device, projectRoot, autostart }.
 async function acquireConnection({
   device = null,
   projectRoot = process.cwd(),
+  autostart = true,
   resolve = resolveDeviceConnection,
 } = {}) {
-  const { bridge, close } = await resolve({ device, projectRoot });
+  const { bridge, close } = await resolve({ device, projectRoot, autostart });
   return { bridge, close };
 }
 
@@ -55,7 +61,20 @@ function isSessionAlive(projectRoot, { client = sessionClient } = {}) {
 // 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) };
+  return {
+    ...status,
+    log_path: paths.logFilePath(projectRoot),
+    // Read from the handle, not from the ping reply. The handle is written once
+    // the daemon is listening and removed by stop(), so it is the same fact
+    // without a second protocol field that could disagree with it — and a verb
+    // that wants the id does not have to pay a socket round trip.
+    //
+    // Deliberately NOT symmetric with log_path, which survives running:false on
+    // purpose (a dead daemon's log is exactly what you want then). A SIGKILLed
+    // daemon leaves its handle behind, so reporting that id alongside
+    // running:false would name a session that no longer exists.
+    session_id: status && status.running ? readSessionId(projectRoot) : null,
+  };
 }
 
 // Spawn a daemon and wait until it answers. Resolves true on success.

package/src/device/crash-model.js

@@ -0,0 +1,110 @@
+'use strict';
+
+// Agnostic crash-report model, in the shape of device-model.js / element-model.js.
+//
+// It exists because the engine's payload is not mauto's contract. mobile-mcp's
+// mobile_list_crashes delegates to `mobilecli`, a separately-versioned Go binary
+// that reaches us TRANSITIVELY (through mobilewright) rather than as a pin in our
+// package.json, so its CrashReport struct is not something this repo can hold
+// still. Normalizing here means a key rename upstream costs one line in one
+// file instead of a silently-empty crash list at the call sites.
+//
+// The one thing this module never does is invent a field. An unreadable id or
+// time is `null`, and callers treat null-timed reports as UNATTRIBUTED rather
+// than assuming them recent or assuming them stale — see the "absent-versus-
+// empty problem" section of the slice-4 plan. An at-or-before-epoch time is
+// treated as unreadable too, not as a real, ancient instant: no device capable
+// of running mauto reports a crash at or before 1970-01-01T00:00:00Z, so a
+// decoded value that low is a zero-value sentinel (Go's unset int64, or its
+// zero-value time.Time) rather than a fact about the crash.
+
+// Plausible spellings for each field, most-likely first. A list rather than a
+// single key because "which spelling does mobilecli use this month" is exactly
+// the fact we refuse to depend on.
+const ID_KEYS = ['id', 'crashId', 'crash_id', 'reportId', 'name'];
+const PROCESS_KEYS = ['processName', 'process', 'packageName', 'bundleId', 'bundle_id', 'appId'];
+const TIME_KEYS = ['timestamp', 'time', 'date', 'createdAt', 'created_at'];
+
+function firstString(obj, keys) {
+  for (const k of keys) {
+    const v = obj[k];
+    if (typeof v === 'string' && v.trim() !== '') return v;
+  }
+  return null;
+}
+
+function firstValue(obj, keys) {
+  for (const k of keys) {
+    const v = obj[k];
+    if (v !== undefined && v !== null && v !== '') return v;
+  }
+  return null;
+}
+
+// Accepts a bare array, a { crashes: [...] } envelope, or the JSON text of
+// either — mobile-mcp stringifies its payload and parseToolResult's text
+// fallback can hand it to us unparsed.
+function toArray(raw) {
+  if (Array.isArray(raw)) return raw;
+  if (typeof raw === 'string') {
+    try {
+      return toArray(JSON.parse(raw));
+    } catch (_) {
+      return [];
+    }
+  }
+  if (raw && typeof raw === 'object') {
+    for (const k of ['crashes', 'reports', 'data', 'items']) {
+      if (Array.isArray(raw[k])) return raw[k];
+    }
+  }
+  return [];
+}
+
+function normalizeCrashes(raw) {
+  return toArray(raw)
+    .filter((c) => c && typeof c === 'object' && !Array.isArray(c))
+    .map((c) => ({
+      id: firstString(c, ID_KEYS),
+      process: firstString(c, PROCESS_KEYS),
+      timestamp: (() => {
+        const t = firstValue(c, TIME_KEYS);
+        return t == null ? null : String(t);
+      })(),
+    }));
+}
+
+// Epoch milliseconds for a normalized crash, or null when the time cannot be
+// read. Never <= 0 and never NaN. NaN compares false against every watermark,
+// so it would silently drop the report. An at-or-before-epoch value is not a
+// real crash instant either: no device capable of running mauto reports a
+// crash at or before 1970-01-01T00:00:00Z, so a decoded instant that low is a
+// zero-value sentinel wearing a timestamp's clothes, not a fact about the
+// crash — Go emits exactly this for an unset field (a zero int64, or
+// json.Marshal's `"0001-01-01T00:00:00Z"` for a zero-value time.Time). A floor
+// is used rather than a list of known sentinel spellings because the whole
+// reason this module normalizes instead of trusting keys is that we cannot
+// enumerate mobilecli's spellings; a new sentinel spelling defeats a list but
+// not a floor. Either failure mode is the confident wrong answer this slice
+// exists to prevent, so unreadable is reported as unreadable.
+function crashTimestampMs(crash) {
+  const t = crash && crash.timestamp;
+  if (t == null || t === '') return null;
+  if (typeof t === 'number' && Number.isFinite(t)) {
+    // Heuristic shared with every log tool: a 10-digit value is seconds.
+    const ms = t < 1e12 ? Math.round(t * 1000) : Math.round(t);
+    return ms > 0 ? ms : null;
+  }
+  const s = String(t).trim();
+  if (/^\d+$/.test(s)) {
+    const n = Number(s);
+    if (!Number.isFinite(n)) return null;
+    const ms = n < 1e12 ? n * 1000 : n;
+    return ms > 0 ? ms : null;
+  }
+  const parsed = Date.parse(s);
+  if (!Number.isFinite(parsed)) return null;
+  return parsed > 0 ? parsed : null;
+}
+
+module.exports = { normalizeCrashes, crashTimestampMs };

package/src/device/device-call.js

@@ -0,0 +1,145 @@
+'use strict';
+
+// One bounded, measured device call.
+//
+// Wraps the daemon's single injected `call` so that invoking a mobile-mcp
+// primitive is one thing with one contract — "it answers within timeoutMs, and
+// it leaves a trace either way" — instead of ninety lines inlined into a socket
+// data handler, where the device logic and the telemetry were interleaved at
+// nesting depth 6 and neither could be read on its own.
+//
+// Why this is ONE concept and not two. The obvious split (a timeout wrapper,
+// then an instrumentation wrapper around it) does not survive contact with the
+// events: `call.end` reports error_kind, and the only way to know a failure was
+// a timeout rather than a device error is `err.kind === 'timeout'` — a marker
+// this module itself invents on the timeout path. Split them and the outer
+// layer has to re-derive the inner layer's classification by sniffing an error
+// property, which is the same coupling with an extra seam in front of it. The
+// bound and the measurement are the same fact about a call.
+//
+// Built ONCE per daemon, right after createCall resolves, and then shared by
+// every connection. That is deliberate: the timeout, the sink and the
+// connection are all per-daemon, so nothing here needs a per-connection
+// identity. WARNING for anyone extending it: this means a `let` at factory
+// scope would be cross-connection shared state, mutated by concurrent calls
+// from unrelated sockets (the daemon multiplexes, and frames from two sockets
+// interleave freely). Everything mutable must stay inside `invoke`.
+//
+// Everything it needs is injected — no defaults — because every one of these
+// has a failure mode that is silent if it is wrong. See the construction-time
+// validation below.
+
+const { isKnownTool } = require('./mobile-mcp-tools');
+
+function makeDeviceCall(call, { scheduleTimeout, observe, timeoutMs, nextCallId } = {}) {
+  // Validate at CONSTRUCTION, loudly, rather than defaulting. A default here
+  // would be worse than a crash: with `timeoutMs` undefined,
+  // scheduleTimeout(undefined) is setTimeout(fn, undefined) is setTimeout(fn, 0),
+  // so EVERY device call would lose its race and fail with "... did not respond
+  // within undefinedms" — an entire session broken, in a way no test asserts
+  // against because every test injects its own scheduleTimeout. Failing at
+  // build time means the daemon never starts instead of starting useless.
+  if (typeof call !== 'function') throw new TypeError('makeDeviceCall requires a call function');
+  if (typeof observe !== 'function') throw new TypeError('makeDeviceCall requires an observe function');
+  if (typeof scheduleTimeout !== 'function') {
+    throw new TypeError('makeDeviceCall requires a scheduleTimeout function');
+  }
+  if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new TypeError('makeDeviceCall requires a finite positive timeoutMs');
+  }
+  // Injected rather than defaulted for the reason in the WARNING above: a
+  // counter kept at factory scope here would be cross-connection shared state
+  // living in the wrong module. The sequence belongs to the DAEMON LIFETIME,
+  // which is what the id is scoped to, so startDaemon owns it — and a default
+  // built here would silently work (the decorator is built once per daemon)
+  // right up until something builds two, at which point two live calls could
+  // share an id and the pairing would be wrong rather than merely absent.
+  if (typeof nextCallId !== 'function') {
+    throw new TypeError('makeDeviceCall requires a nextCallId function');
+  }
+
+  return async function invoke(tool, args) {
+    // NEVER record `tool` unchecked. The value arrives inside a socket frame
+    // and the daemon's socket is reachable by any process on the machine, while
+    // `tool` is sends:true in the event catalog on the grounds that it is an
+    // enumerated primitive name. Unknown values are omitted (makeEvent drops
+    // undefined), so the latency is still recorded — just anonymously.
+    const name = isKnownTool(tool) ? tool : undefined;
+    // Drawn ONCE, here, and stamped on both events. Drawing it twice would look
+    // like a start and an end belonging to two different calls, which is worse
+    // than carrying no id: the pairing would be wrong rather than absent.
+    const callId = nextCallId();
+    // Started BEFORE the call.start observe, so the sink's own cost (an
+    // appendFileSync) is inside the measurement rather than excluded from it.
+    // The number is meant to bound what the device took, from the daemon's
+    // point of view, not to flatter it.
+    const started = Date.now();
+    // debug: off at the default level, so a scenario pays ONE append per device
+    // call. Its value is bracketing — a daemon SIGKILLed mid-call leaves a
+    // call.start with no call.end, which is the only trace a call that never
+    // returned can possibly leave. That reading needs call_id: the daemon
+    // multiplexes and every call in a lifetime shares session_id, so without a
+    // per-call id "no matching call.end" is not a decidable question.
+    observe({ level: 'debug', event: 'call.start', tool: name, call_id: callId });
+    try {
+      // `call(...)` stays INSIDE the try. A `call` that throws synchronously —
+      // or returns a non-thenable, which makes `p.catch` a TypeError — would
+      // otherwise escape with no call.end recorded and no 'device'
+      // classification, i.e. the one failure shape whose trace matters most
+      // would be the one that leaves none.
+      const p = call(tool, args);
+      // Swallow the race loser's eventual settlement: once the timeout has won,
+      // the underlying call is still running (it is NOT cancellable) and its
+      // later rejection would surface as an unhandled rejection — which, in the
+      // daemon, is a process exit.
+      p.catch(() => {});
+      const result = await Promise.race([
+        p,
+        scheduleTimeout(timeoutMs).then(() => {
+          // The RAW `tool`, never the checked `name`: with an unknown tool
+          // `name` is undefined and the message would read "undefined: the
+          // mobile-mcp call did not respond ...", hiding which call hung at
+          // exactly the moment a human needs to know. This is safe precisely
+          // because it lands in `message`, which is sends:false in the event
+          // catalog and never leaves the machine.
+          const e = new Error(`${tool}: the mobile-mcp call did not respond within ${timeoutMs}ms`);
+          e.kind = 'timeout';
+          e.hint = 'the action may have partially executed on the device — verify state before retrying';
+          throw e;
+        }),
+      ]);
+      observe({
+        level: 'info',
+        event: 'call.end',
+        tool: name,
+        call_id: callId,
+        ok: true,
+        dur_ms: Date.now() - started,
+      });
+      return result;
+    } catch (err) {
+      observe({
+        // warn, not info. The daemon's stderr is a log file, not a terminal, so
+        // this costs a human no noise and lands next to the adb/simctl output
+        // that explains it.
+        level: 'warn',
+        event: 'call.end',
+        tool: name,
+        call_id: callId,
+        ok: false,
+        // The envelope's own taxonomy, reused verbatim: a non-timeout failure
+        // is exactly what client/deviceFail turns into kind 'device'.
+        error_kind: err && err.kind === 'timeout' ? 'timeout' : 'device',
+        dur_ms: Date.now() - started,
+        // sends:false — an engine message can embed element labels, typed text
+        // and filesystem paths. `err &&` because a caller can reject with a
+        // falsy value, and reading .message off null here would replace an
+        // ordinary failure with a TypeError.
+        message: err && (err.message || String(err)),
+      });
+      throw err;
+    }
+  };
+}
+
+module.exports = { makeDeviceCall };

package/src/device/failure-probe.js

@@ -0,0 +1,276 @@
+'use strict';
+
+// The failure-path crash check.
+//
+// Runs ONLY after an action has already failed, or after `mauto elements`
+// returned an empty list. Never after a successful action: a round trip on
+// every `mauto tap` would put a device call on the hot path, whereas checking
+// after a failure costs nothing in the common case and answers the exact
+// question that is otherwise unanswerable — "did the app die, or did the button
+// move?".
+//
+// THE CONTRACT (see the slice-4 plan's "absent-versus-empty problem"): three
+// states, not two.
+//
+//   crashes: [ … ]   we asked and the device reported crashes
+//   crashes: []      we asked and the device reported none  — a POSITIVE claim
+//   (no key)         we could not ask, or could not attribute — UNKNOWN
+//
+// Emitting `[]` when the probe failed, timed out or had no watermark would be
+// this slice's own bug with the sign flipped: the tool would confidently tell
+// the agent the app is fine when it has no idea. So the probe attaches a key it
+// earned, or attaches nothing at all.
+//
+// It is TOTAL. It never throws, never rejects, and never alters ok, error or
+// schema_version. An observability failure must not rewrite the caller's error.
+//
+// SIGNATURE, and why it differs from the plan's own "Interfaces" prose: that
+// prose sketched probeCrashes deriving the watermark internally (via
+// readHandle(projectRoot)), but its own test file passes `watermark` and
+// `sinks` explicitly and sets `projectRoot` to the nonexistent path '/nope'.
+// The tests are the contract: this module takes `watermark` as a plain value
+// and never touches the filesystem itself, which is what makes it a pure,
+// synchronously-testable function. `src/cli.js` already owns a
+// `sessionWatermark(projectRoot)` helper (added with the `crash` verb, reusing
+// the same `readHandle`-backed logic `handleCrashList` needs) — connectBridge
+// calls that and passes the result in, rather than this module growing a second
+// copy of "how do we find the session start time".
+//
+// ENVELOPE SHAPE ON FAILURE: attaching `data.crashes` to a `fail()` envelope is
+// not a new envelope shape. `src/output/envelope.js`'s `fail(kind, message,
+// hint, data)` has taken an optional trailing `data` since before this slice
+// (used by `init --agent all`'s per-host ok/failed map) — `data` is included
+// only when given, so the common fail shape is unchanged for every verb that
+// doesn't pass one. No lint guard or schema asserts a fixed key set for a
+// failure envelope (checked: no envelope-shape guard exists in tests/lint or
+// tests/unit). This module uses that existing extension point rather than
+// inventing one.
+//
+// THE ok:true / EMPTY-`elements` ASYMMETRY IS INTENTIONAL, AND DELIBERATELY NOT
+// SILENT. On failure, `data` is an object (or absent) and gaining a `crashes`
+// key is additive. On the `elements` ok:true path `data` IS the elements array
+// — the verb's whole contract — so grafting a `crashes` key onto it would
+// corrupt that contract for every consumer expecting `data` to stay an array.
+// So on that path the result reaches the caller ONLY as a hint, on BOTH
+// determined outcomes (crash found, or confirmed clear) — not only when a
+// crash is found. Signalling only the "found" case would make an earned-clear
+// probe look identical to a probe that never ran, which is exactly the
+// UNKNOWN state this module exists to keep distinct from EARNED-EMPTY. Only
+// the genuinely undetermined case (skipped, failed, timed out, unscoped)
+// leaves the envelope untouched.
+
+const { crashTimestampMs } = require('./crash-model');
+const { record } = require('../observe/recorder');
+
+// The probe's own budget, deliberately far below the daemon's per-call timeout
+// (session-daemon.js's DAEMON_CALL_TIMEOUT_MS, 25s). Inheriting that would add
+// up to 25 seconds to a verb that has ALREADY failed, for a courtesy lookup the
+// caller did not ask for.
+const CRASH_PROBE_TIMEOUT_MS = 3000;
+
+// `mauto devices` returns a bare array through the same connectBridge seam, so
+// the empty-list trigger would fire on "nothing connected" and then try to
+// probe a device that does not exist.
+//
+// `crash` is exempt for the same reason, sharper: it is ITSELF the
+// crash-diagnostic tool. A failing `crash get <id>` (bad id, unreadable
+// report — kind `device` either way) would otherwise re-run `listCrashes()`
+// behind its back and staple a second, unrelated crash-probe hint onto the
+// error, e.g. "The app under test crashed... run `mauto crash get c1`"
+// alongside "the device engine could not read crash reports" for the SAME
+// envelope — self-contradictory, and pointing at a different id than the one
+// the caller asked about. The probe exists to answer a question other verbs
+// can't; `crash` can already answer it directly.
+const PROBE_EXEMPT_VERBS = new Set(['devices', 'crash']);
+
+// Failure kinds that can plausibly mean "the app died". invalid_input is a bad
+// flag, target_not_found/environment/internal never reached (or never
+// involved) the device — none of them are worth a device round trip.
+const PROBE_KINDS = new Set(['device', 'timeout']);
+
+function shouldProbe({ envelope, verb } = {}) {
+  if (!envelope || typeof envelope !== 'object') return false;
+  if (PROBE_EXEMPT_VERBS.has(verb)) return false;
+  if (envelope.ok === false) {
+    return PROBE_KINDS.has(envelope.error && envelope.error.kind);
+  }
+  // The silent symptom: the app is gone, so the view hierarchy is empty and the
+  // verb still succeeds. Named by verb rather than by shape — relying on "only
+  // `elements` returns a bare array" would be relying on an accident.
+  return verb === 'elements' && Array.isArray(envelope.data) && envelope.data.length === 0;
+}
+
+function crashHint(crashes) {
+  const process = crashes[0] && crashes[0].process;
+  const who = process ? ` (${process})` : '';
+  const id = crashes[0] && crashes[0].id;
+  const how = id ? ` Run \`mauto crash get ${id}\` for the report.` : ' Run `mauto crash list`.';
+  return `The app under test crashed during this session${who}: ${crashes.length} crash report(s).${how}`;
+}
+
+// The confirmatory half of the three-state contract on the ok:true path, where
+// there is no `data` slot to carry an earned-empty result.
+const NO_CRASH_HINT =
+  'Checked for an app crash since the session started: none found — the empty result looks genuine.';
+
+// A report whose own timestamp is missing or unparseable (crashTimestampMs
+// returns null — see crash-model.js's epoch floor for why a zero-value
+// sentinel counts as unreadable too) is neither included nor silently
+// dropped: it is `unattributed`, matching handleCrashList's vocabulary in
+// src/cli.js. Attaching an earned-empty `crashes: []` here instead would be
+// this slice's own confident-wrong-answer bug, just moved from "found none"
+// to "found something I couldn't place in time".
+function unattributedHint(count) {
+  return `Checked for an app crash since the session started: the device returned ${count} report(s) with an unreadable timestamp — not counted as clear. Run \`mauto crash list\` to inspect them.`;
+}
+
+function amendHint(envelope, note) {
+  envelope.hint = envelope.hint ? `${note} ${envelope.hint}` : note;
+}
+
+// Shared sentinel so a caller racing withDeadline() can tell "the deadline won"
+// apart from "the bridge resolved with this exact value" — a module-level
+// constant rather than a fresh Symbol() per call, so the identity check below
+// actually matches.
+const TIMED_OUT = Symbol('mauto.probe.timeout');
+
+// Race a promise against a deadline. The timer is deliberately left REF'D
+// (not unref()'d): the promise on the other side of this race is, by
+// definition, a HUNG bridge call that will never settle on its own — that is
+// the exact case this deadline exists to catch. If the timer were unref'd and
+// nothing else happened to be keeping the event loop alive (a one-shot verb
+// whose connectBridge socket handling has already torn down, say), Node would
+// consider the loop empty and exit *before the timer ever fires*: the race
+// never settles, probeCrashes never resolves, connectBridge's `await
+// probeCrashes(...)` never returns, and the CLI exits 0 with no output —
+// silently swallowing the very device failure this module exists to surface.
+// That is strictly worse than never having built this deadline. Keeping the
+// timer ref'd costs nothing it was trying to save: the `.finally(() =>
+// clearTimeout(timer))` below already guarantees the timer cannot outlive the
+// race on either branch, which is the actual guarantee "don't leave a live
+// timer behind" was after.
+function withDeadline(promise, ms) {
+  let timer;
+  const deadline = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(TIMED_OUT), ms);
+  });
+  return Promise.race([promise, deadline]).finally(() => clearTimeout(timer));
+}
+
+async function probeCrashes({
+  bridge,
+  envelope,
+  verb,
+  projectRoot,
+  env = process.env,
+  watermark,
+  sinks,
+  timeoutMs = CRASH_PROBE_TIMEOUT_MS,
+} = {}) {
+  const recordOpts = { projectRoot, env, sinks };
+  try {
+    if (!bridge || typeof bridge.listCrashes !== 'function') return;
+    if (!shouldProbe({ envelope, verb })) return;
+
+    if (watermark == null) {
+      // No session handle (or a caller that passed none) means nothing to
+      // attribute against. An iOS DiagnosticReports file from last Tuesday is
+      // not evidence about this step, so say nothing rather than say something
+      // wrong.
+      record({ level: 'debug', src: 'cli', event: 'crash.probe_unscoped', verb }, recordOpts);
+      return;
+    }
+    const sinceMs = Date.parse(watermark);
+
+    let raw;
+    try {
+      raw = await withDeadline(
+        Promise.resolve().then(() => bridge.listCrashes()),
+        timeoutMs
+      );
+    } catch (err) {
+      record(
+        {
+          level: 'warn',
+          src: 'cli',
+          event: 'crash.probe_failed',
+          verb,
+          message: (err && err.message) || String(err),
+        },
+        recordOpts
+      );
+      return;
+    }
+    if (raw === TIMED_OUT) {
+      record({ level: 'warn', src: 'cli', event: 'crash.probe_timeout', verb, dur_ms: timeoutMs }, recordOpts);
+      return;
+    }
+
+    const crashes = [];
+    let unattributed = 0;
+    for (const c of Array.isArray(raw) ? raw : []) {
+      const ms = crashTimestampMs(c);
+      if (ms == null) unattributed += 1;
+      else if (Number.isFinite(sinceMs) && ms >= sinceMs) crashes.push(c);
+    }
+
+    record(
+      {
+        level: crashes.length > 0 ? 'warn' : 'info',
+        src: 'cli',
+        event: crashes.length > 0 ? 'crash.detected' : 'crash.probe_clear',
+        verb,
+        crash_count: Number.isFinite(crashes.length) ? crashes.length : undefined,
+        // app_id and message are sends:false — a crashed process name is an
+        // unreleased product name and a stack excerpt is free text.
+        app_id: (crashes[0] && crashes[0].process) || undefined,
+      },
+      recordOpts
+    );
+
+    if (envelope.ok === false) {
+      // EARNED result: we asked, the device answered, we attribute the answer.
+      // See the module comment above for why this key is safe to add.
+      // `unattributed` rides alongside `crashes` unconditionally (0 included)
+      // so "genuinely clean" and "device returned something unplaceable in
+      // time" are always distinguishable, never just when the count is > 0.
+      envelope.data = { ...(envelope.data || {}), crashes, unattributed };
+      if (crashes.length > 0) amendHint(envelope, crashHint(crashes));
+      else if (unattributed > 0) amendHint(envelope, unattributedHint(unattributed));
+    } else {
+      // ok:true only happens for the empty-`elements` trigger. `data` stays the
+      // elements array untouched; the result is prose-only, on ALL THREE
+      // determined outcomes (crash found, unattributed report found, confirmed
+      // clear). See the module comment above.
+      if (crashes.length > 0) amendHint(envelope, crashHint(crashes));
+      else if (unattributed > 0) amendHint(envelope, unattributedHint(unattributed));
+      else amendHint(envelope, NO_CRASH_HINT);
+    }
+  } catch (err) {
+    // Total by construction. A broken probe must never turn "tap failed:
+    // element not found" into "tap failed AND crash probing is broken" — that
+    // buries the error the caller actually needs.
+    try {
+      record(
+        {
+          level: 'warn',
+          src: 'cli',
+          event: 'crash.probe_failed',
+          verb,
+          message: (err && err.message) || String(err),
+        },
+        recordOpts
+      );
+    } catch (_) {
+      /* record() is already total; this is belt and suspenders */
+    }
+  }
+}
+
+module.exports = {
+  probeCrashes,
+  shouldProbe,
+  CRASH_PROBE_TIMEOUT_MS,
+  PROBE_EXEMPT_VERBS,
+  PROBE_KINDS,
+};