@runuai/host 0.8.16 → 0.8.17

package/README.md

@@ -89,3 +89,26 @@ no build step (ADR-032).
 - [docs/host-ui.md](https://github.com/runuai/uai/blob/main/docs/host-ui.md) — the local UI surface.
 - [docs/host-packaging.md](https://github.com/runuai/uai/blob/main/docs/host-packaging.md) — how this package is built and published.
 </content>
+
+## Telemetry
+
+Installed hosts report **crashes only** to Sentry by default. Sent on a
+crash: the error and stack trace (paths and secret-shaped strings
+redacted), recent bridge-connection breadcrumbs, OS/runtime versions, the
+package version, and a pseudonymous host id. No sessions, no usage pings,
+and no request data — nothing is sent until something actually crashes.
+Telemetry is designed to exclude chat, prompts, env values, and repo
+content; error text is scrubbed for secret shapes, but redaction is
+pattern-based, not perfect. Repo checkouts and dev/test runs never report,
+and reporting only activates after this notice has been shown once (the
+`install`/`pair`/`setup`/`start`/`restart` commands print it — a silently
+upgraded service stays off until one of them runs).
+
+Opt out any time — add to `$UAI_HOME/.env.local` (default
+`~/.uai/.env.local`), then `uai-host restart`:
+
+```
+UAI_TELEMETRY_DISABLED=1
+```
+
+`UAI_SENTRY_DSN=<dsn>` redirects reports to your own Sentry instead.

package/lib/engines.ts

@@ -518,7 +518,7 @@ export function disconnectEngine(
 }
 
 // ---------------------------------------------------------------------------
-// Install a missing engine CLI (ADR-072).
+// Install a missing engine CLI (ADR-074).
 // ---------------------------------------------------------------------------
 
 /**

package/lib/env.ts

@@ -3,9 +3,9 @@
  * machine; cloud metadata arrives over the host protocol.
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, resolve } from "node:path";
+import { dirname, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { z } from "zod";
@@ -26,6 +26,12 @@ const schema = z.object({
   UAI_HOST_KEY_FILE: z.string().min(1).optional(),
   UAI_GH_PAT_FALLBACK: z.string().min(1).optional(),
   UAI_WORKSPACE_ROOT: z.string().min(1).default("~/.uai"),
+  // Crash reporting (ADR-071, docs/observability.md). Default-ON for
+  // installed hosts via the DSN baked into lib/obs.ts; UAI_SENTRY_DSN
+  // overrides it (self-hosted Sentry), UAI_TELEMETRY_DISABLED=1 turns it
+  // off entirely — zero telemetry bytes leave the machine.
+  UAI_SENTRY_DSN: z.string().min(1).optional(),
+  UAI_TELEMETRY_DISABLED: z.string().optional(),
   NODE_ENV: z
     .enum(["development", "production", "test"])
     .default("development"),
@@ -61,14 +67,27 @@ function findUp(start: string, pred: (dir: string) => boolean): string | null {
 }
 
 // Monorepo root iff we're running from a checkout: a dir holding BOTH
-// pnpm-workspace.yaml and a host-agent/ child. null when installed under
-// node_modules — then state lives under ~/.uai, never inside the package.
-const repoRoot = findUp(
-  here,
-  (d) =>
-    existsSync(resolve(d, "pnpm-workspace.yaml")) &&
-    existsSync(resolve(d, "host-agent")),
-);
+// pnpm-workspace.yaml and a host-agent/ child. The node_modules guard makes
+// the "null when installed" comment TRUE (review finding: a tarball beneath
+// a foreign pnpm workspace with a sibling host-agent/ resolved uaiHome — and
+// the telemetry disclosure marker — into that workspace instead of ~/.uai).
+// Real path first: pnpm reaches this file through symlinks. Keep in sync
+// with src/load-env.ts, which applies the same rule.
+const realHere = (() => {
+  try {
+    return realpathSync(here);
+  } catch {
+    return here;
+  }
+})();
+const repoRoot = realHere.split(sep).includes("node_modules")
+  ? null
+  : findUp(
+      realHere,
+      (d) =>
+        existsSync(resolve(d, "pnpm-workspace.yaml")) &&
+        existsSync(resolve(d, "host-agent")),
+    );
 
 // UAI_HOME: where .env.local + the data dir live. Explicit UAI_HOME wins; then
 // the parent of an explicit UAI_DATA_DIR; then the repo root (dev checkout);

package/lib/obs.ts

@@ -0,0 +1,514 @@
+/**
+ * Host-agent crash reporting (ADR-071). Default-ON for installed hosts,
+ * with disclosure and a first-class opt-out — an installed product whose
+ * crash reporting requires hand-editing .env.local reports nothing from
+ * exactly the machines we need visibility into. The contract:
+ *
+ * - UAI_TELEMETRY_DISABLED=1  → nothing initializes, zero bytes leave the
+ *   machine. The one switch, documented everywhere the DSN default is.
+ * - UAI_SENTRY_DSN=…          → operator override (self-hosters pointing at
+ *   their own Sentry).
+ * - otherwise                 → DEFAULT_HOST_DSN below. DSNs are public by
+ *   design (every browser bundle ships one); this is errors-only crash
+ *   reporting, content-scrubbed, console breadcrumbs disabled.
+ *
+ * Every start with the default DSN logs a disclosure line naming the
+ * opt-out, and the default only ACTIVATES after the persisted disclosure
+ * marker exists (see the gate below).
+ *
+ * Captures uncaught exceptions / unhandled rejections (then the process
+ * exits as it does today; launchd/systemd restarts it), plus
+ * bridge-lifecycle breadcrumbs for context. Console breadcrumbs are
+ * disabled: host console output carries third-party process text
+ * (git/docker stderr, agent lifecycle lines) no scrubber can bound.
+ *
+ * Errors only — tracesSampleRate 0. The WSS heartbeat shares this event loop
+ * (agent-notes: never block it); we add no per-event work.
+ *
+ * The scrub rules MIRROR lib/obs/scrub.ts on the cloud side, duplicated by
+ * hand because the cloud may not import host internals and vice versa
+ * (eslint import guard). Every behavior here — key lists, string patterns,
+ * depth cap ("[max-depth]", never raw pass-through), hostile-proxy fencing —
+ * must match the cloud scrubber; obs.test.ts holds the parity regressions
+ * and docs/observability.md holds the shared table. The hooks are exported
+ * so tests exercise exactly what Sentry runs.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import * as Sentry from "@sentry/node";
+
+import { env } from "./env";
+
+/**
+ * The uai-host Sentry project's DSN, baked into the shipped package (npm +
+ * desktop-vendored copy). Public by design — a DSN can only ingest events,
+ * never read them. Activation is still gated: persisted disclosure marker,
+ * never in repo checkouts/dev/test, UAI_TELEMETRY_DISABLED=1 kills it,
+ * UAI_SENTRY_DSN overrides it.
+ */
+export const DEFAULT_HOST_DSN =
+  "https://f1b34b8b7df6f7ee519500fd06faa872@o4511765849178112.ingest.us.sentry.io/4511768446369792";
+
+export type HostDsnSource = "disabled" | "explicit" | "default" | "none";
+
+/**
+ * Pure resolution of the telemetry contract above — unit-tested. The baked
+ * DEFAULT applies only to INSTALLED hosts: a repo checkout
+ * (UAI_AGENT_FROM_REPO) or an explicit dev/test NODE_ENV never
+ * default-activates — the consent claim is "installed product telemetry",
+ * not "developing the repo phones home". An explicit UAI_SENTRY_DSN is
+ * always honored.
+ */
+export function resolveHostDsn(env: {
+  UAI_TELEMETRY_DISABLED?: string;
+  UAI_SENTRY_DSN?: string;
+  NODE_ENV?: string;
+  UAI_AGENT_FROM_REPO?: string;
+  UAI_LAUNCHED_FROM_REPO?: string;
+}): { dsn: string | null; source: HostDsnSource } {
+  if (env.UAI_TELEMETRY_DISABLED === "1") {
+    return { dsn: null, source: "disabled" };
+  }
+  if (env.UAI_SENTRY_DSN) {
+    return { dsn: env.UAI_SENTRY_DSN, source: "explicit" };
+  }
+  // UAI_LAUNCHED_FROM_REPO is stamped by src/load-env.ts from its own
+  // filesystem position (review finding: real dev launches — root
+  // `pnpm host-agent`, desktop non-packaged — set none of the explicit
+  // flags). The explicit flags remain as overrides/belt.
+  const repoOrDev =
+    env.NODE_ENV === "development" ||
+    env.NODE_ENV === "test" ||
+    env.UAI_AGENT_FROM_REPO === "1" ||
+    env.UAI_AGENT_FROM_REPO === "true" ||
+    env.UAI_LAUNCHED_FROM_REPO === "1";
+  if (DEFAULT_HOST_DSN && !repoOrDev) {
+    return { dsn: DEFAULT_HOST_DSN, source: "default" };
+  }
+  return { dsn: null, source: "none" };
+}
+
+/**
+ * The disclosure text, single-sourced: the service start log line and the
+ * `uai-host install` / `pair` / `setup` / `start` / `restart` stdout all
+ * print exactly this. Says what is TRUE, no more: crash reports carry a
+ * pseudonymous hostId tag ("anonymous" would overclaim), OS/runtime
+ * versions ride along, and error text is scrubbed for secret shapes but
+ * pattern scrubbing cannot recognize arbitrary prose — the residual-risk
+ * stance documented in docs/observability.md, mirrored here instead of a
+ * "never" the implementation can't fully guarantee.
+ */
+export const TELEMETRY_NOTICE =
+  "crash reporting is ON by default for installed hosts. Sent on a crash " +
+  "only: the error and stack trace (paths + secret-shaped strings " +
+  "redacted), recent bridge-connection breadcrumbs, OS/runtime versions, " +
+  "agent version, and a pseudonymous host id — no sessions, no usage " +
+  "pings, no request data, and telemetry is designed to exclude chat, " +
+  "prompts, env values, and repo content (error text is scrubbed, but " +
+  "redaction is pattern-based, not perfect). Disable any time: " +
+  "UAI_TELEMETRY_DISABLED=1 in the host's .env.local.";
+
+/**
+ * Persisted disclosure gate (review): the baked DEFAULT only activates
+ * after the notice has actually been SHOWN once on this machine — a service
+ * silently upgraded via reboot/KeepAlive never sees a terminal, so it stays
+ * off until the next interactive `uai-host` command (or the desktop
+ * first-run dialog, which writes the same marker) discloses and persists.
+ */
+export function telemetryDisclosureMarkerPath(home: string = env.uaiHome): string {
+  return join(home, ".telemetry-disclosed");
+}
+
+export function hasSeenTelemetryDisclosure(home: string = env.uaiHome): boolean {
+  try {
+    return existsSync(telemetryDisclosureMarkerPath(home));
+  } catch {
+    return false;
+  }
+}
+
+/** Best-effort persist; called by the surfaces that PRINT the notice. */
+export function persistTelemetryDisclosure(home: string = env.uaiHome): void {
+  try {
+    mkdirSync(home, { recursive: true });
+    writeFileSync(
+      telemetryDisclosureMarkerPath(home),
+      `${new Date().toISOString()}\n`,
+    );
+  } catch {
+    // Worst case: the notice prints again next time.
+  }
+}
+
+/** Pure gate — unit-tested: the default requires a persisted disclosure. */
+export function defaultActivationAllowed(
+  source: HostDsnSource,
+  disclosureSeen: boolean,
+): boolean {
+  return source !== "default" || disclosureSeen;
+}
+
+/** The notice CLI commands print, or null when the default isn't active. */
+export function telemetryNoticeIfActive(): string | null {
+  return resolveHostDsn(process.env).source === "default"
+    ? TELEMETRY_NOTICE
+    : null;
+}
+
+let initialized = false;
+
+const SUBSTRING_KEY =
+  /(token|secret|password|passwd|credential|authorization|cookie|apikey|api[-_]key|private[-_]?key)/i;
+const EXACT_KEY =
+  /^(prompt|initialprompt|globalcontext|defaultprompt|content|text|body|env|http\.query|url\.query|query|query_string|querystring|search|http\.fragment|url\.fragment|fragment|hash)$/i;
+
+function isSensitiveKey(key: string): boolean {
+  return EXACT_KEY.test(key) || SUBSTRING_KEY.test(key);
+}
+
+const URL_CREDENTIALS_RE = /(\/\/)[^/\s@:]+:[^/\s@]+@/g;
+// ?query OR #fragment tails (fragments carry OAuth implicit tokens) —
+// mirrors lib/obs/scrub.ts.
+const URL_TAIL_RE = /(https?:\/\/[^\s"'<>?#]+)([?#])[^\s"'<>]*/g;
+const RELATIVE_URL_TAIL_RE =
+  /(^|[\s"'`(=])(\/[A-Za-z0-9_\-./~%[\]]*)([?#])[^\s"'<>]*/g;
+const EMAIL_RE = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g;
+const TOKEN_RES: RegExp[] = [
+  /\b(?:sk|rk)-[A-Za-z0-9_-]{16,}\b/g,
+  /\b(?:sk|pk)_(?:live|test)_[A-Za-z0-9]{8,}\b/g,
+  /\bgh[pousr]_[A-Za-z0-9]{16,}\b/g,
+  /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
+  /\bxox[a-z]-[A-Za-z0-9-]{10,}\b/g,
+  /\bwhsec_[A-Za-z0-9]{8,}\b/g,
+  /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]*\b/g,
+  /\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi,
+];
+
+// Identity/repo-metadata rules beyond the cloud mirror — host strings carry
+// operator PATHS: the home dir embeds the username, and task worktree paths
+// embed project slugs (repo-identifying — "no repo data" must hold for
+// stack frames too).
+/**
+ * Separator-agnostic, case-insensitive home matcher (exported for injected-
+ * home tests): Sentry normalizes Windows ESM frame paths to FORWARD slashes,
+ * so an exact `C:\Users\Alice` match left `C:/Users/Alice` unredacted
+ * (review probe), and Windows paths are case-insensitive.
+ */
+export function buildHomePathRe(home: string): RegExp {
+  const pattern = home
+    .split(/[\\/]+/)
+    .filter((seg) => seg !== "")
+    .map((seg) => seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join("[\\\\/]+");
+  // A POSIX home is rooted — the leading separator must be part of the
+  // match, or "/home/op" replaces as "/~". Windows homes ("C:\…") aren't.
+  const lead = /^[\\/]/.test(home) ? "[\\\\/]+" : "";
+  return new RegExp(lead + pattern, "gi");
+}
+
+const HOME_RE = buildHomePathRe(homedir());
+// MCP gateway routes are BEARER-IN-PATH: /t/<token>/<connection-slug>
+// (mcp-gateway.ts). A crash near the gateway put both verbatim into event
+// strings (review receiver) — normalize the whole segment pair.
+const MCP_GATEWAY_PATH_RE = /(\/t\/)[^/\s"'?#]+(\/[^/\s"'?#]+)?/g;
+// Both separator styles: hosts run on Windows too, and a POSIX-only rule
+// left repo slugs intact in win32 paths (review probe).
+const TASK_WORKSPACE_SLUG_RE =
+  /([/\\]tasks[/\\][A-Za-z0-9_-]+[/\\]workspace[/\\])[^/\\\s"']+/g;
+
+export function scrubHostString(value: string): string {
+  let out = value;
+  out = out.replace(URL_CREDENTIALS_RE, "$1[redacted]@");
+  out = out.replace(URL_TAIL_RE, "$1$2[redacted]");
+  out = out.replace(RELATIVE_URL_TAIL_RE, "$1$2$3[redacted]");
+  for (const re of TOKEN_RES) out = out.replace(re, "[redacted]");
+  out = out.replace(EMAIL_RE, "[email]");
+  out = out.replace(HOME_RE, "~");
+  out = out.replace(TASK_WORKSPACE_SLUG_RE, "$1[project]");
+  out = out.replace(MCP_GATEWAY_PATH_RE, "$1[redacted]");
+  return out;
+}
+
+/** URL field sanitizer: drop ?query/#fragment wholesale, then string-scrub. */
+export function scrubHostUrl(url: string): string {
+  const q = url.indexOf("?");
+  const h = url.indexOf("#");
+  const cut = q === -1 ? h : h === -1 ? q : Math.min(q, h);
+  return scrubHostString(
+    cut === -1 ? url : `${url.slice(0, cut)}${url[cut]}[redacted]`,
+  );
+}
+
+/** Mirror of the cloud scrubValue: depth-capped, hostile-proxy-fenced. */
+export function scrubHostValue(value: unknown, depth = 0): unknown {
+  if (typeof value === "string") return scrubHostString(value);
+  if (value === null || typeof value !== "object") return value;
+  if (depth > 8) return "[max-depth]";
+  try {
+    if (Array.isArray(value)) {
+      return value.map((v) => {
+        try {
+          return scrubHostValue(v, depth + 1);
+        } catch {
+          return "[unreadable]";
+        }
+      });
+    }
+    const out: Record<string, unknown> = {};
+    for (const k of Object.keys(value as Record<string, unknown>)) {
+      if (isSensitiveKey(k)) {
+        out[k] = "[scrubbed]";
+        continue;
+      }
+      try {
+        out[k] = scrubHostValue((value as Record<string, unknown>)[k], depth + 1);
+      } catch {
+        out[k] = "[unreadable]";
+      }
+    }
+    return out;
+  } catch {
+    return "[unreadable]";
+  }
+}
+
+interface HostScrubbableBreadcrumb {
+  category?: string;
+  message?: string;
+  data?: Record<string, unknown>;
+}
+
+interface HostScrubbableFrame {
+  filename?: string;
+  abs_path?: string;
+  module?: string;
+}
+
+interface HostScrubbableEvent {
+  message?: string;
+  server_name?: string;
+  transaction?: string;
+  request?: unknown;
+  exception?: {
+    values?: Array<{
+      type?: string;
+      value?: string;
+      stacktrace?: { frames?: HostScrubbableFrame[] };
+    }>;
+  };
+  extra?: Record<string, unknown>;
+  contexts?: Record<string, Record<string, unknown> | undefined>;
+  breadcrumbs?: HostScrubbableBreadcrumb[];
+}
+
+/** The exact beforeSend hook Sentry runs — exported for regression tests. */
+export function scrubHostEvent<T extends HostScrubbableEvent>(event: T): T {
+  // The SDK stamps os.hostname() ("Diogos-Mac-Studio.local") as server_name
+  // — identifying, and exactly what the pseudonymous hostId tag replaces.
+  delete event.server_name;
+  // MINIMAL CONTRACT (review): request context and transaction names are
+  // DROPPED wholesale, not sanitized. The MCP gateway is bearer-in-path
+  // (/t/<token>/<slug>), and per-field scrubbing left the token verbatim in
+  // both `transaction` and `request.url`, plus mcp-session-id in headers —
+  // the disclosed payload is the error, not the route that raised it.
+  delete event.request;
+  delete event.transaction;
+  if (typeof event.message === "string") {
+    event.message = scrubHostString(event.message);
+  }
+  if (event.exception?.values) {
+    for (const ex of event.exception.values) {
+      if (typeof ex.value === "string") ex.value = scrubHostString(ex.value);
+      // Stack frame paths ride the operator's home dir (username) and task
+      // worktree slugs (repo names) — string-scrub them frame by frame.
+      for (const frame of ex.stacktrace?.frames ?? []) {
+        if (typeof frame.filename === "string") {
+          frame.filename = scrubHostString(frame.filename);
+        }
+        if (typeof frame.abs_path === "string") {
+          frame.abs_path = scrubHostString(frame.abs_path);
+        }
+        if (typeof frame.module === "string") {
+          frame.module = scrubHostString(frame.module);
+        }
+      }
+    }
+  }
+  if (event.extra) {
+    event.extra = scrubHostValue(event.extra) as Record<string, unknown>;
+  }
+  if (event.contexts) {
+    // Allow-list, not scrub: the SDK's environment-derived system context
+    // (device, app, culture, cloud resource) exceeds the disclosed "error +
+    // stack trace + host id + version". Keep only what crash triage needs.
+    const pruned: NonNullable<HostScrubbableEvent["contexts"]> = {};
+    const os = event.contexts.os;
+    if (os) pruned.os = { name: os.name, version: os.version };
+    const runtime = event.contexts.runtime;
+    if (runtime) {
+      pruned.runtime = { name: runtime.name, version: runtime.version };
+    }
+    if (event.contexts.trace) {
+      pruned.trace = scrubHostValue(event.contexts.trace) as Record<
+        string,
+        unknown
+      >;
+    }
+    event.contexts = pruned as T["contexts"];
+  }
+  if (Array.isArray(event.breadcrumbs)) {
+    // Bridge-only is ENFORCED here too, not just at beforeBreadcrumb: any
+    // crumb already sitting on the event (added before init hooks, or by a
+    // future integration) is allow-listed away (review probe: a native
+    // `http` crumb carrying a private repo URL shipped unchanged).
+    event.breadcrumbs = event.breadcrumbs
+      .filter((crumb) => crumb?.category === "bridge")
+      .map((crumb) => scrubHostBreadcrumb(crumb))
+      .filter((crumb): crumb is NonNullable<typeof crumb> => crumb !== null);
+  }
+  return event;
+}
+
+/**
+ * The exact beforeBreadcrumb hook Sentry runs — exported for tests.
+ * FAIL-CLOSED allow-list (review): only the curated `bridge` category
+ * exists in this telemetry; anything else — whatever integration or code
+ * path produced it — is dropped, then the survivor is scrubbed.
+ */
+export function scrubHostBreadcrumb<T extends HostScrubbableBreadcrumb>(
+  crumb: T,
+): T | null {
+  if (crumb.category !== "bridge") return null;
+  if (typeof crumb.message === "string") {
+    crumb.message = scrubHostString(crumb.message);
+  }
+  if (crumb.data) {
+    crumb.data = scrubHostValue(crumb.data) as Record<string, unknown>;
+  }
+  return crumb;
+}
+
+/**
+ * The exact Sentry.init options — exported pure for tests, because "errors
+ * only" is a checkable claim, not a vibe: release-health sessions send an
+ * envelope AT INIT (review probe caught it) and client reports are another
+ * non-crash egress; both are off, so nothing leaves until a crash.
+ */
+export function buildHostInitOptions(args: {
+  dsn: string;
+  version?: string;
+}): Sentry.NodeOptions {
+  return {
+    dsn: args.dsn,
+    // A service install has no NODE_ENV — that's the PRODUCTION case for a
+    // host (review finding: installs were labelled "development"). Explicit
+    // dev/test envs still label themselves; SENTRY_ENVIRONMENT overrides.
+    environment:
+      process.env.SENTRY_ENVIRONMENT ||
+      (process.env.NODE_ENV === "development" || process.env.NODE_ENV === "test"
+        ? process.env.NODE_ENV
+        : "production"),
+    release: args.version,
+    tracesSampleRate: 0,
+    sendDefaultPii: false,
+    sendClientReports: false,
+    // With tracing off the SDK still injects sentry-trace/baggage headers
+    // (public key, release, environment) into ORDINARY outbound HTTP —
+    // metadata third parties the host talks to shouldn't receive.
+    tracePropagationTargets: [],
+    // "strict" preserves today's semantics: an unhandled rejection still
+    // takes the process down (service manager restarts) — Sentry's default
+    // "warn" mode would silently keep a possibly-wedged host alive.
+    // Console breadcrumbs are DROPPED (header comment) — host console
+    // carries unboundable third-party output. ProcessSession is DROPPED —
+    // it is the init-time session envelope that falsified "errors only".
+    // Modules is DROPPED — the full dependency inventory is data the
+    // disclosure doesn't cover and debugging doesn't need. ContextLines is
+    // DROPPED — the disclosure promises "error and stack trace", and
+    // source-line excerpts exceed that.
+    // Http is REMOVED ENTIRELY, not reconfigured. Every retained slice of it
+    // broke the minimal contract in review probes: default incoming-session
+    // tracking sent a `sessions` envelope on a plain GET; outbound
+    // breadcrumbs shipped completed request URLs; and — unfixable by hooks —
+    // inbound `sentry-trace`/`baggage` TRACE CONTINUATION copies
+    // attacker-controlled public_key/release/environment/user_segment/
+    // transaction into the ENVELOPE HEADER, which beforeSend never sees.
+    // With request/transaction context already discarded, http
+    // instrumentation carries no payload value for crash-only reporting.
+    // NodeFetch goes with it for the same minimal contract: it adds fetch
+    // breadcrumbs (outbound request data) and is the undici half of trace
+    // propagation. No http-layer instrumentation remains on either module.
+    integrations: (defaults) => [
+      ...defaults.filter(
+        (i) =>
+          i.name !== "Console" &&
+          i.name !== "ProcessSession" &&
+          i.name !== "Modules" &&
+          i.name !== "ContextLines" &&
+          i.name !== "Http" &&
+          i.name !== "NodeFetch",
+      ),
+      Sentry.onUnhandledRejectionIntegration({ mode: "strict" }),
+    ],
+    beforeSend: (event) => scrubHostEvent(event),
+    beforeBreadcrumb: (crumb) => scrubHostBreadcrumb(crumb),
+  };
+}
+
+export function initHostObs(opts: { version?: string } = {}): void {
+  if (initialized) return;
+  const { dsn, source } = resolveHostDsn(process.env);
+  if (!dsn) return;
+  if (!defaultActivationAllowed(source, hasSeenTelemetryDisclosure())) {
+    console.log(
+      "[host-agent] crash reporting is pending disclosure — it stays OFF until the notice has been shown (`uai-host install`/`pair`/`setup`/`start`/`restart`, or the desktop first run)",
+    );
+    return;
+  }
+
+  Sentry.init(buildHostInitOptions({ dsn, version: opts.version }));
+  initialized = true;
+  if (source === "default") {
+    // The disclosure half of default-on: every start says what leaves the
+    // machine and how to turn it off (same text the install/pair CLIs print).
+    console.log(`[host-agent] ${TELEMETRY_NOTICE}`);
+  } else {
+    console.log("[host-agent] sentry crash reporting enabled (UAI_SENTRY_DSN)");
+  }
+}
+
+export function hostObsEnabled(): boolean {
+  return initialized;
+}
+
+/** Tag every future event with this host's id (safe to call repeatedly). */
+export function setHostObsTag(hostId: string): void {
+  if (!initialized) return;
+  Sentry.setTag("hostId", hostId);
+}
+
+/**
+ * Bridge-lifecycle context for the next crash. No-op when disabled. The
+ * category is NARROWED to the allow-listed literal — the hooks drop
+ * everything else, so a wider signature would only invite silent losses.
+ */
+export function addHostBreadcrumb(
+  category: "bridge",
+  message: string,
+  data?: Record<string, unknown>,
+): void {
+  if (!initialized) return;
+  Sentry.addBreadcrumb({ category, message, data, level: "info" });
+}
+
+/** Explicit capture for caught-but-fatal paths. No-op when disabled. */
+export function captureHostError(
+  err: unknown,
+  extra?: Record<string, unknown>,
+): void {
+  if (!initialized) return;
+  Sentry.captureException(err, extra ? { extra } : undefined);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.8.16",
+  "version": "0.8.17",
   "description": "Uai host — runs ephemeral AI coding tasks in Docker on a machine you control.",
   "license": "MIT",
   "author": "Diogo Perillo <diogo.perillo@gmail.com>",
@@ -66,6 +66,7 @@
     "uai-host": "tsx src/cli.ts"
   },
   "dependencies": {
+    "@sentry/node": "^10.66.0",
     "better-sqlite3": "^11.3.0",
     "dotenv": "^16.4.5",
     "drizzle-orm": "^0.36.0",

package/src/cli.ts

@@ -27,6 +27,10 @@ import { dirname } from "node:path";
 
 import { ulid } from "ulid";
 
+import {
+  persistTelemetryDisclosure,
+  telemetryNoticeIfActive,
+} from "../lib/obs";
 import { envLocalPath, serviceLogPath, uaiHome, uiPortFilePath } from "./paths";
 import { CloudResponse, StatusResponse, TasksResponse } from "./ui/types";
 import type { InstallContext, Installer } from "../scripts/install/types";
@@ -322,6 +326,7 @@ async function cmdSetup(rest: string[]): Promise<void> {
     return;
   }
   console.log(green("✓ enrolled") + dim(` — config written to ${envLocalPath()}`));
+  printTelemetryNotice();
   console.log("");
   console.log("Start the host:");
   console.log(cyan("  uai-host install && uai-host start") + dim("   (first time)"));
@@ -342,6 +347,7 @@ async function cmdPair(token: string | undefined): Promise<void> {
   upsertEnvLocal("UAI_HOST_TOKEN", token);
   console.log(green("paired") + dim(` — wrote UAI_HOST_TOKEN to ${envLocalPath()}`));
   console.log(dim("apply it: uai-host restart  (or start the service)"));
+  printTelemetryNotice();
 }
 
 function upsertEnvLocal(key: string, value: string): void {
@@ -361,15 +367,41 @@ function upsertEnvLocal(key: string, value: string): void {
 // --- install dispatch -------------------------------------------------------
 
 async function cmdInstall(dryRun: boolean): Promise<void> {
+  // Disclosure BEFORE activation (review): install starts the service, and
+  // the notice must precede the first telemetry-armed run.
+  if (!dryRun) printTelemetryNotice();
   const installer = await loadInstaller();
   await installer.install(installContext(dryRun));
-  if (!dryRun) console.log(green("installed") + dim(" — start it: uai-host start"));
+  if (!dryRun) {
+    console.log(green("installed") + dim(" — start it: uai-host start"));
+  }
+}
+
+/**
+ * ADR-071 default-on disclosure at the surfaces an operator actually SEES:
+ * the service's own start line only reaches host.out.log/journald, so the
+ * interactive commands (install/pair/setup/start/restart) print it — and
+ * PERSIST the shown-once marker that gates the baked default (a silently
+ * upgraded service stays off until one of these runs).
+ */
+function printTelemetryNotice(): void {
+  const notice = telemetryNoticeIfActive();
+  if (notice) {
+    console.log(yellow("telemetry: ") + notice);
+    persistTelemetryDisclosure();
+  }
 }
 
 async function cmdInstaller(
   action: "uninstall" | "start" | "stop" | "restart",
   dryRun: boolean,
 ): Promise<void> {
+  // Upgrade path (review finding): operators of EXISTING installs meet
+  // default-on telemetry through start/restart — disclose BEFORE the
+  // service action activates anything, and persist the gate marker.
+  if (!dryRun && (action === "start" || action === "restart")) {
+    printTelemetryNotice();
+  }
   const installer = await loadInstaller();
   await installer[action](dryRun);
   if (!dryRun && action === "uninstall") console.log(green("uninstalled"));

package/src/load-env.ts

@@ -3,16 +3,37 @@
  * read environment variables.
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { config as dotenvConfig } from "dotenv";
+
 const proc = process as unknown as {
   loadEnvFile?: (path: string) => void;
 };
 
-const here = dirname(fileURLToPath(import.meta.url)); // <pkg>/src
+// Real path, not the import path: pnpm workspace links reach this file via
+// symlinks — a repo checkout must resolve to the checkout, and an installed
+// tarball to its true node_modules location.
+const here = (() => {
+  const raw = dirname(fileURLToPath(import.meta.url)); // <pkg>/src
+  try {
+    return realpathSync(raw);
+  } catch {
+    return raw;
+  }
+})();
+
+// An INSTALLED copy always lives under a node_modules directory. Without
+// this guard, a tarball installed beneath some user's pnpm workspace that
+// happens to contain a sibling host-agent/ dir was mistaken for this source
+// checkout — suppressing telemetry AND selecting the wrong UAI_HOME
+// (review finding). Packaged desktop resources contain no node_modules
+// segment and no workspace above them; the repo checkout contains neither
+// problem.
+const installedCopy = here.split(sep).includes("node_modules");
 
 // Resolve the same UAI_HOME as lib/env.ts, but independently: this module runs
 // FIRST (before lib/env is imported) so it can't depend on it. .env.local is
@@ -28,22 +49,44 @@ function findUp(start: string, pred: (dir: string) => boolean): string | null {
   }
 }
 
-const repoRoot = findUp(
-  here,
-  (d) =>
-    existsSync(resolve(d, "pnpm-workspace.yaml")) &&
-    existsSync(resolve(d, "host-agent")),
-);
+const repoRoot = installedCopy
+  ? null
+  : findUp(
+      here,
+      (d) =>
+        existsSync(resolve(d, "pnpm-workspace.yaml")) &&
+        existsSync(resolve(d, "host-agent")),
+    );
 
 const uaiHome = process.env.UAI_HOME
   ? resolve(process.env.UAI_HOME.replace(/^~(?=\/|$)/, homedir()))
   : (repoRoot ?? resolve(homedir(), ".uai"));
 
+// ADR-071: expose the repo-checkout detection computed above to the
+// telemetry gate (lib/obs resolveHostDsn). `pnpm host-agent` from a fresh
+// checkout and host-desktop's non-packaged dev launch set neither NODE_ENV
+// nor UAI_AGENT_FROM_REPO — this marker is the signal tied to the REAL
+// launch path, so dev runs never default-activate crash reporting. Packaged
+// installs (npm tarball, desktop resources) have no workspace file above
+// them and stay unmarked.
+if (repoRoot && !process.env.UAI_LAUNCHED_FROM_REPO) {
+  process.env.UAI_LAUNCHED_FROM_REPO = "1";
+}
+
 for (const file of [".env.local", ".env"]) {
   const path = join(uaiHome, file);
-  if (!proc.loadEnvFile || !existsSync(path)) continue;
+  if (!existsSync(path)) continue;
   try {
-    proc.loadEnvFile(path);
+    if (proc.loadEnvFile) {
+      proc.loadEnvFile(path);
+    } else {
+      // process.loadEnvFile landed in Node 20.12; the package supports
+      // >=20. Silently skipping .env.local on 20.0–20.11 would ignore
+      // UAI_TELEMETRY_DISABLED — the telemetry kill switch MUST load on
+      // every supported Node, so fall back to dotenv (already a dep).
+      // Neither loader overrides pre-set process.env — same semantics.
+      dotenvConfig({ path });
+    }
   } catch (err) {
     console.warn(
       `[host-agent] could not load ${file}: ${(err as Error).message}`,

package/src/main.ts

@@ -45,6 +45,7 @@ import {
 } from "../lib/host-env";
 import { handleMcpOp } from "../lib/mcp-connections";
 import { startMcpGateway } from "../lib/mcp-gateway";
+import { addHostBreadcrumb, initHostObs, setHostObsTag } from "../lib/obs";
 import {
   packageVersion,
   serviceLogPath,
@@ -89,6 +90,11 @@ import {
   FilesOpInput,
 } from "./protocol";
 
+// Crash reporting (ADR-071) — default-ON for installed hosts via the baked
+// DSN (lib/obs.ts); repo checkouts and dev/test never default-activate.
+// UAI_TELEMETRY_DISABLED=1 turns it off; UAI_SENTRY_DSN overrides.
+initHostObs({ version: packageVersion() });
+
 const PING_INTERVAL_MS = 15_000;
 const DEAD_AFTER_MS = 45_000;
 // Reconnect backoff, capped low (~15s) on purpose: cloud deploys drop the
@@ -268,6 +274,8 @@ function connect(): void {
     reconnectAttempt = 0;
     markConnected();
     console.log(`[host-agent] connected as ${hostId}`);
+    setHostObsTag(hostId);
+    addHostBreadcrumb("bridge", "connected");
 
     unsubscribe = hostEvents.subscribe((event) => {
       if (socket.readyState !== WebSocket.OPEN) return;
@@ -446,6 +454,11 @@ function connect(): void {
     console.warn(
       `[host-agent] disconnected${ready ? "" : " before auth"}; reconnecting in ${Math.round(delay)}ms`,
     );
+    addHostBreadcrumb("bridge", "disconnected", {
+      code,
+      authed: ready,
+      retryInMs: Math.round(delay),
+    });
     setTimeout(connect, delay);
   });
 }