mobile-automator 0.25.0 → 0.26.0

package/src/cli.js

@@ -23,6 +23,19 @@ const guideEmitter = require('./guide/emitter');
 const { ADAPTERS } = require('./init/adapters');
 const { isSemanticAction, ACTION_METHOD, selectResolver } = require('./device/semantic-press');
 const connection = require('./device/connection');
+const { record } = require('./observe/recorder');
+const { resolveRunId } = require('./observe/settings');
+const { runTracePath } = require('./observe/paths');
+const { readTrace, deriveRun, pruneRunTraces } = require('./observe/trace');
+const { readHandle, readSessionId } = require('./device/session-handle');
+const { captureOnFailure } = require('./observe/failure-capture');
+const { crashTimestampMs } = require('./device/crash-model');
+const { probeCrashes } = require('./device/failure-probe');
+const observeTelemetry = require('./observe/telemetry');
+const observeSpool = require('./observe/spool');
+const observeTransport = require('./observe/transport');
+const { makeFlusher } = require('./observe/flush');
+const { findWorkspaceRoot, noWorkspaceFailure } = require('./workspace/discover');
 
 // Commander throws (via exitOverride) for two very different reasons, and the
 // split below is the ONLY thing that tells them apart.
@@ -625,6 +638,75 @@ function handleResultAddAssertion({ resultStoreFactory, projectRoot }, opts) {
   return { envelope: ok({ run_id: runId, assertion: entry }, storeHint(store)), exitKind: 'ok' };
 }
 
