mobile-automator 0.24.0 → 0.26.0

package/src/observe/trace.js

@@ -0,0 +1,174 @@
+'use strict';
+
+// The READ side of a run trace: turn the NDJSON a run left behind into the
+// handful of facts `result finalize` is allowed to state as measured.
+//
+// Deliberately separate from the sink that writes it, because the two have
+// opposite constraints. Writing happens on every verb and must be as close to
+// free as an append can be. Reading happens once, in finalize, and can afford
+// to parse the whole file. Nothing here is ever called on the hot path — which
+// is also why the directory prune lives here rather than in the sink.
+
+const realFs = require('fs');
+const path = require('path');
+
+const { atCap } = require('./sinks/file');
+const { logsDir, runTracePath, RUN_TRACE_PREFIX } = require('./paths');
+
+// A device failure in the envelope's own taxonomy. `deviceFail` (src/cli.js) is
+// the ONLY producer of these two kinds, so counting them needs no list of which
+// verbs are device verbs — a list that would have to be maintained by hand
+// alongside connectBridge and would be wrong the first time someone forgot.
+const DEVICE_FAILURE_KINDS = new Set(['device', 'timeout']);
+
+// How many run traces .logs/ keeps. See the plan's bounded-measurement analysis:
+// a trace is capped individually, but the DIRECTORY is one file per run forever.
+const KEEP_RUN_TRACES = 20;
+
+// Parse NDJSON leniently. A trailing partial line is NORMAL, not corruption: a
+// SIGKILLed process can be interrupted mid-append, and the trace of a run that
+// died is the trace most worth reading. Unparseable lines are skipped.
+function parseTrace(text) {
+  const events = [];
+  for (const line of String(text).split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const e = JSON.parse(line);
+      if (e && typeof e === 'object') events.push(e);
+    } catch (_) {
+      /* partial or corrupt line; the rest of the trace is still evidence */
+    }
+  }
+  return events;
+}
+
+function readTrace(tracePath, { fs = realFs } = {}) {
+  if (!tracePath) return null;
+  let text;
+  try {
+    text = fs.readFileSync(tracePath, 'utf8');
+  } catch (_) {
+    // No trace for this run: an ordinary, expected state (MAUTO_RUN_ID unset,
+    // logging silenced, no workspace, or an id that could not name a file).
+    return null;
+  }
+  return { events: parseTrace(text), truncated: atCap(tracePath, { fs }) };
+}
+
+function millis(event) {
+  const t = event && event.ts ? Date.parse(event.ts) : NaN;
+  return Number.isFinite(t) ? t : null;
+}
+
+// The facts a trace can PROVE, and deliberately nothing else.
+//
+// Absent by design: per-step attempt counts. The design asks for "retry counts
+// … counted from repeated verb events against the same target", and the trace
+// has no target — `--at 100,250` is not a recorded field and must not become
+// one, because coordinates and element labels are exactly the free text the
+// redaction catalog exists to keep off the wire. Step boundaries could be
+// inferred from where the `result add-step` events fall, but that is only sound
+// if the agent records each step immediately after performing it; an agent that
+// batches its add-step calls at the end would file every device call under step
+// one. Silently mis-attributing retries is the same confident wrongness this
+// slice exists to remove.
+//
+// So this counts what needs no inference — run-wide device failures, each of
+// which is an attempt that did not take. finalize COMPARES that against what
+// the agent said rather than overwriting the per-step numbers.
+function deriveRun(trace) {
+  if (!trace || !Array.isArray(trace.events) || trace.events.length === 0) return null;
+
+  const truncated = Boolean(trace.truncated);
+  const device_failures = trace.events.filter(
+    (e) => e.event === 'verb.end' && e.ok === false && DEVICE_FAILURE_KINDS.has(e.error_kind)
+  ).length;
+  const failure_screenshots = trace.events
+    .filter((e) => e.event === 'screenshot.on_failure' && typeof e.path === 'string')
+    .map((e) => e.path);
+
+  // reduce, not Math.min(...stamps): a 1 MiB trace is a few thousand lines
+  // today, but spreading an array into a call is an argument-count limit
+  // waiting to be hit by a future, larger cap.
+  let first = null;
+  let last = null;
+  for (const event of trace.events) {
+    const t = millis(event);
+    if (t === null) continue;
+    if (first === null || t < first) first = t;
+    if (last === null || t > last) last = t;
+  }
+
+  // Two stamps or nothing. A single-event trace spans zero time, and writing 0
+  // down as a MEASURED duration would be a confident lie where "we did not
+  // measure" is the truth — finalize falls back to the reported value.
+  const measurable = first !== null && last !== null && last > first;
+
+  return {
+    // Milliseconds to seconds: the trace's resolution is 1ms, and rounding to
+    // whole seconds would report every fast run as 0.
+    duration_seconds: measurable ? (last - first) / 1000 : null,
+    trace_events: trace.events.length,
+    device_failures,
+    trace_truncated: truncated,
+    failure_screenshots,
+  };
+}
+
+// Keep the `keep` most recent run traces; delete the rest.
+//
+// Called at finalize and NOWHERE else. Off the hot path — a readdir per
+// `mauto tap` would put directory scanning inside the tightest loop the tool
+// has — and finalize is the only moment a run is known to be over. Keying the
+// prune on OTHER runs' traces also handles the crashed-run case: a run that
+// never finalized leaves an orphan, which is simply an older file the next
+// successful finalize sweeps up.
+//
+// The trace of the run being finalized is always excluded. Deleting it there is
+// the one option that is clearly wrong: it is the evidence behind every number
+// finalize just wrote, destroyed at exactly the moment someone starts asking
+// where duration_seconds came from.
+//
+// Deletion is confined to `run-*.ndjson` in the resolved logs dir — files this
+// tool created, under a name it owns. Best-effort throughout: pruning a log
+// directory must never be the reason a finalize fails.
+function pruneRunTraces(projectRoot, { keep = KEEP_RUN_TRACES, except, env = process.env, fs = realFs } = {}) {
+  try {
+    const dir = logsDir(projectRoot, env);
+    const exceptPath = except ? runTracePath(projectRoot, except, env) : null;
+    const exceptName = exceptPath ? path.basename(exceptPath) : null;
+
+    const traces = fs
+      .readdirSync(dir)
+      .filter((n) => n.startsWith(RUN_TRACE_PREFIX) && n.endsWith('.ndjson') && n !== exceptName)
+      .map((name) => {
+        const full = path.join(dir, name);
+        let mtime = 0;
+        try {
+          mtime = fs.statSync(full).mtimeMs;
+        } catch (_) {
+          /* raced with another process; treat as oldest */
+        }
+        return { full, mtime };
+      })
+      .sort((a, b) => b.mtime - a.mtime);
+
+    // keep - 1: the run being finalized is excluded from `traces` above and
+    // occupies one of the retained slots.
+    let removed = 0;
+    for (const trace of traces.slice(Math.max(0, keep - 1))) {
+      try {
+        fs.unlinkSync(trace.full);
+        removed += 1;
+      } catch (_) {
+        /* raced, or already gone */
+      }
+    }
+    return removed;
+  } catch (_) {
+    // No .logs/ yet, or an unreadable directory. Pruning is never load-bearing.
+    return 0;
+  }
+}
+
+module.exports = { readTrace, deriveRun, pruneRunTraces, KEEP_RUN_TRACES, DEVICE_FAILURE_KINDS };

