@mochi.js/core 0.3.0 → 0.6.0

package/src/default-profile.ts

@@ -0,0 +1,112 @@
+/**
+ * Auto-pick the host-OS-matching profile when `LaunchOptions.profile` is
+ * omitted (task 0272). The function below is the pure decision table the
+ * launcher consults; tests stub `(platform, arch)` and assert the mapping
+ * without spinning a Chromium.
+ *
+ * ## Why
+ *
+ * Task 0271 documents the strategic thesis: spoofing Windows from a Linux
+ * server is the wrong default. Linux is a real-user signal, not a bot
+ * signal. WAFs trained on real traffic do not penalize Linux UAs because
+ * Linux desktops are massively overrepresented in high-LTV segments
+ * (developers, engineers, researchers). The signal was always
+ * `HeadlessChrome`, never Linux.
+ *
+ * Lifting host-OS-matching from "user types `profile: 'linux-chrome-stable'`
+ * by hand" into a default removes the entire class of "user accidentally
+ * spoofed Windows from a Linux DC and looked weird to the WAF" failures —
+ * the same argument that drove `detectLinuxServerEnv` for headless mode in
+ * task 0259.
+ *
+ * ## Mapping
+ *
+ * The host pairs `(process.platform, process.arch)` we currently support:
+ *
+ *   - `linux/x64`     → `linux-chrome-stable`
+ *   - `darwin/arm64`  → `mac-m4-chrome-stable`
+ *   - `darwin/x64`    → `mac-chrome-stable`
+ *   - `win32/x64`     → `windows-chrome-stable`
+ *
+ * Everything else (linux/arm64, freebsd, alpine-musl detection, win32/arm64,
+ * etc.) returns `null` — the launcher then throws with a precise diagnostic
+ * listing the six explicit profile IDs and a pointer to the
+ * choose-your-profile guide. We never silently fall back to a placeholder.
+ *
+ * ## Caveat — darwin/x64
+ *
+ * The current profile catalog (`packages/profiles/data/`) ships
+ * `mac-chrome-stable` as a darwin/arm64 capture (its `os.arch === "arm64"`
+ * in `profile.json`). The mapping above still routes darwin/x64 to
+ * `mac-chrome-stable` per task 0272's success criteria; users on Intel Macs
+ * who want a strict arch match should pass `profile` explicitly until an
+ * `mac-intel-chrome-stable` capture lands.
+ *
+ * @see tasks/0271-the-linux-os-thesis.md — the strategic thesis + evidence
+ * @see tasks/0272-host-os-profile-auto-default.md — engineering brief
+ */
+
+import type { ProfileId } from "./launch";
+
+/**
+ * Pure decision table: given the current host's `(process.platform,
+ * process.arch)` pair, return the profile id that best matches the host
+ * OS axis. Returns `null` for unsupported hosts so the launcher can throw
+ * with a precise diagnostic.
+ *
+ * No I/O, no logging — call sites can introspect the value cheaply (e.g.
+ * `console.log(mochi.defaultProfileForHost())`).
+ */
+export function defaultProfileForHost(): ProfileId | null {
+  return resolveDefaultProfileForHost(process.platform, process.arch);
+}
+
+/**
+ * Internal pure resolver, exposed so the unit tests can drive the table
+ * without stubbing global `process`. Mirrors the precedence-table style of
+ * `resolveHeadlessMode` (task 0258).
+ *
+ * @internal
+ */
+export function resolveDefaultProfileForHost(
+  platform: NodeJS.Platform,
+  arch: string,
+): ProfileId | null {
+  if (platform === "linux" && arch === "x64") return "linux-chrome-stable";
+  if (platform === "darwin" && arch === "arm64") return "mac-m4-chrome-stable";
+  if (platform === "darwin" && arch === "x64") return "mac-chrome-stable";
+  if (platform === "win32" && arch === "x64") return "windows-chrome-stable";
+  return null;
+}
+
+/**
+ * The six real-device profile IDs that `defaultProfileForHost` can return,
+ * surfaced by the launcher's failure-mode diagnostic. Order matches the
+ * task 0272 brief verbatim so the user-facing message is stable.
+ *
+ * @internal
+ */
+export const EXPLICIT_PROFILE_IDS = [
+  "mac-m4-chrome-stable",
+  "mac-chrome-stable",
+  "mac-chrome-beta",
+  "windows-chrome-stable",
+  "linux-chrome-stable",
+  "mac-brave-stable",
+] as const satisfies readonly ProfileId[];
+
+/**
+ * Build the precise diagnostic emitted when `profile` is omitted on an
+ * unsupported host. Format pinned by task 0272 — keep stable so docs +
+ * LLM-context blocks stay correct.
+ *
+ * @internal
+ */
+export function unsupportedHostMessage(platform: NodeJS.Platform, arch: string): string {
+  const list = EXPLICIT_PROFILE_IDS.map((id) => `  - ${id}`).join("\n");
+  return (
+    `[mochi] launch: no profile supplied and no host-matching default for ` +
+    `platform=${platform} arch=${arch}. Pick one explicitly:\n${list}\n` +
+    `See https://mochijs.com/docs/guides/choose-your-profile for the decision aid.`
+  );
+}