+// Record an observed app crash.
+function handleResultAddCrash({ resultStoreFactory, projectRoot }, opts = {}) {
+  const store = resultStoreFactory({
+    runId: opts.runId,
+    scenarioId: opts.scenarioId,
+    projectRoot,
+  });
+  const entry = store.addCrash({
+    crash_id: opts.crashId,
+    process: opts.process,
+    timestamp: opts.crashTimestamp,
+    step_id: opts.stepId,
+    excerpt: opts.excerpt,
+    report_path: opts.reportPath,
+  });
+  return { envelope: ok({ crash: entry }, storeHint(store)), exitKind: 'ok' };
+}
+
+// Tolerance for calling a reported duration wrong.
+//
+// The measured value is a wall-clock span between two recorded events, so
+// sub-second differences are rounding rather than disagreement, and 10% absorbs
+// the honest gap between "the run" and "the part of the run mauto saw" —
+// setup before the first verb, and finalize's own execution after the last.
+//
+// Symmetric on purpose. An UNDER-claim means the agent lost track of its own
+// retries; an OVER-claim means it counted its planning as run time. Both are
+// worth a human seeing, and one rule is two tests instead of four.
+const DURATION_TOLERANCE_SECONDS = 1;
+const DURATION_TOLERANCE_RATIO = 0.1;
+
+// Turn the run's trace into the duration to record and the measurement block to
+// record beside it. Total: an unreadable, absent or unmeasurable trace yields
+// the reported value and a `measurements` block that says so, never an error.
+function measureRun({ projectRoot, runId, reported }) {
+  const derived = deriveRun(readTrace(runTracePath(projectRoot, runId)));
+  const reportedSeconds = reported === undefined ? null : Number(reported);
+  const hasReported = reportedSeconds !== null && Number.isFinite(reportedSeconds);
+
+  const base = {
+    reported_duration_seconds: hasReported ? reportedSeconds : null,
+    trace_events: derived ? derived.trace_events : 0,
+    device_failures: derived ? derived.device_failures : 0,
+    trace_truncated: derived ? derived.trace_truncated : false,
+    failure_screenshots: derived ? derived.failure_screenshots : [],
+  };
+
+  // No trace, or a trace too short to span any time. Falling back to the flag
+  // is 0.24.0's behaviour, and `source` records that it IS a fallback rather
+  // than dressing a self-report as a measurement.
+  if (!derived || derived.duration_seconds === null) {
+    return {
+      durationSeconds: hasReported ? reportedSeconds : 0,
+      measurements: { source: hasReported ? 'reported' : 'none', duration_disagreement: false, ...base },
+    };
+  }
+
+  const measured = derived.duration_seconds;
+  const tolerance = Math.max(DURATION_TOLERANCE_SECONDS, measured * DURATION_TOLERANCE_RATIO);
+  return {
+    durationSeconds: measured,
+    measurements: {
+      source: 'trace',
+      duration_disagreement: hasReported && Math.abs(reportedSeconds - measured) > tolerance,
+      ...base,
+    },
+  };
+}
+
 function handleResultFinalize({ resultStoreFactory, memoryStoreFactory, projectRoot }, opts) {
   const { runId, scenarioId, status, duration } = opts;
   if (!runId) {
@@ -643,11 +725,20 @@ function handleResultFinalize({ resultStoreFactory, memoryStoreFactory, projectR
   if (opts.apiLevel !== undefined) metadata.api_level = opts.apiLevel;
   if (opts.environment !== undefined) metadata.environment = opts.environment;
 
+  // Measure BEFORE constructing the store: the trace is read-only here, and
+  // deriving first keeps the store's lock window as small as it already is.
+  const measured = measureRun({ projectRoot, runId, reported: duration });
+
   const store = resultStoreFactory({ runId, scenarioId, projectRoot });
   const result = store.finalize({
     status,
-    durationSeconds: duration === undefined ? 0 : Number(duration),
+    // Derived, not trusted. `--duration` survives in
+    // measurements.reported_duration_seconds and, when it disagrees with the
+    // clock, in a typed state_context observation — the disagreement is a
+    // signal about the agent, so it is recorded rather than resolved.
+    durationSeconds: measured.durationSeconds,
     metadata,
+    measurements: measured.measurements,
     // Undefined when --summary is omitted; ResultStore.finalize's own
     // `summary || <generated default>` already treats that as "no override",
     // so no provided-keys-only guard is needed here (unlike metadata, whose
@@ -655,6 +746,12 @@ function handleResultFinalize({ resultStoreFactory, memoryStoreFactory, projectR
     summary: opts.summary,
   });
 
+  // Retention, at the only moment a run is known to be over and the only place
+  // off the hot path. Never this run's own trace — it is the evidence behind
+  // every number just written. Best-effort by construction; pruneRunTraces
+  // swallows everything and returns a count.
+  pruneRunTraces(projectRoot, { except: runId });
+
   // Auto-harvest into cross-session memory. This is best-effort: a memory
   // failure must never fail an otherwise-successful finalize, so its warnings
   // fold into the envelope hint instead of throwing.
@@ -691,7 +788,11 @@ function storeHint(store) {
 // on success; only their ERROR paths (unknown topic/name) fall back to the
 // `fail(...)` envelope + exit 3.
 
-function handleSetup({ projectRoot }, opts = {}) {
+// `ancestorRoot` is the workspace discovery found ABOVE cwd, if any. setup
+// still scaffolds in cwd — it is the one verb whose job is to create a
+// workspace where the user stands — but a nested workspace silently shadows
+// the ancestor for every later verb run below it, so say so.
+function handleSetup({ projectRoot, ancestorRoot = null }, opts = {}) {
   const raw = opts.mode === undefined ? 'aware' : String(opts.mode);
   const mode = MODE_ALIASES[raw];
   if (!mode) {
@@ -701,8 +802,24 @@ function handleSetup({ projectRoot }, opts = {}) {
     };
   }
   const r = scaffold(projectRoot, { mode });
+  const hint = ancestorRoot
+    ? `An existing workspace was found in an ancestor directory (${ancestorRoot}). This new workspace in ${projectRoot} shadows it for every mauto verb run from here or below; remove it if you meant to use the ancestor's.`
+    : null;
   return {
-    envelope: ok({ created: r.created, mode: r.mode, next: 'run `mauto guide setup`' }),
+    envelope: ok(
+      {
+        created: r.created,
+        mode: r.mode,
+        // A NOTICE, not a prompt. mauto verbs are invoked by an agent, so there
+        // is nobody at the keyboard to answer a question — and an agent answering
+        // a consent question on a human's behalf is worse than not asking. It
+        // rides in the envelope (structured, in-band) rather than as a stderr
+        // banner, so the agent can surface it to the human it belongs to.
+        telemetry: { enabled: false, notice: observeTelemetry.CONSENT_NOTICE },
+        next: 'run `mauto guide setup`',
+      },
+      hint
+    ),
     exitKind: 'ok',
   };
 }
@@ -732,6 +849,87 @@ function handleConfigSet({ projectRoot }, key, rawValue) {
   return { envelope: ok({ key, value }), exitKind: 'ok' };
 }
 
+// --- Slice 5: telemetry consent surface -----------------------------------
+//
+// `status` is the informed half of informed consent, and it is COMPUTED: the
+// field lists come from EVENT_FIELDS at runtime, so the disclosure a user reads
+// before opting in cannot drift from what the uploader actually sends. Prose
+// that restates a catalog is prose that will eventually be wrong.
+
+function telemetryReport({ projectRoot, env }, extra = {}) {
+  const decision = observeTelemetry.decideForProject(projectRoot, env);
+  return {
+    enabled: decision.enabled,
+    reason: decision.reason,
+    endpoint: observeTransport.endpointUrl(env),
+    fields_sent: observeTelemetry.sentFields(),
+    fields_never_sent: observeTelemetry.neverSentFields(),
+    spool: observeSpool.stats({ projectRoot, env }),
+    notice: observeTelemetry.CONSENT_NOTICE,
+    enable_with: 'mauto telemetry enable',
+    ...extra,
+  };
+}
+
+function handleTelemetryStatus({ projectRoot, env = process.env }) {
+  return { envelope: ok(telemetryReport({ projectRoot, env })), exitKind: 'ok' };
+}
+
+// Writes the durable intent, then reports the RESOLVED state — which may still
+// be off, because an env kill switch wins. Reporting `enabled: true` here when
+// MAUTO_TELEMETRY=0 is set would be a lie, and the config is not the place to
+// resolve a conflict the environment owns.
+function handleTelemetryEnable({ projectRoot, env = process.env }) {
+  observeTelemetry.setEnabled(projectRoot, true);
+  const data = telemetryReport({ projectRoot, env });
+  const hint =
+    data.reason === 'kill_switch'
+      ? 'Telemetry is enabled in config.json but MAUTO_TELEMETRY=0 is set in this environment and overrides it.'
+      : data.reason === 'do_not_track'
+        ? 'Telemetry is enabled in config.json but DO_NOT_TRACK is set in this environment and overrides it.'
+        : data.reason === 'no_token'
+          ? 'Telemetry is enabled in config.json but this build ships no project token, so nothing will be sent.'
+          : undefined;
+  return { envelope: ok(data, hint), exitKind: 'ok' };
+}
+
+function handleTelemetryDisable({ projectRoot, env = process.env }) {
+  observeTelemetry.setEnabled(projectRoot, false);
+  return { envelope: ok(telemetryReport({ projectRoot, env })), exitKind: 'ok' };
+}
+
+// The explicit escape hatch. This is the ONE verb allowed a network round trip,
+// because the user asked for one and is willing to wait for it — every other
+// verb appends to the spool and exits. A machine that never runs a daemon
+// drains here.
+async function handleTelemetryFlush({ projectRoot, env = process.env, flusher }) {
+  const flush = flusher || makeFlusher({ projectRoot, env });
+  const r = await flush();
+  // exitKind stays 'ok': the envelope's own `ok` says the VERB executed — an
+  // undelivered spool is a non-error state by design (src/observe/spool.js).
+  // The flush's verdict — including permanently discarded events — is data:
+  // `ok` below, alongside the counts. Units: `kept` counts BATCHES (files);
+  // `sent`, `dropped` and `kept_events` count events.
+  const hint =
+    r.dropped > 0
+      ? `${r.dropped} event${r.dropped === 1 ? '' : 's'} permanently discarded — the endpoint rejected them (revoked token, wrong host, or a non-retryable status). They will not be retried.`
+      : r.kept > 0
+        ? `${r.kept} batch${r.kept === 1 ? '' : 'es'} (${r.kept_events} events) kept for retry — the next daemon drain or mauto telemetry flush will resend them.`
+        : undefined;
+  return {
+    envelope: ok({
+      skipped: r.skipped,
+      sent: r.sent,
+      dropped: r.dropped,
+      kept: r.kept,
+      kept_events: r.kept_events,
+      ok: r.ok,
+      spool: observeSpool.stats({ projectRoot, env }),
+    }, hint),
+    exitKind: 'ok',
+  };
+}
+
 // RAW content on success; fail envelope only when the topic is unknown.
 function handleGuide({ projectRoot, emitter = guideEmitter, config = configManager }, topic) {
   const cfg = config.load(projectRoot);
@@ -1118,6 +1316,134 @@ async function handleDevicesClear({
   };
 }
 
+// --- Crash diagnostics (slice 4) -----------------------------------------
+//
+// A DIAGNOSTIC verb, like `devices` / `session` / `memory` — deliberately NOT
+// in src/device/action-catalog.js, which holds exactly the scenario-schema
+// actions and whose lint guard asserts parity in both directions.
+
+const CRASH_REPORT_HEAD_LINES = 200;
+const CRASH_LIST_HINT =
+  'The device engine could not read crash reports. Run `mauto devices` to confirm the device is reachable; crash reporting needs the helper binary that ships with the device engine.';
+
+// Default watermark: when a device session is live, its handle already records
+// started_at (src/device/session-daemon.js). Bind, do not copy — there is no new
+// timestamp artifact and no second source of truth for "when did this session
+// begin". No handle means no watermark, which means UNSCOPED, which the envelope
+// reports as `since: null` rather than pretending the list is recent.
+function sessionWatermark(projectRoot) {
+  const handle = readHandle(projectRoot);
+  const t = handle && handle.started_at;
+  return typeof t === 'string' && Number.isFinite(Date.parse(t)) ? t : null;
+}
+
+// Split a crash list around a watermark. Reports whose own time is unreadable
+// are neither included nor discarded — they are counted, so the caller can see
+// that the device returned something the tool could not place in time.
+function scopeCrashes(crashes, sinceMs) {
+  if (sinceMs == null) return { crashes, unattributed: 0 };
+  const inWindow = [];
+  let unattributed = 0;
+  for (const c of crashes) {
+    const ms = crashTimestampMs(c);
+    if (ms == null) unattributed += 1;
+    else if (ms >= sinceMs) inWindow.push(c);
+  }
+  return { crashes: inWindow, unattributed };
+}
+
+async function handleCrashList({ deviceBridge, projectRoot }, opts = {}) {
+  const sinceRaw = opts.since !== undefined ? opts.since : sessionWatermark(projectRoot);
+  let sinceMs = null;
+  if (sinceRaw != null) {
+    sinceMs = Date.parse(sinceRaw);
+    if (!Number.isFinite(sinceMs)) {
+      return {
+        envelope: fail(
+          'invalid_input',
+          `could not parse --since "${sinceRaw}" as a date`,
+          'Pass an ISO 8601 timestamp, e.g. --since 2026-09-05T10:00:00Z.'
+        ),
+        exitKind: 'invalid_input',
+      };
+    }
+  }
+
+  let all;
+  try {
+    all = await deviceBridge.listCrashes();
+  } catch (err) {
+    // "Could not look" is NOT "found none". Reporting ok:true with an empty
+    // list here would be this slice's own bug with the sign flipped.
+    return {
+      envelope: fail(err.kind || 'device', err.message || String(err), err.hint || CRASH_LIST_HINT),
+      exitKind: err.kind || 'device',
+    };
+  }
+
+  const { crashes, unattributed } = scopeCrashes(all, sinceMs);
+  record(
+    {
+      level: 'info',
+      src: 'cli',
+      event: 'crash.list',
+      crash_count: Number.isFinite(crashes.length) ? crashes.length : undefined,
+    },
+    { projectRoot }
+  );
+  return {
+    envelope: ok({
+      crashes,
+      count: crashes.length,
+      since: sinceMs == null ? null : sinceRaw,
+      unattributed,
+    }),
+    exitKind: 'ok',
+  };
+}
+
+async function handleCrashGet({ deviceBridge, fs: fsDep = fs }, id, opts = {}) {
+  let report;
+  try {
+    report = await deviceBridge.getCrash(id);
+  } catch (err) {
+    return {
+      envelope: fail(err.kind || 'device', err.message || String(err), err.hint || CRASH_LIST_HINT),
+      exitKind: err.kind || 'device',
+    };
+  }
+
+  // --out writes the FULL report and returns only its path. This is how a
+  // tens-of-kilobytes native tombstone reaches a result file without passing
+  // through the agent's context window.
+  if (opts.out) {
+    try {
+      fsDep.writeFileSync(opts.out, report);
+    } catch (err) {
+      return {
+        envelope: fail(
+          'environment',
+          `could not write the crash report to ${opts.out}: ${err.message}`,
+          'Check the directory exists and is writable.'
+        ),
+        exitKind: 'environment',
+      };
+    }
+    return { envelope: ok({ crash_id: id, path: opts.out, truncated: false }), exitKind: 'ok' };
+  }
+
+  const lines = String(report).split('\n');
+  const truncated = !opts.full && lines.length > CRASH_REPORT_HEAD_LINES;
+  return {
+    envelope: ok({
+      crash_id: id,
+      report: truncated ? lines.slice(0, CRASH_REPORT_HEAD_LINES).join('\n') : String(report),
+      truncated,
+    }),
+    exitKind: 'ok',
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Program wiring
 // ---------------------------------------------------------------------------
@@ -1142,10 +1468,31 @@ function buildProgram(deps = {}) {
     resultStoreFactory = (args) => new ResultStore(args),
     // Factory for the cross-session memory store. Overridable in tests.
     memoryStoreFactory = (args) => new MemoryStore(args),
-    // Project root used to resolve mobile-automator/results/.
-    projectRoot = process.cwd(),
+    // Where the creating verbs (setup, init) write: always the directory the
+    // user stands in, never a discovered ancestor. Defaults to an injected
+    // projectRoot so tests that inject only a root keep writing there.
+    cwd = deps.projectRoot !== undefined ? deps.projectRoot : process.cwd(),
+    // The upward-discovery result `{ root, searched }` (#188): run() resolves
+    // it once and passes it in, tests inject it wholesale, and a bare
+    // buildProgram() discovers from cwd exactly as run() does. ONE fabrication
+    // rule, stated once: a caller that injects ONLY a projectRoot is trusted
+    // to know where the workspace is ({ root: projectRoot }) — the legacy
+    // handler-test seam, and deliberately gate-arming. run() passes cwd +
+    // workspace and NEVER projectRoot, so production cannot arm this branch
+    // and silently disable the requireWorkspace gate.
+    workspace = deps.projectRoot !== undefined
+      ? { root: deps.projectRoot, searched: [deps.projectRoot] }
+      : findWorkspaceRoot(cwd),
+    // Project root used to resolve mobile-automator/results/ — and, through the
+    // emitters below, mobile-automator/.logs/. One root, one tree. The
+    // discovered workspace when there is one; cwd otherwise, which is what the
+    // tolerant verbs (guide, mcp, read-only device/session) have always used.
+    projectRoot = workspace.root || cwd,
+    // The exit paths. run() passes its own instance so the help/version and
+    // fatal paths it owns share this program's resolved verb.
+    emitters = makeEmitters({ projectRoot }),
     // Sink used to emit the rendered envelope + drive the exit code.
-    emit = defaultEmit,
+    emit = emitters.emit,
   } = deps;
 
   const program = new Command();
@@ -1184,6 +1531,31 @@ function buildProgram(deps = {}) {
   });
   program.configureOutput({ writeErr: () => {} });
 
+  // Name the verb for the observability record, from commander's own resolution
+  // rather than from argv. preAction fires only after a SUCCESSFUL parse and
+  // only for a command that exists, which is what makes `verb` provably a name
+  // out of the vocabulary this CLI ships — the property event.js's `sends: true`
+  // classification asserts. Hooks registered on the root are inherited by every
+  // subcommand, so one registration covers all of them.
+  //
+  // `actionCommand` is the innermost command (`get` in `config get mode`), so
+  // walk up to the child of the root: the record names the verb, not its
+  // subcommand, keeping the vocabulary the size of the verb list.
+  program.hook('preAction', (_thisCommand, actionCommand) => {
+    // Read --run-id off the INNERMOST command (e.g. `add-step`) before walking
+    // up to name the verb (`result`). The three result verbs already require
+    // it, so they correlate with no new flag and no environment variable; an
+    // explicit flag beats the ambient MAUTO_RUN_ID because it is scoped to this
+    // invocation and the environment is not.
+    const opts = actionCommand.opts();
+    emitters.setRunId(
+      (typeof opts.runId === 'string' && opts.runId ? opts.runId : null) || resolveRunId(process.env)
+    );
+    let command = actionCommand;
+    while (command.parent && command.parent.parent) command = command.parent;
+    emitters.setVerb(command.name());
+  });
+
   const humanFlag = () => Boolean(program.opts().human);
 
   // The single envelope boundary. Wrap every `.action(...)` callback so any
@@ -1203,6 +1575,20 @@ function buildProgram(deps = {}) {
     }
   };
 
+  // Gate for verbs whose whole job is reading or writing the workspace. With
+  // no workspace discovered, carrying on against cwd is what produced #188's
+  // confident wrong answers — `ok:true` with a value silently absent, an
+  // "empty" memory store, a result file written where nobody will look — and
+  // `config set` would even create a stray workspace. Fail environment
+  // (exit 5) naming where we looked, so the agent can recover.
+  const requireWorkspace = (action) => (...args) => {
+    if (!workspace.root) {
+      emit(noWorkspaceFailure(workspace.searched), humanFlag());
+      return undefined;
+    }
+    return action(...args);
+  };
+
   // Resolve which device a verb targets: explicit --device wins, else the
   // persisted selection, else null (mobile-mcp auto-selects a single device).
   // Keeping the no-selection fast path returning null preserves zero-config use.
@@ -1221,13 +1607,55 @@ function buildProgram(deps = {}) {
     let bridge;
     let close;
     try {
-      ({ bridge, close } = await deviceBridgeFactory({ device, projectRoot }));
+      // autostart: the daemon is a per-workspace artifact — its .session/ tree
+      // and logs live under mobile-automator/. With no discovered workspace
+      // there is nowhere legitimate to put one, so never autostart: the verb
+      // connects one-shot and creates nothing. `ok:true` plus a phantom
+      // workspace is the exact #188 pathology.
+      ({ bridge, close } = await deviceBridgeFactory({
+        device,
+        projectRoot,
+        autostart: Boolean(workspace.root),
+      }));
+      // AFTER the connect, deliberately: the handle is written when the daemon
+      // starts listening, so before this point it may legitimately not exist
+      // yet. Best-effort — readSessionId never throws and returns null for an
+      // absent or malformed handle, which is a normal state (a one-shot
+      // fallback connection has no daemon at all).
+      emitters.setSessionId(readSessionId(projectRoot));
     } catch (err) {
       emit(deviceFail(err), humanFlag());
       return;
     }
     try {
       const r = await fn(bridge);
+      // The ONE window where a device failure can still be investigated: after
+      // fn(bridge) has produced its verdict and before `finally` closes the
+      // connection. The connect-failure catch above cannot do this — there is
+      // no bridge there — which is why this is here and not wrapped around the
+      // whole function.
+      //
+      // The return value of BOTH calls is deliberately unused. `r` reaches
+      // emit() untouched (aside from probeCrashes's own in-place, additive
+      // mutation of r.envelope) whether either helper succeeded, failed, or
+      // never ran; neither may mask or replace the error the caller actually
+      // asked about. Probe before screenshot: the probe has its own short,
+      // gated deadline and must not sit behind the screenshot's device round
+      // trip.
+      await probeCrashes({
+        bridge,
+        envelope: r.envelope,
+        verb: emitters.getVerb(),
+        projectRoot,
+        watermark: sessionWatermark(projectRoot),
+      });
+      await captureOnFailure({
+        bridge,
+        result: r,
+        projectRoot,
+        runId: emitters.getRunId(),
+        verb: emitters.getVerb(),
+      });
       emit(r, humanFlag());
     } finally {
       if (typeof close === 'function') await close();
@@ -1382,7 +1810,7 @@ function buildProgram(deps = {}) {
       []
     )
     .option('--capture <name=value>', 'captured variable; repeatable', collect, [])
-    .action(withEnvelope((opts) => {
+    .action(withEnvelope(requireWorkspace((opts) => {
       const r = handleResultAddStep(
         { resultStoreFactory, projectRoot },
         {
@@ -1398,7 +1826,7 @@ function buildProgram(deps = {}) {
         }
       );
       emit(r, humanFlag());
-    }));
+    })));
 
   result
     .command('add-assertion')
@@ -1412,7 +1840,7 @@ function buildProgram(deps = {}) {
     .option('--message <text>', 'human-readable justification for the verdict')
     .option('--expected <v>', 'expected value')
     .option('--actual <v>', 'observed value')
-    .action(withEnvelope((opts) => {
+    .action(withEnvelope(requireWorkspace((opts) => {
       const r = handleResultAddAssertion(
         { resultStoreFactory, projectRoot },
         {
@@ -1428,7 +1856,35 @@ function buildProgram(deps = {}) {
         }
       );
       emit(r, humanFlag());
-    }));
+    })));
+
+  result
+    .command('add-crash')
+    .description('Record an app crash observed during the run')
+    .requiredOption('--run-id <id>', 'run identifier (run_YYYYMMDD_HHMMSS)')
+    .option('--scenario-id <id>', 'scenario identifier')
+    .requiredOption('--crash-id <id>', 'device-local report id (from `mauto crash list`)')
+    .option('--step-id <id>', 'step in flight when the crash was observed')
+    .option('--process <name>', 'package/bundle identifier of the process that died')
+    .option('--crash-timestamp <iso>', "the device's own time for the report")
+    .option('--excerpt <text>', 'head of the crash report (stored capped at 2000 chars)')
+    .option('--report-path <path>', 'path to the full report written by `mauto crash get --out`')
+    .action(withEnvelope(requireWorkspace((opts) => {
+      const r = handleResultAddCrash(
+        { resultStoreFactory, projectRoot },
+        {
+          runId: opts.runId,
+          scenarioId: opts.scenarioId,
+          crashId: opts.crashId,
+          stepId: opts.stepId,
+          process: opts.process,
+          crashTimestamp: opts.crashTimestamp,
+          excerpt: opts.excerpt,
+          reportPath: opts.reportPath,
+        }
+      );
+      emit(r, humanFlag());
+    })));
 
   result
     .command('finalize')
@@ -1442,7 +1898,7 @@ function buildProgram(deps = {}) {
     .option('--api-level <v>', 'OS API level / version')
     .option('--environment <v>', "target environment (e.g. 'staging')")
     .option('--summary <text>', 'override the generated one-line result summary')
-    .action(withEnvelope((opts) => {
+    .action(withEnvelope(requireWorkspace((opts) => {
       const r = handleResultFinalize(
         { resultStoreFactory, memoryStoreFactory, projectRoot },
         {
@@ -1458,7 +1914,7 @@ function buildProgram(deps = {}) {
         }
       );
       emit(r, humanFlag());
-    }));
+    })));
 
   // --- Slice 3 verbs --------------------------------------------------------
 
@@ -1467,7 +1923,7 @@ function buildProgram(deps = {}) {
   // anything else is an envelope error and goes through the normal emit path.
   const emitMaybeRaw = (r) => {
     if (r.raw !== undefined && r.exitKind === 'ok') {
-      emitRaw(r.raw, r.exitKind);
+      emitters.emitRaw(r.raw, r.exitKind);
     } else {
       emit(r, humanFlag());
     }
@@ -1478,7 +1934,10 @@ function buildProgram(deps = {}) {
     .description('Scaffold the workspace (mobile-automator/) and write a config')
     .option('--mode <mode>', 'aware (platform-aware, default) | agnostic (platform-agnostic)')
     .action(withEnvelope((opts) => {
-      const r = handleSetup({ projectRoot }, { mode: opts.mode });
+      // cwd, not the discovered root: setup creates a workspace where the user
+      // stands. A discovered root that is not cwd is an ancestor worth naming.
+      const ancestorRoot = workspace.root && workspace.root !== cwd ? workspace.root : null;
+      const r = handleSetup({ projectRoot: cwd, ancestorRoot }, { mode: opts.mode });
       emit(r, humanFlag());
     }));
 
@@ -1486,11 +1945,11 @@ function buildProgram(deps = {}) {
   config
     .command('get <key>')
     .description('Get a dotted-path config value')
-    .action(withEnvelope((key) => emit(handleConfigGet({ projectRoot }, key), humanFlag())));
+    .action(withEnvelope(requireWorkspace((key) => emit(handleConfigGet({ projectRoot }, key), humanFlag()))));
   config
     .command('set <key> <value>')
     .description('Set a dotted-path config value (coerced to its declared type per `mauto schema config`)')
-    .action(withEnvelope((key, value) => emit(handleConfigSet({ projectRoot }, key, value), humanFlag())));
+    .action(withEnvelope(requireWorkspace((key, value) => emit(handleConfigSet({ projectRoot }, key, value), humanFlag()))));
 
   program
     .command('guide <topic>')
@@ -1516,28 +1975,28 @@ function buildProgram(deps = {}) {
     .description('Print RAW memory markdown (run-history[, app-knowledge, preferences])')
     .option('--kind <k>', 'run-history | app-knowledge | preferences')
     .option('--scenario <id>', 'filter run-history to one scenario')
-    .action(withEnvelope((opts) =>
+    .action(withEnvelope(requireWorkspace((opts) =>
       emitMaybeRaw(
         handleMemoryShow({ memoryStoreFactory, projectRoot }, { kind: opts.kind, scenario: opts.scenario })
       )
-    ));
+    )));
 
   memory
     .command('add <text>')
     .description('Record an agent-authored memory entry (app-knowledge or preferences)')
     .requiredOption('--kind <k>', 'app-knowledge | preferences')
-    .action(withEnvelope((text, opts) =>
+    .action(withEnvelope(requireWorkspace((text, opts) =>
       emit(handleMemoryAdd({ memoryStoreFactory, projectRoot }, { kind: opts.kind, text }), humanFlag())
-    ));
+    )));
 
   memory
     .command('forget')
     .description('Remove agent-authored memory entries whose text contains a substring')
     .requiredOption('--kind <k>', 'app-knowledge | preferences')
     .requiredOption('--match <substr>', 'remove entries containing this substring')
-    .action(withEnvelope((opts) =>
+    .action(withEnvelope(requireWorkspace((opts) =>
       emit(handleMemoryForget({ memoryStoreFactory, projectRoot }, { kind: opts.kind, match: opts.match }), humanFlag())
-    ));
+    )));
 
   // --- Slice 7: vendor init + MCP prompts server ---------------------------
 
@@ -1546,7 +2005,9 @@ function buildProgram(deps = {}) {
     .description('Install native Agent Skills (+ slash commands/rules + MCP entry) for an agent')
     .requiredOption('--agent <name>', 'claude | cursor | gemini | copilot | agents | all')
     .action(withEnvelope((opts) => {
-      const r = handleInit({ projectRoot }, opts.agent);
+      // cwd, as before discovery existed: init writes host files where the
+      // user invoked it.
+      const r = handleInit({ projectRoot: cwd }, opts.agent);
       emit(r, humanFlag());
     }));
 
@@ -1561,10 +2022,10 @@ function buildProgram(deps = {}) {
     .description('Start the device session daemon (subsequent verbs reuse its connection)')
     .option('--device <id>', 'pin the daemon to a target device id')
     .option('--idle <ms>', 'idle timeout in milliseconds before the daemon self-reaps')
-    .action(withEnvelope(async (opts) => {
+    .action(withEnvelope(requireWorkspace(async (opts) => {
       const r = await handleSessionStart({ projectRoot }, { device: opts.device, idle: opts.idle });
       emit(r, humanFlag());
-    }));
+    })));
 
   session
     .command('status')
@@ -1596,11 +2057,11 @@ function buildProgram(deps = {}) {
   devices
     .command('use <id>')
     .description('Persist a device selection so subsequent verbs reuse it (--device still overrides per-call)')
-    .action(withEnvelope((id) =>
+    .action(withEnvelope(requireWorkspace((id) =>
       connectBridge(null, (bridge) =>
         handleDevicesUse({ deviceBridge: bridge, projectRoot }, id)
       )
-    ));
+    )));
 
   devices
     .command('clear')
@@ -1610,6 +2071,69 @@ function buildProgram(deps = {}) {
       emit(r, humanFlag());
     }));
 
+  const crash = program
+    .command('crash')
+    .description('Diagnostics: crash reports currently readable on the device');
+
+  crash
+    .command('list')
+    .description('List crash reports, scoped to the current device session by default')
+    .option('--device <id>', 'target device id')
+    .option('--since <iso>', 'only reports at or after this ISO timestamp (default: session start)')
+    .action(withEnvelope((opts) =>
+      connectBridge(resolveVerbDevice(opts.device), (bridge) =>
+        handleCrashList(
+          { deviceBridge: bridge, projectRoot },
+          opts.since === undefined ? {} : { since: opts.since }
+        )
+      )
+    ));
+
+  crash
+    .command('get <id>')
+    .description('Fetch one crash report (head by default)')
+    .option('--device <id>', 'target device id')
+    .option('--full', 'return the whole report instead of its head')
+    .option('--out <path>', 'write the full report to a file and return its path')
+    .action(withEnvelope((id, opts) =>
+      connectBridge(resolveVerbDevice(opts.device), (bridge) =>
+        handleCrashGet({ deviceBridge: bridge }, id, { full: opts.full, out: opts.out })
+      )
+    ));
+
+  // --- Slice 5: telemetry ---------------------------------------------------
+
+  const telemetryCmd = program
+    .command('telemetry')
+    .description('Inspect and control anonymous usage telemetry (off by default)');
+
+  // requireWorkspace, same as config get/set: telemetry status/enable/disable
+  // all read or write mobile-automator/config.json, and flush reads/claims
+  // mobile-automator/.logs/telemetry.spool, so all four have #188's exact
+  // failure mode without the gate — status would report the SAME
+  // not_configured/no_token answer for "no workspace here" as for "a real,
+  // just-unconfigured workspace", and enable/disable would create a stray
+  // mobile-automator/ wherever the caller happened to be standing.
+  telemetryCmd
+    .command('status')
+    .description('Report whether telemetry is on, what would be sent, and what is queued')
+    .action(withEnvelope(requireWorkspace(() => emit(handleTelemetryStatus({ projectRoot }), humanFlag()))));
+
+  telemetryCmd
+    .command('enable')
+    .description('Turn on anonymous usage telemetry')
+    .action(withEnvelope(requireWorkspace(() => emit(handleTelemetryEnable({ projectRoot }), humanFlag()))));
+
+  telemetryCmd
+    .command('disable')
+    .description('Turn off anonymous usage telemetry')
+    .action(withEnvelope(requireWorkspace(() => emit(handleTelemetryDisable({ projectRoot }), humanFlag()))));
+
+  telemetryCmd
+    .command('flush')
+    .description('Upload any spooled telemetry now instead of waiting for the daemon')
+    .action(withEnvelope(requireWorkspace(async () => emit(await handleTelemetryFlush({ projectRoot }), humanFlag()))));
+
   program
     .command('mcp')
     .description('Run the MCP prompts server (stdio) exposing the mauto workflows as prompts')
@@ -1623,18 +2147,6 @@ function buildProgram(deps = {}) {
   return program;
 }
 
-function defaultEmit({ envelope, exitKind }, human) {
-  process.stdout.write(render(envelope, { human }) + '\n');
-  process.exit(exitCodeFor(exitKind));
-}
-
-// Print raw content (markdown / JSON schema / text) verbatim — no envelope
-// wrapping — then exit. Used by guide/schema/bootstrap success paths.
-function emitRaw(content, exitKind) {
-  process.stdout.write(content.endsWith('\n') ? content : content + '\n');
-  process.exit(exitCodeFor(exitKind));
-}
-
 // Keep the stack of a genuinely-unexpected error on STDERR so a crash stays
 // debuggable. The stdout envelope (the agent's contract) is untouched, and the
 // expected/diagnosed classes (invalid_input, environment) carry an actionable
@@ -1645,19 +2157,146 @@ function diagnose(err, exitKind) {
   }
 }
 
-// Last-resort emit for errors that escape BEFORE any action runs (so the
-// in-program withEnvelope boundary can't see them) — e.g. the ScenarioValidator
-// default-param compiling a corrupt bundled schema inside buildProgram, or a
-// stray unhandled rejection. Always one JSON envelope on stdout + the mapped
-// exit code, never a raw stack trace. `human` (opt-in --human) renders the fail
-// envelope readably instead of as JSON.
-function emitFatal(err, human = false) {
-  const { envelope, exitKind } = toEnvelope(err);
-  diagnose(err, exitKind);
-  process.stdout.write(render(envelope, { human }) + '\n');
-  process.exit(exitCodeFor(exitKind));
+// The exit paths, bound to ONE invocation's resolved dependencies. Per
+// invocation rather than module-scope because every input they need is: as
+// module-level functions, finish() could not see the projectRoot buildProgram()
+// was handed, so it reached around the program's own DI to process.cwd() and
+// wrote the record of a verb into a different tree than the verb ran against.
+function makeEmitters({ projectRoot = process.cwd() } = {}) {
+  // The top-level command commander actually RESOLVED, or null when parsing
+  // never got that far (a parse failure, or help/version). Set via setVerb()
+  // from buildProgram()'s preAction hook.
+  //
+  // Deliberately not `process.argv[2]`: event.js marks `verb` as `sends: true`
+  // on the grounds that it is "a fixed vocabulary we ship", and slice 5 ships
+  // it to a third party on that justification. argv[2] is arbitrary user text —
+  // `mauto --human config get mode` recorded `--human`.
+  let resolvedVerb = null;
+
+  // The run this invocation belongs to, and the daemon lifetime it used.
+  //
+  // Both follow resolvedVerb's pattern for resolvedVerb's reason: finish() is
+  // closed over this invocation's state, and every exit path reaches it
+  // through commander's own call stack, so there is nowhere else to put them.
+  //
+  // resolvedRunId is NOT validated here. It becomes a filename in exactly one
+  // place — runTracePath — which refuses anything unsafe and returns null, so
+  // a second predicate here could only disagree with that one.
+  let resolvedRunId = null;
+  // Set ONLY by connectBridge, and only after a successful connect. That is
+  // what makes `session_id` on a CLI event mean "this verb reached the device
+  // through that daemon".
+  let resolvedSessionId = null;
+
+  // THE process-ending path: every way this CLI terminates goes through here,
+  // so "is this invocation observable" has exactly one answer. Only `mauto mcp`
+  // is outside it — it serves until its client disconnects and then returns,
+  // with no termination to record.
+  //
+  // One function rather than four copies of a ten-line record() literal. Two of
+  // the four got written, and the classes left unrecorded were parse failures
+  // (#146) — the crashes this instrumentation exists to see — and help/version.
+  //
+  // `text` is optional: commander writes help/version itself, so that path has
+  // an invocation to record but nothing left to print.
+  //
+  // dur_ms uses process.uptime() (seconds since THIS process started, no state
+  // needed). A Date.now() stamped at require time would measure from whenever
+  // cli.js was loaded, which is not process start for anything that requires it
+  // first (a test harness, bin/mauto.js's own guards).
+  function finish({ text = '', exitKind, ok, errorKind, exitCode = exitCodeFor(exitKind) }) {
+    // The flag-resolved id when a command parsed, the environment otherwise: a
+    // parse failure reaches no preAction hook and so has no flag, but it is
+    // still part of the run and is exactly the class of failure (#146) this
+    // instrumentation exists to see.
+    const runId = resolvedRunId || resolveRunId(process.env);
+    // null for an id that cannot safely name a file. Every hostile
+    // MAUTO_RUN_ID lands here as "no trace" — but NOT as "no run_id below":
+    // the raw id is still recorded on the mauto.ndjson line, so a refused id
+    // is provably distinguishable from one never exported at all (no field).
+    const tracePath = runTracePath(projectRoot, runId);
+
+    // Record BEFORE the write: process.exit() below is immediate.
+    const fields = {
+      event: 'verb.end',
+      // `info`, not `warn`-on-failure: the failure is carried by `ok` and
+      // `error_kind`, and the LEVEL only decides routing. At `warn` every
+      // failed verb would clear the stderr threshold and echo the envelope the
+      // CLI just wrote. stderr stays a human's channel; the file sink
+      // (threshold `info`) keeps the forensic record either way.
+      level: 'info',
+      src: 'cli',
+      // Absent, not guessed, when no command resolved. makeEvent drops
+      // undefined fields, so the line carries no `verb` rather than a lie.
+      verb: resolvedVerb || undefined,
+      // Recorded even when the id could not name a trace file: the
+      // correlation still belongs in mauto.ndjson, where it is the only thing
+      // tying this line to a run. sends:false in the event catalog.
+      run_id: runId || undefined,
+      session_id: resolvedSessionId || undefined,
+      ok,
+      error_kind: errorKind,
+      exit_code: exitCode,
+      dur_ms: Math.round(process.uptime() * 1000),
+    };
+    record(fields, { projectRoot, tracePath: tracePath || undefined });
+    if (text) process.stdout.write(text.endsWith('\n') ? text : text + '\n');
+    process.exit(exitCode);
+  }
+
+  const fromEnvelope = (envelope, exitKind, human) => ({
+    text: render(envelope, { human }),
+    exitKind,
+    ok: Boolean(envelope && envelope.ok),
+    errorKind: envelope && envelope.error ? envelope.error.kind : undefined,
+  });
+
+  return {
+    finish,
+    setVerb: (verb) => {
+      resolvedVerb = verb;
+    },
+    setRunId: (runId) => {
+      resolvedRunId = runId;
+    },
+    setSessionId: (sessionId) => {
+      resolvedSessionId = sessionId;
+    },
+    // Read-only counterparts to the setters above, for the one other call site
+    // that needs this invocation's resolved run id / verb: connectBridge's
+    // screenshot-on-failure hook. Both values are already committed by the
+    // preAction hook by the time any verb's fn(bridge) can have returned, so
+    // there is nothing to resolve here — only to expose.
+    getRunId: () => resolvedRunId,
+    getVerb: () => resolvedVerb,
+
+    emit: ({ envelope, exitKind }, human) => finish(fromEnvelope(envelope, exitKind, human)),
+
+    // Raw content (markdown / JSON schema / text) verbatim, no envelope
+    // wrapping. Used by the guide/schema/bootstrap success paths.
+    emitRaw: (content, exitKind) => finish({ text: content, exitKind, ok: true }),
+
+    // Last-resort emit for errors that escape BEFORE any action runs, so the
+    // in-program withEnvelope boundary can't see them — a throw inside
+    // buildProgram, or a stray unhandled rejection. One JSON envelope on stdout
+    // + the mapped exit code, never a raw stack trace.
+    emitFatal: (err, human = false) => {
+      const { envelope, exitKind } = toEnvelope(err);
+      diagnose(err, exitKind);
+      finish(fromEnvelope(envelope, exitKind, human));
+    },
+  };
 }
 
+// bin/mauto.js registers the exported emitFatal as a PROCESS-wide
+// unhandledRejection handler, which can fire before run() has built anything —
+// so it needs a module-level way to reach the invocation in flight. A pointer to
+// the per-invocation instance, not a second copy of its state: an unhandled
+// rejection is exactly the crash class this instrumentation exists to see, and
+// it should carry the verb and projectRoot the invocation actually resolved.
+let activeEmitters = null;
+const emitFatal = (err, human = false) => (activeEmitters || makeEmitters()).emitFatal(err, human);
+
 async function run(argv) {
   // Belt-and-suspenders around the in-program withEnvelope boundary: a throw in
   // buildProgram() (e.g. the ScenarioValidator default-param compiling a corrupt
@@ -1666,21 +2305,40 @@ async function run(argv) {
   // `unhandledRejection` guard lives in bin/mauto.js (the process entry point),
   // not here, so calling run() in tests never installs a global exit-on-reject
   // listener that would leak across the suite.
+  //
+  // The workspace is resolved ONCE, here, and the same root reaches both the
+  // emitters (the .logs/ file sink and run traces) and every handler — and,
+  // through connection.js, the session daemon's MAUTO_SESSION_PROJECT_ROOT.
+  // No workspace found falls back to cwd for the verbs that tolerate that;
+  // buildProgram fails the ones that cannot (#188).
+  const cwd = process.cwd();
+  const workspace = findWorkspaceRoot(cwd);
+  const projectRoot = workspace.root || cwd;
+  const emitters = makeEmitters({ projectRoot });
+  activeEmitters = emitters;
   try {
-    const program = buildProgram();
+    // No projectRoot here, deliberately: buildProgram derives it as
+    // `workspace.root || cwd`, and an injected projectRoot is the test seam
+    // that FABRICATES a workspace — passing one would arm that branch and
+    // silently disable the requireWorkspace gate.
+    const program = buildProgram({ emitters, cwd, workspace });
     await program.parseAsync(argv);
   } catch (err) {
     // Help/version are NOT errors: commander already wrote the human-readable
-    // text to stdout. Leave them alone (no envelope) rather than wrapping them
-    // (#146). Same COMMANDER_NON_FAILURES set toEnvelope classifies against, so
-    // "which commander outcomes aren't failures" has exactly one answer.
+    // text to stdout, so they get no envelope wrapped around them (#146). Same
+    // COMMANDER_NON_FAILURES set toEnvelope classifies against, so "which
+    // commander outcomes aren't failures" has exactly one answer.
+    //
+    // They still exit through finish(), with no text of their own to print.
+    // They are real invocations, and slice 5 computes rates off this stream —
+    // omitting a whole invocation class skews every one of those denominators.
+    // `exitCode` comes from commander rather than a kind because commander
+    // already computed one: `.help({error:true})` yields 1, not 0.
     if (err && err.name === 'CommanderError' && COMMANDER_NON_FAILURES.has(err.code)) {
-      // Honor commander's own exit code rather than assuming 0 — `.help()`
-      // invoked with `{error:true}` computes 1.
-      process.exit(err.exitCode || 0);
+      emitters.finish({ exitCode: err.exitCode || 0, ok: true });
       return;
     }
-    emitFatal(err, argv.slice(2).includes('--human'));
+    emitters.emitFatal(err, argv.slice(2).includes('--human'));
   }
 }
 
@@ -1707,6 +2365,7 @@ module.exports = {
   handleAssert,
   handleResultAddStep,
   handleResultAddAssertion,
+  handleResultAddCrash,
   handleResultFinalize,
   handleSetup,
   handleConfigGet,
@@ -1724,4 +2383,10 @@ module.exports = {
   handleDevices,
   handleDevicesUse,
   handleDevicesClear,
+  handleTelemetryStatus,
+  handleTelemetryEnable,
+  handleTelemetryDisable,
+  handleTelemetryFlush,
+  handleCrashList,
+  handleCrashGet,
 };