package/src/observe/transport.js

@@ -0,0 +1,169 @@
+'use strict';
+
+// The ONE network path in the shipped tree. tests/lint/telemetry-transport-
+// isolation.test.js fails the build if a second one appears anywhere in src/
+// or bin/, because the privacy contract ("telemetryPayload() is the only thing
+// that builds a network payload") is only true while there is only one wire.
+//
+// PostHog's documented plain-HTTP capture API, no SDK. An SDK would cost
+// cold-start time on every one of the dozens of process spawns a scenario
+// makes, and would add supply-chain surface to a project already carrying
+// high-severity advisories (#161). The whole transport is one JSON body.
+//
+// This module RESHAPES a spool line into PostHog's envelope. It never adds a
+// fact: everything in `properties` came out of telemetryPayload(), which
+// iterates the field catalog rather than the event.
+
+// EU cloud by default. No user content reaches the wire at all (the catalog
+// guarantees that), but app package names are the sensitive class this design
+// is shaped around, so the region is a cheap belt on top of the braces.
+const DEFAULT_HOST = 'https://eu.i.posthog.com';
+
+// A PostHog project API key is WRITE-ONLY and public by design — it authorises
+// capture and nothing else, and PostHog embeds it in the <script> tag of every
+// site that uses them. Shipping it is therefore correct; fetching it at flush
+// time would mean a network round trip before the network round trip, a server
+// we must keep alive forever, and no actual protection (anyone can read it out
+// of `npm pack`). See "Why the project token ships in the package" in
+// docs/plans/2026-09-05-observability-slice-5-plan.md.
+//
+// Until a maintainer pastes the real value, hasToken() is false and telemetry
+// resolves DISABLED with reason `no_token`. A fork or a mid-slice build can
+// therefore never post, even with telemetry.enabled true in its config.
+const TOKEN_PLACEHOLDER = 'phc_REPLACE_ME';
+const PROJECT_TOKEN = 'phc_xD3rE7kJ76yIcVgBKfkarm6cXiNaiEEbSL8q4R5rpBi';
+
+// One event has one identity and no person. distinct_id is a constant and
+// $process_person_profile is false, so PostHog creates no person profile at
+// all: aggregate verb counts and error rates still work, and there is no
+// stable per-machine identifier anywhere in the system to correlate on.
+const ANON_DISTINCT_ID = 'mauto-anonymous';
+
+// A hung POST must never pin the daemon or delay its idle reap.
+const POST_TIMEOUT_MS = 5000;
+
+// Keys that become top-level wire fields rather than properties, so they are
+// not sent twice under two names.
+const WIRE_KEYS = ['event', 'ts', 'msg_id'];
+
+function resolveToken(env = process.env) {
+  return (env && env.MAUTO_TELEMETRY_TOKEN) || PROJECT_TOKEN;
+}
+
+function hasToken(env = process.env) {
+  const t = resolveToken(env);
+  return Boolean(t) && t !== TOKEN_PLACEHOLDER;
+}
+
+function endpointUrl(env = process.env) {
+  const host = ((env && env.MAUTO_TELEMETRY_HOST) || DEFAULT_HOST).replace(/\/+$/, '');
+  return `${host}/batch/`;
+}
+
+function toWireEvent(payload) {
+  const properties = { distinct_id: ANON_DISTINCT_ID, $process_person_profile: false };
+  for (const [k, v] of Object.entries(payload)) {
+    if (WIRE_KEYS.includes(k)) continue;
+    properties[k] = v;
+  }
+  return {
+    event: payload.event,
+    timestamp: payload.ts,
+    uuid: payload.msg_id,
+    properties,
+  };
+}
+
+// Bounds a promise with a deadline without ever leaving a live timer behind.
+// The timer is deliberately left REF'D (not unref()'d): src/device/
+// failure-probe.js shipped the unref'd version of exactly this and it was a
+// real bug — an unref'd timer never fires when nothing else is keeping the
+// event loop alive (a one-shot verb, or the daemon between device calls), so
+// the race never settles and the caller hangs forever waiting on a deadline
+// that was never going to arrive. Keeping it ref'd costs nothing the unref
+// was trying to save: the `finally` 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. The AbortController is passed to
+// fetch as a cooperative cancel; the race is the actual bound, so a fetchImpl
+// that ignores the signal still cannot hang the caller.
+async function withDeadline(promise, ms, controller) {
+  let timer;
+  const deadline = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      resolve({ timedOut: true });
+    }, ms);
+  });
+  try {
+    return await Promise.race([promise.then((response) => ({ response })), deadline]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Resolves — never rejects. `retry` distinguishes "try this batch again later"
+// from "this batch will never succeed":
+//
+//   4xx except 429  permanent. A malformed body or a revoked token would
+//                   otherwise retry forever and the spool would never drain.
+//   429, 5xx, throw retryable. Rate limiting, an outage, DNS, a captive portal.
+//   timeout         retryable. Indistinguishable from a slow network from here.
+async function postBatch(payloads, { fetchImpl, env = process.env, timeoutMs = POST_TIMEOUT_MS } = {}) {
+  if (!Array.isArray(payloads) || payloads.length === 0) return { ok: true, retry: false, status: 0 };
+
+  // telemetryPayload() drops a value that fails its accepts() check, so a
+  // payload can arrive here with no `event` (an unrecognised event name was
+  // dropped). Posting that fragment under an invented event name would be
+  // worse than dropping it; skip it instead of pretending it is a real event.
+  const usable = payloads.filter((p) => p && p.event);
+  if (usable.length === 0) return { ok: true, retry: false, status: 0 };
+
+  if (!hasToken(env)) return { ok: false, retry: false, status: 0 };
+
+  const doFetch = fetchImpl === undefined ? globalThis.fetch : fetchImpl;
+  // Node 18 has global fetch; a stripped or exotic runtime might not. Not
+  // having a transport is a permanent condition for this process, not a
+  // retryable one, so the batch is dropped rather than accumulated forever.
+  if (typeof doFetch !== 'function') return { ok: false, retry: false, status: 0 };
+
+  const body = JSON.stringify({
+    api_key: resolveToken(env),
+    batch: usable.map(toWireEvent),
+  });
+
+  const controller = new AbortController();
+  try {
+    const outcome = await withDeadline(
+      doFetch(endpointUrl(env), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+        signal: controller.signal,
+      }),
+      timeoutMs,
+      controller,
+    );
+
+    if (outcome.timedOut) return { ok: false, retry: true, status: 0 };
+
+    const status = outcome.response.status;
+    if (status >= 200 && status < 300) return { ok: true, retry: false, status };
+    if (status === 429 || status >= 500) return { ok: false, retry: true, status };
+    return { ok: false, retry: false, status };
+  } catch (_) {
+    // Network-level: DNS, TLS, abort/timeout, captive portal. All retryable,
+    // and none of them is ever allowed to escape into the caller.
+    return { ok: false, retry: true, status: 0 };
+  }
+}
+
+module.exports = {
+  DEFAULT_HOST,
+  TOKEN_PLACEHOLDER,
+  POST_TIMEOUT_MS,
+  ANON_DISTINCT_ID,
+  resolveToken,
+  hasToken,
+  endpointUrl,
+  postBatch,
+};

package/src/observe/vocab.js

@@ -0,0 +1,96 @@
+'use strict';
+
+// The closed vocabularies telemetry's `oneOf` checks are built from
+// (src/observe/accepts.js, applied at the wire by telemetryPayload).
+//
+// Hard-coded rather than derived from the code that produces the values, on
+// purpose: derived-at-load would make the check agree with whatever the code
+// does, including a bug that records caller text. tests/lint/telemetry-vocab-drift.test.js
+// pins each list to its producer in BOTH directions instead, so a new event,
+// verb or reason is noticed rather than silently dropped from telemetry.
+//
+// Arrays are frozen: the entries are ordinary indexed properties, so the freeze
+// is real (unlike a frozen Set — see src/device/mobile-mcp-tools.js).
+
+const os = require('os');
+
+const OS_NAMES = Object.freeze([
+  'aix',
+  'darwin',
+  'freebsd',
+  'linux',
+  'openbsd',
+  'sunos',
+  'win32',
+  'android',
+]);
+
+// Every `event:` name the source records. Pinned by the drift guard.
+const EVENT_NAMES = Object.freeze([
+  'verb.end',
+  'call.start',
+  'call.end',
+  'screenshot.on_failure',
+  'screenshot.capture_failed',
+  'crash.list',
+  'crash.detected',
+  'crash.probe_clear',
+  'crash.probe_unscoped',
+  'crash.probe_failed',
+  'crash.probe_timeout',
+  'daemon.start',
+  'daemon.stop',
+  'daemon.start_failure',
+  'daemon.listen_failure',
+  'daemon.connect_failure',
+  'daemon.lock_conflict',
+  'daemon.undeliverable',
+  // Emitted by the flush path, which lands in a later slice-5 task; declared
+  // now because its event shape is already exercised by unit tests.
+  'telemetry.flush',
+]);
+
+// The values cli.js's preAction hook can record as `verb`: the TOP-LEVEL
+// command commander resolved (`config get` records `config`). Commander's
+// implicit `help` command, `--help` and `-V` run no preAction hook, so they
+// record no verb at all and are deliberately absent.
+const VERB_NAMES = Object.freeze([
+  'elements',
+  'screenshot',
+  'validate',
+  'tap',
+  'type',
+  'swipe',
+  'press',
+  'long-press',
+  'double-tap',
+  'launch',
+  'install',
+  'uninstall',
+  'open-url',
+  'orientation',
+  'assert',
+  'result',
+  'setup',
+  'config',
+  'guide',
+  'schema',
+  'bootstrap',
+  'memory',
+  'init',
+  'session',
+  'devices',
+  'crash',
+  'mcp',
+  'telemetry',
+]);
+
+// Why the daemon stopped. 'crash' is documented but not yet produced.
+const STOP_REASONS = Object.freeze(['idle', 'signal', 'shutdown', 'crash', 'explicit']);
+
+// Node/libuv errno names for this platform, plus our own ELOCKED (a lock
+// conflict, recorded by src/device/session-daemon.js). Names only: the numeric codes an MCP
+// server reports are not in this set and so never pass.
+const ERROR_CODES = Object.freeze([...Object.keys(os.constants.errno), 'ELOCKED']);
+
+module.exports = { OS_NAMES, EVENT_NAMES, VERB_NAMES, STOP_REASONS, ERROR_CODES };

package/src/output/envelope.js

@@ -36,6 +36,11 @@ const KIND_TO_CODE = {
   partial: 1,
 };
 
+// The closed set of error.kind values. Single source: src/observe/event.js
+// validates the telemetry `error_kind` field against exactly this list, so a
+// new kind added to KIND_TO_CODE is accepted there without a second edit.
+const ERROR_KINDS = Object.freeze(Object.keys(KIND_TO_CODE));
+
 function ok(data, hint = null) {
   const env = { ok: true, data, schema_version: SCHEMA_VERSION };
   // A success can still carry an advisory hint (e.g. recovered corruption).
@@ -99,6 +104,7 @@ function render(envelope, { human = false } = {}) {
 module.exports = {
   SCHEMA_VERSION,
   EXIT,
+  ERROR_KINDS,
   ok,
   fail,
   exitCodeFor,

package/src/result/capability-catalog.js

@@ -92,6 +92,11 @@ const RESULT_CAPABILITIES = {
   },
   duration: {
     verb: 'finalize',
+    // --duration is now the REPORTED value, not the recorded one. When a run
+    // trace exists, finalize writes the measured duration to duration_seconds
+    // and keeps this flag's value in measurements.reported_duration_seconds,
+    // flagging a disagreement rather than silently discarding either number.
+    // The store's write site is unchanged — the caller derives the value.
     flags: ['--duration'],
     store: 'finalize',
     writes: 'duration_seconds: Number(durationSeconds) || 0',
@@ -114,6 +119,14 @@ const RESULT_CAPABILITIES = {
     writeCheck: 'behavioral',
     schemaPointer: '/properties/summary',
   },
+  crash_record: {
+    verb: 'add-crash',
+    flags: ['--crash-id', '--process', '--crash-timestamp', '--excerpt', '--report-path'],
+    store: 'addCrash',
+    writes: 'this._crashes.push(entry)',
+    writeCheck: 'substring',
+    schemaPointer: '/properties/crashes',
+  },
 };
 
 // Flags that identify WHICH run/step is being recorded, rather than carrying
@@ -139,6 +152,7 @@ const NO_FLAG_ALLOWLIST = {
   total_assertions: 'derived by ResultStore.finalize by counting assertion_results; no independent flag by design',
   passed_assertions: 'derived by ResultStore.finalize by counting assertion_results; no independent flag by design',
   failed_assertions: 'derived by ResultStore.finalize by counting assertion_results; no independent flag by design',
+  measurements: 'derived by ResultStore.finalize from the run trace (src/observe/trace.js); deliberately has NO flag — an agent-supplied measurement is precisely the self-report this field exists to replace',
 };
 
 module.exports = { RESULT_CAPABILITIES, IDENTITY_FLAGS, NO_FLAG_ALLOWLIST };

package/src/result/store.js

@@ -17,6 +17,11 @@ const { OBSERVATION_TYPES } = require('./flags');
 
 const SCHEMA_VERSION = '2.0';
 
+// A crash report is read into an agent's context and routinely committed to a
+// repo. A native tombstone is tens of kilobytes, so the excerpt is bounded HERE
+// rather than trusted from the caller — the full report's home is report_path.
+const MAX_CRASH_EXCERPT = 2000;
+
 function defaultMetadata(overrides = {}) {
   return {
     app_version: overrides.app_version || 'unknown',
@@ -77,6 +82,7 @@ class ResultStore {
     this._assertions = loaded.assertion_results || [];
     this._observations = loaded.observations || [];
     this._capturedVariables = loaded.captured_variables || {};
+    this._crashes = loaded.crashes || [];
     if (!this.scenarioId && loaded.scenario_id) this.scenarioId = loaded.scenario_id;
   }
 
@@ -151,6 +157,7 @@ class ResultStore {
       assertion_results: this._assertions,
       observations: this._observations,
       captured_variables: this._capturedVariables,
+      crashes: this._crashes,
       _in_progress: true,
     };
     this._atomicWrite(JSON.stringify(snapshot, null, 2));
@@ -228,6 +235,29 @@ class ResultStore {
     });
   }
 
+  addCrash({ crash_id, process = null, timestamp = null, step_id = null, excerpt = null, report_path = null } = {}) {
+    return withLock(this._lock, () => {
+      this._refreshFromDisk();
+      if (!crash_id || String(crash_id).trim() === '') {
+        // Without an id the full report is unreachable, which makes the record
+        // a claim nobody can check.
+        throw new Error('addCrash requires a crash_id');
+      }
+      const entry = {
+        crash_id: String(crash_id),
+        process: process == null ? null : String(process),
+        timestamp: timestamp == null ? null : String(timestamp),
+        detected_at: new Date().toISOString(),
+        step_id: step_id == null ? null : String(step_id),
+        excerpt: excerpt == null ? null : String(excerpt).slice(0, MAX_CRASH_EXCERPT),
+        report_path: report_path == null ? null : String(report_path),
+      };
+      this._crashes.push(entry);
+      this._persistInProgress();
+      return entry;
+    });
+  }
+
   captureVariable(name, value) {
     return withLock(this._lock, () => {
       this._refreshFromDisk();
@@ -236,9 +266,66 @@ class ResultStore {
     });
   }
 
-  finalize({ status, durationSeconds = 0, summary, metadata } = {}) {
+  // Typed observations derived from the measurement.
+  //
+  // They go in the observations array as well as in `measurements` because
+  // src/memory/store.js harvests observations into run-history: a scenario
+  // whose reported durations are chronically wrong, or whose steps claim no
+  // retries while the device kept failing, is a CROSS-RUN fact, and
+  // `measurements` is only ever read one file at a time.
+  //
+  // `state_context` for the duration case rather than a new observation type:
+  // extending the enum would mean changing OBSERVATION_TYPES and the schema
+  // together for a fact the existing vocabulary already describes — the agent's
+  // model of the run disagreed with the machine's.
+  _measurementObservations(measurements, measuredSeconds) {
+    const notes = [];
+    if (!measurements) return notes;
+
+    if (measurements.duration_disagreement) {
+      notes.push({
+        type: 'state_context',
+        step_id: null,
+        message:
+          `Reported duration ${measurements.reported_duration_seconds}s disagrees with ` +
+          `${measuredSeconds}s measured from the run trace; the measured value was recorded.`,
+      });
+    }
+
+    // Provable under-report: the device failed, and not one step admits to a
+    // retry. `_steps.length > 0` because `every` on an empty array is true, and
+    // a run with no steps has nothing to under-report.
+    if (
+      measurements.device_failures > 0 &&
+      this._steps.length > 0 &&
+      this._steps.every((s) => (s.retry_count || 0) === 0)
+    ) {
+      notes.push({
+        type: 'flakiness',
+        step_id: null,
+        message:
+          `${measurements.device_failures} device call(s) failed during this run, but no step ` +
+          `reported a retry; the recorded attempt counts under-report what the device saw.`,
+      });
+    }
+
+    return notes;
+  }
+
+  finalize({ status, durationSeconds = 0, summary, metadata, measurements } = {}) {
     return withLock(this._lock, () => {
       this._refreshFromDisk();
+
+      // Appended INSIDE the lock and deduped by (type, message), so re-running
+      // finalize — which the execute guide tells an agent to do after a failed
+      // one — cannot stack duplicates.
+      for (const note of this._measurementObservations(measurements, Number(durationSeconds) || 0)) {
+        const already = this._observations.some(
+          (o) => o.type === note.type && o.message === note.message
+        );
+        if (!already) this._observations.push(note);
+      }
+
       const passed = this._assertions.filter((a) => a.status === 'passed').length;
       const failed = this._assertions.filter((a) => a.status === 'failed').length;
       const total = this._assertions.length;
@@ -264,6 +351,16 @@ class ResultStore {
           `${resolvedStatus}: ${passed}/${total} assertion(s) passed across ${this._steps.length} step(s).`,
       };
 
+      // Additive and OMITTED when absent: a result file from a run with no
+      // trace must stay shaped exactly as 0.24.0 wrote it, so finalize never
+      // emits an empty measurements object as a placeholder.
+      if (measurements) result.measurements = measurements;
+
+      // Present only when non-empty. That is what makes `crashes` additive in
+      // PRACTICE and not merely in schema: a run with no crashes emits exactly
+      // the file it emitted before this field existed.
+      if (this._crashes.length > 0) result.crashes = this._crashes;
+
       this._atomicWrite(JSON.stringify(result, null, 2));
       return result;
     });

package/src/schemas/config_schema.json

@@ -37,6 +37,17 @@
     "environments": { "$ref": "#/definitions/stringList" },
     "protected_directories": { "$ref": "#/definitions/stringList" },
     "business_critical_paths": { "$ref": "#/definitions/stringList" },
+    "telemetry": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Anonymous usage telemetry. Off unless `enabled` is literally true. MAUTO_TELEMETRY=0 and DO_NOT_TRACK=1 override this and always win; MAUTO_TELEMETRY=1 deliberately does not enable. Run `mauto telemetry status` for the exact field list.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Opt in to anonymous usage telemetry. Default false. Set with `mauto telemetry enable`."
+        }
+      }
+    },
     "app": {
       "type": "object",
       "additionalProperties": true,