@runuai/host 0.8.13 → 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/codex-auth.ts

@@ -9,12 +9,24 @@
  * re-login otherwise only helps NEW tasks. This re-copies the fresh `~/.codex`
  * into the running task containers so live tasks self-heal.
  *
- * Two triggers, covering both re-login paths:
+ * Three triggers, covering every path:
  *   - {@link watchCodexAuth} — fs.watch on `~/.codex`, for `codex login` run
  *     from a terminal while the host stays up.
  *   - {@link reinjectCodexRunningTasks} at host start — for the desktop
  *     "Connect Codex" flow, which writes `~/.codex` then restarts the host
  *     (durable sessions reattach to containers that still hold the old creds).
+ *     Sequenced AFTER boot recovery (main.ts awaits recoveryComplete()).
+ *   - {@link injectCodexIntoContainer} — recovery calls it right after
+ *     `docker start` of an exited container, before agents can respawn.
+ *
+ * Copies go ONLY into containers docker confirms are RUNNING. A DB-active row
+ * can be a stopped container (boot, pre-recovery), and `docker cp` into a
+ * stopped container SUCCEEDS while the `docker exec … chown` that follows
+ * cannot run — stranding auth.json/config.toml mode 0600 owned by the host
+ * uid (macOS 501:20), unreadable to the container's `node` (1000:1000), and
+ * Codex dies at startup. Every docker step's exit status is checked; failures
+ * surface as actionable errors (never credential contents — only file NAMES
+ * and docker stderr are logged).
  *
  * Codex auth is host-wide (the operator's single `~/.codex`, not per-user), so
  * this targets ALL running tasks — matching task-up, which copies it into every
@@ -43,8 +55,11 @@ const EXEC_TIMEOUT_MS = 15_000;
 /** Injectable seams (defaults hit the real DB / docker / fs) so the copy logic
  *  is testable without either. */
 export interface CodexDeps {
-  exec?: (args: string[]) => Promise<{ status: number | null; stderr: string }>;
-  runningContainers?: () => string[];
+  exec?: (
+    args: string[],
+  ) => Promise<{ status: number | null; stdout: string; stderr: string }>;
+  /** DB-active task containers — may include stopped ones; docker decides. */
+  activeTaskContainers?: () => string[];
   fileExists?: (path: string) => boolean;
 }
 
@@ -54,10 +69,10 @@ function ownerCodexDir(): string {
 
 const defaultExec: NonNullable<CodexDeps["exec"]> = async (args) => {
   const res = await dockerCli(args, { timeoutMs: EXEC_TIMEOUT_MS });
-  return { status: res.status, stderr: res.stderr };
+  return { status: res.status, stdout: res.stdout, stderr: res.stderr };
 };
 
-function defaultRunningContainers(): string[] {
+function defaultActiveTaskContainers(): string[] {
   return getDb()
     .select({ taskId: schema.hostTasks.taskId })
     .from(schema.hostTasks)
@@ -66,50 +81,119 @@ function defaultRunningContainers(): string[] {
     .map((r) => `task-${r.taskId}-app-1`);
 }
 
+/**
+ * The containers docker reports as RUNNING right now, or null when docker
+ * itself didn't answer — the caller must then skip injection rather than
+ * docker-cp into containers of unknown state.
+ */
+async function dockerRunningNames(
+  exec: NonNullable<CodexDeps["exec"]>,
+): Promise<Set<string> | null> {
+  const res = await exec(["ps", "--filter", "status=running", "--format", "{{.Names}}"]);
+  if (res.status !== 0) return null;
+  return new Set(
+    res.stdout
+      .split("\n")
+      .map((l) => l.trim())
+      .filter(Boolean),
+  );
+}
+
 /**
  * Re-copy `~/.codex/<items>` into one container — mirrors task-up.sh exactly:
- * ensure the dir (root), cp each item that exists, chown back to node. Best
- * effort; a stopped/removed container makes the exec fail and is caught by the
- * caller.
+ * ensure the dir (root), cp each item that exists, chown back to node:node
+ * (docker cp preserves the HOST uid/gid, and 0600 files owned by macOS
+ * 501:20 are unreadable to the container's node). Any nonzero step throws
+ * with the step name and docker's stderr — never file contents.
  */
 async function copyCodexInto(container: string, deps: CodexDeps): Promise<void> {
   const exec = deps.exec ?? defaultExec;
   const exists = deps.fileExists ?? existsSync;
   const dir = ownerCodexDir();
-  await exec(["exec", "-u", "root", container, "mkdir", "-p", "/home/node/.codex"]);
+  const must = async (args: string[], step: string): Promise<void> => {
+    const res = await exec(args);
+    if (res.status !== 0) {
+      const detail = res.stderr.trim().slice(0, 200);
+      throw new Error(
+        `${step} failed (${res.status === null ? "docker timeout" : `exit ${res.status}`})` +
+          (detail ? `: ${detail}` : ""),
+      );
+    }
+  };
+  await must(
+    ["exec", "-u", "root", container, "mkdir", "-p", "/home/node/.codex"],
+    "mkdir /home/node/.codex",
+  );
   for (const item of CODEX_ITEMS) {
     const src = join(dir, item);
     if (!exists(src)) continue;
-    await exec(["cp", src, `${container}:/home/node/.codex/`]);
+    await must(["cp", src, `${container}:/home/node/.codex/`], `docker cp ${item}`);
   }
-  await exec([
-    "exec",
-    "-u",
-    "root",
-    container,
-    "chown",
-    "-R",
-    "node:node",
-    "/home/node/.codex",
-  ]);
+  await must(
+    ["exec", "-u", "root", container, "chown", "-R", "node:node", "/home/node/.codex"],
+    "chown -R node:node /home/node/.codex",
+  );
 }
 
 /**
- * Re-copy the freshly (re)logged-in `~/.codex` into every running task
- * container on this host. No-op when there is no `~/.codex/auth.json` (nothing
- * to inject) or no running tasks. Best-effort per container.
+ * Inject the owner's `~/.codex` into ONE container known to be running.
+ * Recovery calls this immediately after `docker start`, BEFORE uai-init and
+ * any agent respawn, so a recovered container never runs Codex against
+ * host-uid-owned credentials. Returns false after logging an actionable
+ * error (no secrets) — recovery of the task itself must not fail over Codex.
+ */
+export async function injectCodexIntoContainer(
+  container: string,
+  deps: CodexDeps = {},
+): Promise<boolean> {
+  const exists = deps.fileExists ?? existsSync;
+  if (!exists(join(ownerCodexDir(), "auth.json"))) return true; // nothing to inject
+  try {
+    await copyCodexInto(container, deps);
+    return true;
+  } catch (err) {
+    console.error(
+      `[codex] inject into ${container}: ${err instanceof Error ? err.message : err} — ` +
+        `Codex in this task will fail until fixed (run: docker exec -u root ${container} ` +
+        `chown -R node:node /home/node/.codex, or restart the host)`,
+    );
+    return false;
+  }
+}
+
+/**
+ * Re-copy the freshly (re)logged-in `~/.codex` into every task container that
+ * is both DB-active AND confirmed running by docker. No-op when there is no
+ * `~/.codex/auth.json` or no active tasks; skipped entirely (with a warning)
+ * when docker doesn't answer. Per-container failures are surfaced and don't
+ * stop the sweep.
  */
 export async function reinjectCodexRunningTasks(deps: CodexDeps = {}): Promise<void> {
   const exists = deps.fileExists ?? existsSync;
   if (!exists(join(ownerCodexDir(), "auth.json"))) return;
-  const containers = (deps.runningContainers ?? defaultRunningContainers)();
-  if (containers.length === 0) return;
-  console.log(`[codex] re-copying ~/.codex into ${containers.length} running task(s)`);
-  for (const container of containers) {
+  const active = (deps.activeTaskContainers ?? defaultActiveTaskContainers)();
+  if (active.length === 0) return;
+  const running = await dockerRunningNames(deps.exec ?? defaultExec);
+  if (running === null) {
+    console.warn(
+      "[codex] reinject skipped — docker didn't answer `docker ps`; will retry on the next trigger",
+    );
+    return;
+  }
+  const targets = active.filter((c) => running.has(c));
+  const stopped = active.length - targets.length;
+  if (stopped > 0) {
+    console.log(
+      `[codex] ${stopped} active task(s) not running — skipped (recovery injects them at docker start)`,
+    );
+  }
+  if (targets.length === 0) return;
+  console.log(`[codex] re-copying ~/.codex into ${targets.length} running task(s)`);
+  for (const container of targets) {
     try {
       await copyCodexInto(container, deps);
     } catch (err) {
-      console.warn(
+      console.error(
         `[codex] reinject into ${container} failed: ${err instanceof Error ? err.message : err}`,
       );
     }

package/lib/engines.ts

@@ -63,6 +63,7 @@ import {
   chmodSync,
   existsSync,
   mkdirSync,
+  readdirSync,
   readFileSync,
   rmSync,
   writeFileSync,
@@ -88,6 +89,11 @@ export interface EngineCatalogEntry {
   apiKeyHint: string | null;
   /** Where to mint a key for the pasted-API-key alternative. */
   apiKeyUrl: string | null;
+  /**
+   * Human-readable install command the UI shows next to "Install & connect"
+   * when the CLI is missing (null = nothing to install, e.g. Cursor).
+   */
+  installHint: string | null;
 }
 
 interface EngineDescriptor {
@@ -240,18 +246,43 @@ function defaultPtyWrap(bin: string, args: string[]): PtyCommand | null {
 }
 
 /**
- * The PATH the owner's login shell exports. Runs `/usr/bin/env` (not
+ * The PATH the owner's shell exports. Probes an INTERACTIVE login shell
+ * first: nvm/asdf/fnm put their PATH setup in `.zshrc`/`.bashrc`, which a
+ * plain login shell (`-lc`) never sources — that gap hid `npm i -g` installs
+ * from the probe. Falls back to `-lc` for profiles that misbehave when run
+ * interactively without a terminal. Null on failure of both; callers fall
+ * back to the inherited PATH.
+ *
+ * Cached (module-level, 5 min): the CLI-found statuses probe on every
+ * /api/engines poll and shelling out each time would be rude. Staleness is
+ * harmless — every installer this module runs lands in a candidate dir,
+ * which is checked before the probe.
+ */
+async function probeLoginShellPath(): Promise<string | null> {
+  const now = Date.now();
+  if (loginPathCache && now - loginPathCache.at < LOGIN_PATH_CACHE_MS) {
+    return loginPathCache.value;
+  }
+  const value = (await shellPath("-lic")) ?? (await shellPath("-lc"));
+  loginPathCache = { value, at: now };
+  return value;
+}
+
+let loginPathCache: { value: string | null; at: number } | null = null;
+const LOGIN_PATH_CACHE_MS = 5 * 60_000;
+
+/**
+ * Run `$SHELL <flags> /usr/bin/env` and pull PATH out. `/usr/bin/env` (not
  * `echo $PATH`) so the value is the real colon-joined exported PATH under any
- * shell — fish's `$PATH` is a list and would echo space-joined — and takes the
- * LAST `PATH=` line so profile echo noise can't spoof it. Null on any failure;
- * callers fall back to the inherited PATH.
+ * shell — fish's `$PATH` is a list and would echo space-joined — and the
+ * LAST `PATH=` line wins so profile echo noise can't spoof it.
  */
-function probeLoginShellPath(): Promise<string | null> {
+function shellPath(flags: string): Promise<string | null> {
   return new Promise((resolve) => {
     const shell = process.env.SHELL?.trim() || "/bin/zsh";
     nodeExecFile(
       shell,
-      ["-lc", "/usr/bin/env"],
+      [flags, "/usr/bin/env"],
       { timeout: 8_000 },
       (err, stdout) => {
         if (err) return resolve(null);
@@ -285,10 +316,22 @@ export function engineCatalog(): EngineCatalogEntry[] {
       getKeyUrl: d.getKeyUrl ?? null,
       apiKeyHint: d.apiKeyHint ?? null,
       apiKeyUrl: d.apiKeyUrl ?? null,
+      installHint:
+        kind === "codex" ? CODEX_INSTALL_HINT : (INSTALLERS[kind] ?? null),
     };
   });
 }
 
+/** kind → whether the engine's CLI is resolvable on this host right now. */
+export async function engineCliStatuses(
+  seams: Partial<EngineSeams> = {},
+): Promise<Record<EngineKind, boolean>> {
+  const s = withDefaults(seams);
+  const out = {} as Record<EngineKind, boolean>;
+  for (const kind of ORDER) out[kind] = await engineCliFound(kind, s);
+  return out;
+}
+
 /** kind → connected, for every engine. */
 export function engineStatuses(
   seams: Partial<EngineSeams> = {},
@@ -474,6 +517,209 @@ export function disconnectEngine(
   }
 }
 
+// ---------------------------------------------------------------------------
+// Install a missing engine CLI (ADR-074).
+// ---------------------------------------------------------------------------
+
+/**
+ * Pinned installer one-liners — the same vendor installers the standard task
+ * image already trusts (host-agent/images/standard/Dockerfile), shown
+ * VERBATIM in the UI before running. Every one lands its binary in a
+ * candidateBins dir, so the next resolve finds it with no restart:
+ * claude → ~/.local/bin, kimi → ~/.kimi-code/bin, grok → ~/.grok/bin.
+ * Codex has no vendor script — resolved at run time (brew, then npm).
+ */
+const INSTALLERS: Partial<Record<EngineKind, string>> = {
+  claude: "curl -fsSL https://claude.ai/install.sh | bash",
+  kimi: "curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash",
+  grok: "curl -fsSL https://x.ai/cli/install.sh | bash",
+};
+
+const CODEX_INSTALL_HINT = "brew install codex — or: npm i -g @openai/codex";
+
+/** Installers can compile/download; give them real time. */
+const INSTALL_TIMEOUT_MS = 15 * 60_000;
+
+export interface InstallResult {
+  ok: boolean;
+  message: string;
+}
+
+/**
+ * Install an engine's CLI with its pinned installer, streaming output to
+ * `onLog`. Refuses when there's nothing to install (api-key engines) and
+ * short-circuits when the CLI is already resolvable. Success = the installer
+ * exits 0 AND the CLI resolves afterwards.
+ */
+export async function installEngineCli(
+  kind: EngineKind,
+  onLog: (line: string) => void,
+  seams: Partial<EngineSeams> = {},
+): Promise<InstallResult> {
+  const s = withDefaults(seams);
+  const d = DESCRIPTORS[kind];
+  if (d.authMode === "api-key") {
+    return {
+      ok: false,
+      message: `${d.label} doesn't use a CLI on the host — paste an API key instead.`,
+    };
+  }
+  if (await engineCliFound(kind, s)) {
+    return { ok: true, message: `${d.label} CLI is already installed.` };
+  }
+  const inv = await resolveInstaller(kind, s);
+  if (!inv) {
+    return {
+      ok: false,
+      message:
+        "No way to install Codex automatically: install Homebrew or Node.js first, then `brew install codex` or `npm i -g @openai/codex`.",
+    };
+  }
+  let child: ChildProcess;
+  try {
+    child = s.spawn(inv.command, inv.args, {
+      ...s.procEnv,
+      ...(inv.path ? { PATH: inv.path } : {}),
+    });
+  } catch (err) {
+    return { ok: false, message: err instanceof Error ? err.message : String(err) };
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer: NodeJS.Timeout | undefined;
+    const done = (r: InstallResult, kill = false): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (kill) {
+        try {
+          child.kill();
+        } catch {
+          /* already gone */
+        }
+      }
+      resolve(r);
+    };
+    const relay = createLineRelay(onLog);
+    child.stdout?.on("data", relay);
+    child.stderr?.on("data", relay);
+    child.on("error", (err: NodeJS.ErrnoException) =>
+      done({ ok: false, message: err.message }),
+    );
+    child.on("exit", (code) => {
+      void (async () => {
+        if (code !== 0) {
+          done({
+            ok: false,
+            message: `Install failed (exit ${code ?? "?"}) — see the log above.`,
+          });
+          return;
+        }
+        done(
+          (await engineCliFound(kind, s))
+            ? { ok: true, message: `${d.label} CLI installed.` }
+            : {
+                ok: false,
+                message:
+                  "The installer finished but the CLI still isn't findable — install it manually, then try Connect.",
+              },
+        );
+      })();
+    });
+    timer = setTimeout(
+      () =>
+        done(
+          { ok: false, message: "The installer timed out — see the log above." },
+          true,
+        ),
+      INSTALL_TIMEOUT_MS,
+    );
+  });
+}
+
+interface InstallInvocation {
+  command: string;
+  args: string[];
+  /** Child PATH override (npm needs its own dir leading so node resolves). */
+  path?: string;
+}
+
+/** Vendor script via sh for most engines; brew-then-npm for Codex. */
+async function resolveInstaller(
+  kind: EngineKind,
+  s: EngineSeams,
+): Promise<InstallInvocation | null> {
+  if (kind !== "codex") {
+    const script = INSTALLERS[kind];
+    return script ? { command: "/bin/sh", args: ["-c", script] } : null;
+  }
+  const brew = s.systemBinDirs.map((dir) => join(dir, "brew")).find(existsSync);
+  if (brew) return { command: brew, args: ["install", "codex"] };
+  const npm = await findBinNamed("npm", s);
+  if (npm) {
+    return {
+      command: npm,
+      args: ["install", "-g", "@openai/codex"],
+      path: prependPath([dirname(npm)], s.procEnv.PATH ?? ""),
+    };
+  }
+  return null;
+}
+
+/** Find an arbitrary tool the same way engine CLIs are found. */
+async function findBinNamed(
+  name: string,
+  s: EngineSeams,
+): Promise<string | null> {
+  const home = s.ownerHome();
+  const dirs = [
+    join(home, ".local", "bin"),
+    ...nodeManagerBinDirs(home),
+    ...s.systemBinDirs,
+  ];
+  for (const dir of dirs) {
+    const file = join(dir, name);
+    if (existsSync(file)) return file;
+  }
+  const login = await s.loginShellPath();
+  const dir = login?.split(":").find((p) => p && existsSync(join(p, name)));
+  return dir ? join(dir, name) : null;
+}
+
+/** Whether an engine's CLI resolves right now (candidates, then login PATH). */
+async function engineCliFound(
+  kind: EngineKind,
+  s: EngineSeams,
+): Promise<boolean> {
+  if (DESCRIPTORS[kind].authMode === "api-key") return true; // never spawned
+  if (candidateBins(kind, s).some(existsSync)) return true;
+  const login = await s.loginShellPath();
+  return !!login
+    ?.split(":")
+    .some((dir) => dir.length > 0 && existsSync(join(dir, kind)));
+}
+
+/**
+ * Accumulate a child's output and forward each distinct, meaningful,
+ * COMPLETE line to `onLog` once — same discipline as the token flow's
+ * relay, for plain (non-PTY) installer output with \r progress noise.
+ */
+function createLineRelay(onLog: (line: string) => void): (b: Buffer) => void {
+  let raw = "";
+  const forwarded = new Set<string>();
+  return (b) => {
+    raw += b.toString("utf8");
+    if (raw.length > 262_144) raw = raw.slice(-131_072);
+    const text = sanitizeTerminalOutput(raw);
+    for (const line of significantLines(text.slice(0, text.lastIndexOf("\n") + 1))) {
+      if (!forwarded.has(line)) {
+        forwarded.add(line);
+        onLog(line);
+      }
+    }
+  };
+}
+
 /**
  * Flatten a PTY byte stream into plain text lines. Strips OSC sequences
  * (incl. OSC-8 hyperlink wrappers, keeping their visible text), CSI
@@ -571,14 +817,21 @@ function configPath(kind: EngineKind, s: EngineSeams): string {
  */
 function candidateBins(kind: EngineKind, s: EngineSeams): string[] {
   const home = s.ownerHome();
-  const common = [join(home, ".local", "bin"), ...s.systemBinDirs];
+  const common = [
+    join(home, ".local", "bin"),
+    ...nodeManagerBinDirs(home),
+    ...s.systemBinDirs,
+  ];
   switch (kind) {
     case "claude":
       // Native installer symlinks ~/.local/bin/claude (preferred); the older
       // "local install" migration keeps a wrapper at ~/.claude/local/claude.
-      return [join(home, ".local", "bin"), join(home, ".claude", "local"), ...s.systemBinDirs].map(
-        (d) => join(d, "claude"),
-      );
+      return [
+        join(home, ".local", "bin"),
+        join(home, ".claude", "local"),
+        ...nodeManagerBinDirs(home),
+        ...s.systemBinDirs,
+      ].map((d) => join(d, "claude"));
     case "codex":
       return common.map((d) => join(d, "codex"));
     case "kimi":
@@ -592,6 +845,50 @@ function candidateBins(kind: EngineKind, s: EngineSeams): string[] {
   }
 }
 
+/**
+ * Bin dirs of the common node version managers — `npm i -g` lands CLIs here,
+ * and none of these are on a GUI PATH or even in a NON-interactive login
+ * shell's PATH (their init lives in .zshrc/.bashrc), which is exactly how an
+ * installed `codex` still read "not found". Deterministic dirs beat shell
+ * probing: no subprocess, no profile side effects.
+ */
+function nodeManagerBinDirs(home: string): string[] {
+  const dirs = [
+    join(home, ".asdf", "shims"), // shims exec asdf by absolute path
+    join(home, ".volta", "bin"),
+    join(home, ".bun", "bin"),
+    join(home, ".npm-global", "bin"),
+    // fnm's stable default-alias bin — the per-shell multishell paths its
+    // shell init exports are ephemeral. macOS, XDG, and legacy layouts.
+    join(home, "Library", "Application Support", "fnm", "aliases", "default", "bin"),
+    join(home, ".local", "share", "fnm", "aliases", "default", "bin"),
+    join(home, ".fnm", "aliases", "default", "bin"),
+  ];
+  // nvm has no stable "current" symlink — enumerate installed versions,
+  // newest first (numeric compare: lexicographic would put v9 over v22).
+  // A version dir's bin also holds its `node`, so the shebang of whatever
+  // we find there resolves against the same dir once it leads PATH.
+  try {
+    const versions = join(home, ".nvm", "versions", "node");
+    dirs.push(
+      ...readdirSync(versions)
+        .sort(compareVersionDesc)
+        .map((v) => join(versions, v, "bin")),
+    );
+  } catch {
+    /* no nvm */
+  }
+  return dirs;
+}
+
+function compareVersionDesc(a: string, b: string): number {
+  const parts = (s: string): number[] =>
+    s.replace(/^v/, "").split(".").map((n) => parseInt(n, 10) || 0);
+  const [a1 = 0, a2 = 0, a3 = 0] = parts(a);
+  const [b1 = 0, b2 = 0, b3 = 0] = parts(b);
+  return b1 - a1 || b2 - a2 || b3 - a3;
+}
+
 interface ResolvedBin {
   /** Command to spawn — absolute when found, else the bare name. */
   bin: string;

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);