package/src/index.ts

@@ -19,6 +19,13 @@ export {
   type SendOptions,
   type Unsubscribe,
 } from "./cdp/router";
+// Auto-pick host-OS-matching profile when `LaunchOptions.profile` is omitted
+// (task 0272 — paired with the strategic thesis in task 0271).
+export {
+  defaultProfileForHost,
+  EXPLICIT_PROFILE_IDS,
+  resolveDefaultProfileForHost,
+} from "./default-profile";
 // Error surface.
 export { NotImplementedError } from "./errors";
 // Exit-IP / TZ / locale reconciliation (task 0262, PLAN.md §9).
@@ -40,16 +47,33 @@ export {
   mochi,
   type ProfileId,
   type ProxyConfig,
+  resolveHeadlessMode,
 } from "./launch";
+// Linux-server environment detection. Pure helpers for users who want to
+// introspect what mochi inferred (and override `headlessMode` from there).
+// Task 0258 — `mochi.detectLinuxServerEnv()` calls `probeLinuxServerEnv`.
+export {
+  detectLinuxServerEnv,
+  type LinuxServerEnv,
+  type LinuxServerProbes,
+  probeLinuxServerEnv,
+  snapshotProbes,
+} from "./linux-server";
 export {
+  ALL_BROWSER_PERMISSIONS,
+  type BrowserPermission,
   type Cookie,
+  type DomStorage,
+  type DomStorageOptions,
   type GotoOptions,
+  type GrantAllPermissionsOptions,
   type HumanClickOptions,
   type HumanMoveOptions,
   type HumanScrollOptions,
   type HumanTypeOptions,
   Page,
   type PageInit,
+  type ScreenshotOptions,
   type WaitForOptions,
   type WaitState,
   type WaitUntil,
@@ -58,5 +82,13 @@ export { ElementHandle, type ElementHandleInit } from "./page/element-handle";
 // Proxy URL parsing — exported so tests + downstream tools can normalize
 // proxy strings without going through `launch()`.
 export { type ParsedProxy, parseProxyUrl } from "./proxy-auth";
-export { Session, type SessionInit, type StorageSnapshot } from "./session";
+export {
+  COOKIE_JAR_FORMAT_VERSION,
+  type CookieJar,
+  type CookieJarFile,
+  type CookieJarOptions,
+  Session,
+  type SessionInit,
+  type StorageSnapshot,
+} from "./session";
 export { VERSION } from "./version";

package/src/launch.ts

@@ -12,8 +12,10 @@
 
 import { deriveMatrix, type ProfileV1 } from "@mochi.js/consistency";
 import { resolveBinary } from "./binary";
+import { defaultProfileForHost, unsupportedHostMessage } from "./default-profile";
 import { type GeoConsistencyMode, reconcileGeoConsistency } from "./geo-consistency";
 import { probeExitGeo } from "./geo-probe";
+import { type LinuxServerEnv, probeLinuxServerEnv } from "./linux-server";
 import { spawnChromium } from "./proc";
 import { parseProxyUrl } from "./proxy-auth";
 import { Session } from "./session";
@@ -85,10 +87,70 @@ export interface ChallengeLaunchOptions {
  *     flows — never enable in production.
  */
 export interface LaunchOptions {
-  profile: ProfileId | ProfileV1;
+  /**
+   * Profile to derive the fingerprint matrix from. Either a `ProfileId`
+   * string (looked up against `KNOWN_PROFILE_IDS`) or an inline `ProfileV1`
+   * object.
+   *
+   * **Optional since task 0272** — when omitted, mochi auto-picks the
+   * profile whose declared OS matches the host's `process.platform` /
+   * `process.arch` pair via {@link defaultProfileForHost}:
+   *
+   *   - `linux/x64`     → `linux-chrome-stable`
+   *   - `darwin/arm64`  → `mac-m4-chrome-stable`
+   *   - `darwin/x64`    → `mac-chrome-stable`
+   *   - `win32/x64`     → `windows-chrome-stable`
+   *
+   * On any unsupported host (FreeBSD, Linux arm64 today, Windows arm64,
+   * Alpine musl), launch throws with a precise diagnostic listing the six
+   * explicit profile IDs the user can choose from. The default never
+   * silently overrides an explicit choice.
+   *
+   * Strategic rationale: a Linux server defaulting to a Linux profile
+   * removes the entire class of "user accidentally spoofed Windows from a
+   * Linux DC and looked weird to the WAF" failures. Linux is a real-user
+   * signal, not a bot signal — see `concepts/stealth-philosophy` for the
+   * thesis + production evidence.
+   */
+  profile?: ProfileId | ProfileV1;
   seed: string;
   proxy?: string | ProxyConfig;
+  /**
+   * Legacy boolean knob — `true` runs Chromium under `--headless=new`,
+   * `false` (default in v0.1) runs headful. New code should prefer
+   * {@link headlessMode}, which is more expressive AND env-aware.
+   *
+   * Resolution priority (task 0258):
+   *
+   *   1. `headlessMode` if set.
+   *   2. Else `headless: true → "new"`, `headless: false → "off"`.
+   *   3. Else env-aware default — Linux without DISPLAY / WAYLAND_DISPLAY
+   *      auto-resolves to `"new"` (the common server case); everywhere else
+   *      defaults to `"off"` (headful, requires a display).
+   */
   headless?: boolean;
+  /**
+   * Headless dispatch mode (task 0258). One of:
+   *
+   *   - `"new"`    — modern Chromium headless (`--headless=new`). Full
+   *                  rendering, near-byte-identical to headful for
+   *                  fingerprinting. The right default on a server.
+   *   - `"legacy"` — legacy `--headless` (no `=new`). Separate, more-
+   *                  detectable code path; only useful for parity with
+   *                  older tooling. Documented but not recommended.
+   *   - `"off"`    — run headful. Requires a real display server (DISPLAY
+   *                  on X11, WAYLAND_DISPLAY on Wayland) or xvfb.
+   *
+   * When unset, mochi infers the default from the live env: Linux without
+   * DISPLAY / WAYLAND_DISPLAY → `"new"`; otherwise `"off"`. The legacy
+   * `headless: boolean` knob (when set) overrides the env default but is
+   * itself overridden by an explicit `headlessMode`.
+   *
+   * Use `mochi.detectLinuxServerEnv()` to introspect what mochi inferred.
+   *
+   * @see docs/getting-started/linux-server.md
+   */
+  headlessMode?: "new" | "legacy" | "off";
   binary?: string;
   args?: string[];
   out?: { traceDir?: string };
@@ -203,8 +265,27 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
   // are resolved against a placeholder profile until `@mochi.js/profiles`
   // ships its first capture (phase 0.4). The matrix is bit-stable per
   // `(profile, seed)` excluding the `derivedAt` timestamp.
-  const profile = resolveProfile(opts.profile);
-  const matrix = deriveMatrix(profile, opts.seed);
+  //
+  // Task 0272 — when `profile` is omitted, auto-pick the host-OS-matching
+  // profile id. Throws with a precise diagnostic if the host is one of the
+  // unsupported ones (FreeBSD, Linux arm64 today, Windows arm64, Alpine
+  // musl). Explicit `profile:` always wins; the auto-pick never overrides.
+  const profileSource = resolveProfileSource(opts.profile);
+  const matrix = deriveMatrix(profileSource.profile, opts.seed);
+  if (profileSource.autoPicked) {
+    // One info-level log line so users can see what mochi inferred without
+    // calling `defaultProfileForHost()` themselves. Wording is pinned by
+    // task 0272 — keep stable so docs + LLM-context blocks stay correct.
+    // (Routed through `console.warn` to match the existing diagnostic
+    // channel for `geoConsistency` / Linux-server inference; `console.info`
+    // is gated by the workspace lint config — `noConsole` only allows
+    // `error` and `warn` at the moment.)
+    console.warn(
+      `[mochi] no profile supplied; auto-picked ${profileSource.id} for host ` +
+        `${process.platform}/${process.arch}. To override: pass ` +
+        `profile: "${profileSource.id}" explicitly.`,
+    );
+  }
 
   // Task 0262 — exit-IP / TZ / locale reconciliation.
   //
@@ -237,10 +318,36 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
     }
   }
 
+  // Resolve headless dispatch BEFORE the spawn call so we can log the
+  // env-derived default and let the user introspect via
+  // `mochi.detectLinuxServerEnv()`. Task 0258 — the "Linux server, no
+  // DISPLAY" case is the common deployment failure mode for `mochi.launch()`,
+  // and the previous default (`opts.headless ?? false` → headful) crashed
+  // immediately on a fresh Ubuntu / Debian host because there was no display
+  // to attach to. We now infer `"new"` on that environment.
+  const linuxEnv = probeLinuxServerEnv();
+  const resolvedHeadlessMode = resolveHeadlessMode(opts, linuxEnv);
+  if (
+    resolvedHeadlessMode === "new" &&
+    opts.headlessMode === undefined &&
+    opts.headless === undefined
+  ) {
+    // Only chatter when the launcher had to infer (caller said nothing). An
+    // explicit `headlessMode: "new"` from the caller is silent — they know
+    // what they asked for. The container/root signals are surfaced too so
+    // the diagnostic is one log line, not three.
+    console.warn(
+      `[mochi] Linux server detected (no DISPLAY / WAYLAND_DISPLAY) — defaulting to ` +
+        `--headless=new. ${linuxEnv.rationale}. Set headlessMode: "off" to override; ` +
+        `see docs/getting-started/linux-server.md for the xvfb path.`,
+    );
+  }
+
   const proc = await spawnChromium({
     binary,
     extraArgs: opts.args,
     headless: opts.headless ?? false,
+    headlessMode: resolvedHeadlessMode,
     // Opt-out for the auto-no-sandbox-as-root fallback (default: fallback
     // is on so first-run on a Linux server box doesn't crash).
     ...(opts.allowRootWithSandbox === true ? { allowRootWithSandbox: true } : {}),
@@ -306,12 +413,52 @@ export const mochi = {
   version: VERSION,
   /** Launch a browser session. */
   launch,
+  /**
+   * Inspect what mochi would infer about the current process environment for
+   * Linux-server detection (drives `headlessMode` defaulting). Pure read of
+   * `process.platform`, `process.env.DISPLAY`, `process.env.WAYLAND_DISPLAY`,
+   * `process.getuid?.()`, and the container probe paths. Task 0258.
+   */
+  detectLinuxServerEnv: probeLinuxServerEnv,
+  /**
+   * Inspect which profile id `mochi.launch` would auto-pick on the current
+   * host when `profile` is omitted. Pure read of `process.platform` /
+   * `process.arch`. Returns `null` on unsupported hosts — the launcher
+   * throws on that path with a list of explicit profile IDs. Task 0272.
+   *
+   * @see tasks/0271-the-linux-os-thesis.md — the strategic thesis
+   * @see https://mochijs.com/docs/concepts/stealth-philosophy
+   */
+  defaultProfileForHost,
 } as const;
 
 export type Mochi = typeof mochi;
 
 // ---- helpers ----------------------------------------------------------------
 
+/**
+ * Resolve the effective {@link LaunchOptions.headlessMode} given a snapshot
+ * of `(opts, env)`. Pure / synchronous so tests can drive both axes without
+ * stubbing globals. Resolution order — task 0258:
+ *
+ *   1. Explicit `opts.headlessMode` wins.
+ *   2. Else legacy `opts.headless: true | false` maps to `"new"` / `"off"`.
+ *   3. Else env-aware default — Linux without DISPLAY / WAYLAND_DISPLAY →
+ *      `"new"`; otherwise `"off"`.
+ *
+ * Exported so the unit tests can lock the resolution table without spawning
+ * a Chromium or stubbing `process.platform`.
+ */
+export function resolveHeadlessMode(
+  opts: Pick<LaunchOptions, "headless" | "headlessMode">,
+  env: LinuxServerEnv,
+): "new" | "legacy" | "off" {
+  if (opts.headlessMode !== undefined) return opts.headlessMode;
+  if (opts.headless === true) return "new";
+  if (opts.headless === false) return "off";
+  return env.serverNoDisplay ? "new" : "off";
+}
+
 /**
  * Reconcile the two `LaunchOptions.proxy` shapes (URL string and
  * `ProxyConfig` record) into a single normalized record carrying:
@@ -372,14 +519,56 @@ function injectAuth(server: string, auth: { username: string; password: string }
 }
 
 /**
- * Resolve `LaunchOptions.profile` into a concrete `ProfileV1`. Inline
- * profiles flow through unchanged. String profile ids — until
- * `@mochi.js/profiles` ships (phase 0.4) — resolve to a generic placeholder
- * stamped with the id; the consistency engine still produces a real,
- * relationally-locked Matrix from it.
+ * Resolve `LaunchOptions.profile` into a concrete `ProfileV1` plus the
+ * meta-flag the launcher needs to decide whether to log the auto-pick
+ * INFO line. Three branches:
+ *
+ *   1. Explicit `ProfileV1` object — flows through unchanged. `autoPicked`
+ *      false; `id` taken from the inline object.
+ *   2. Explicit `ProfileId` string — same placeholder synthesis as before.
+ *      `autoPicked` false.
+ *   3. `undefined` — task 0272: call `defaultProfileForHost()`. Throw with
+ *      the unsupported-host diagnostic when the resolver returns `null`.
+ *      `autoPicked` true.
+ *
+ * Pure function — does not log. The launcher emits the INFO line itself
+ * after observing `autoPicked === true` so test fixtures can assert the
+ * resolution without intercepting `console`.
+ */
+function resolveProfileSource(profile: ProfileId | ProfileV1 | undefined): {
+  profile: ProfileV1;
+  id: ProfileId;
+  autoPicked: boolean;
+} {
+  if (typeof profile === "object") {
+    return { profile, id: profile.id, autoPicked: false };
+  }
+  if (typeof profile === "string") {
+    return {
+      profile: synthesizePlaceholderProfile(profile),
+      id: profile,
+      autoPicked: false,
+    };
+  }
+  // Auto-pick branch — task 0272.
+  const picked = defaultProfileForHost();
+  if (picked === null) {
+    throw new Error(unsupportedHostMessage(process.platform, process.arch));
+  }
+  return {
+    profile: synthesizePlaceholderProfile(picked),
+    id: picked,
+    autoPicked: true,
+  };
+}
+
+/**
+ * Synthesize a generic placeholder `ProfileV1` from a profile id. Until
+ * `@mochi.js/profiles.getProfile` lands (phase 0.4), the consistency engine
+ * still produces a real, relationally-locked Matrix from this skeleton —
+ * the id is what flows into `sha256(profile.id + seed)`.
  */
-function resolveProfile(profile: ProfileId | ProfileV1): ProfileV1 {
-  if (typeof profile === "object") return profile;
+function synthesizePlaceholderProfile(profile: ProfileId): ProfileV1 {
   return {
     id: profile,
     version: "0.0.0-placeholder",

package/src/linux-server.ts

@@ -0,0 +1,157 @@
+/**
+ * Linux-server environment detection.
+ *
+ * The "common deployment env" failure mode for `mochi.launch()`: a fresh
+ * Ubuntu / Debian server, no DISPLAY, no Wayland — Chromium spawns but cannot
+ * render and either hangs or crashes on the first paint. The fix is to drive
+ * Chromium through `--headless=new` (the modern headless that ships full
+ * rendering and is near-byte-identical to headful for fingerprinting; the
+ * legacy `--headless` is a separate, more-detectable code path).
+ *
+ * This module exposes:
+ *
+ *   - {@link detectLinuxServerEnv} — pure function. Given a snapshot of
+ *     `(platform, env, container probes)`, returns a record describing what
+ *     mochi inferred (Linux-without-display? root? containerised?). Pure /
+ *     synchronous so callers can stub the inputs and unit-test without
+ *     touching `process.*`.
+ *   - {@link DEFAULT_LINUX_SERVER_PROBES} — convenience that snapshots the
+ *     real `process.platform`, `process.env.DISPLAY`,
+ *     `process.env.WAYLAND_DISPLAY`, `process.getuid?.()`, and the container
+ *     filesystem probes (`/.dockerenv`, `/proc/1/cgroup`). Calls
+ *     {@link detectLinuxServerEnv} with that snapshot and returns the result.
+ *
+ * Detection rules:
+ *
+ *   1. `platform === "linux"` AND no `DISPLAY` AND no `WAYLAND_DISPLAY`
+ *      → `serverNoDisplay = true`. This is the load-bearing signal for
+ *      auto-defaulting `headlessMode` to `"new"`.
+ *   2. `getuid?.() === 0` → `root = true`. Orthogonal to #1; drives the
+ *      existing auto-`--no-sandbox` path in `proc.ts` (kept verbatim — this
+ *      module does not own that decision).
+ *   3. `/.dockerenv` exists OR `/proc/1/cgroup` mentions
+ *      `docker | containerd | kubepods` → `container = true`. Tertiary
+ *      signal; surfaced for diagnostics only (a container with DISPLAY set
+ *      is still a "with display" environment).
+ *
+ * @see tasks/0259 (Linux first-run experience)
+ * @see tasks/0258 (Linux server env auto-detection)
+ * @see docs/getting-started/linux-server.md
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+
+/**
+ * Snapshot of the runtime probes that {@link detectLinuxServerEnv} consumes.
+ * Defined as a record (not direct `process.*` reads) so unit tests can stub
+ * each axis independently.
+ */
+export interface LinuxServerProbes {
+  /** `process.platform`. */
+  platform: NodeJS.Platform;
+  /** Value of `process.env.DISPLAY` (X11 display server). */
+  display: string | undefined;
+  /** Value of `process.env.WAYLAND_DISPLAY` (Wayland display server). */
+  waylandDisplay: string | undefined;
+  /** UID, or `undefined` on platforms without a getuid (Windows). */
+  uid: number | undefined;
+  /** `true` when `/.dockerenv` exists. */
+  hasDockerEnvFile: boolean;
+  /**
+   * Contents of `/proc/1/cgroup`, or `undefined` if absent / unreadable.
+   * Container detection scans this for `docker | containerd | kubepods`.
+   */
+  cgroup: string | undefined;
+}
+
+/**
+ * Result returned by {@link detectLinuxServerEnv}. Structured so callers
+ * (the launcher, the diagnostic helper, an end-user calling
+ * `mochi.detectLinuxServerEnv()` directly) can introspect each axis without
+ * re-running the probes.
+ */
+export interface LinuxServerEnv {
+  /** `true` iff Linux + no DISPLAY + no WAYLAND_DISPLAY. */
+  serverNoDisplay: boolean;
+  /** `true` iff the process is running as uid 0 on Linux. */
+  root: boolean;
+  /** `true` iff a container indicator (`/.dockerenv` or cgroup mention) hit. */
+  container: boolean;
+  /** Human-readable rationale string. Intended for `console.debug`. */
+  rationale: string;
+}
+
+/**
+ * Pure, synchronous classifier. Given a `LinuxServerProbes` snapshot, returns
+ * a `LinuxServerEnv` summary. No I/O, no global reads — every input is on the
+ * `probes` argument. Exposed for unit tests AND for users who want to drive
+ * the classification with their own probes (e.g. a CI matrix that wants to
+ * pretend it's running under DISPLAY=:0 to validate a code path).
+ */
+export function detectLinuxServerEnv(probes: LinuxServerProbes): LinuxServerEnv {
+  const isLinux = probes.platform === "linux";
+  const hasDisplay =
+    (probes.display !== undefined && probes.display.length > 0) ||
+    (probes.waylandDisplay !== undefined && probes.waylandDisplay.length > 0);
+  const serverNoDisplay = isLinux && !hasDisplay;
+  const root = isLinux && probes.uid === 0;
+  const container =
+    probes.hasDockerEnvFile ||
+    (probes.cgroup !== undefined && /docker|containerd|kubepods/.test(probes.cgroup));
+
+  const parts: string[] = [];
+  parts.push(`platform=${probes.platform}`);
+  parts.push(`display=${probes.display ?? "(unset)"}`);
+  parts.push(`waylandDisplay=${probes.waylandDisplay ?? "(unset)"}`);
+  parts.push(`uid=${probes.uid ?? "(none)"}`);
+  parts.push(`container=${container}`);
+  parts.push(`serverNoDisplay=${serverNoDisplay}`);
+  const rationale = parts.join(" ");
+
+  return { serverNoDisplay, root, container, rationale };
+}
+
+/**
+ * Snapshot the live process state and run {@link detectLinuxServerEnv}
+ * against it. The convenience entry point used by {@link launch} and the
+ * inspection helper exposed on the public surface (`mochi.detectLinuxServerEnv()`).
+ *
+ * Filesystem probes (`/.dockerenv`, `/proc/1/cgroup`) are guarded with
+ * `existsSync` + a try/catch so the call is safe on macOS / Windows / sandboxed
+ * environments where the paths don't exist.
+ */
+export function probeLinuxServerEnv(): LinuxServerEnv {
+  return detectLinuxServerEnv(snapshotProbes());
+}
+
+/**
+ * Build a {@link LinuxServerProbes} record from the live `process.*` and
+ * filesystem state. Exported so callers debugging an environment-detection
+ * issue can inspect the raw inputs the classifier saw.
+ */
+export function snapshotProbes(): LinuxServerProbes {
+  const platform = process.platform;
+  const display = process.env.DISPLAY;
+  const waylandDisplay = process.env.WAYLAND_DISPLAY;
+  const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+  const hasDockerEnvFile = safeExists("/.dockerenv");
+  const cgroup = safeReadText("/proc/1/cgroup");
+  return { platform, display, waylandDisplay, uid, hasDockerEnvFile, cgroup };
+}
+
+function safeExists(path: string): boolean {
+  try {
+    return existsSync(path);
+  } catch {
+    return false;
+  }
+}
+
+function safeReadText(path: string): string | undefined {
+  try {
+    if (!existsSync(path)) return undefined;
+    return readFileSync(path, "utf8");
+  } catch {
+    return undefined;
+  }
+}