@mochi.js/core 0.3.0 → 0.8.0

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** — 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:
+   *
+   *   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. 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 };
@@ -116,7 +178,7 @@ export interface LaunchOptions {
    * trivially fingerprinted as Chromium-for-Testing.
    *
    * Defaults to `false`. PLAN.md §12.1 (capture must run against bare
-   * Chromium); task 0040.
+   * Chromium);
    */
   bypassInject?: boolean;
   /**
@@ -137,7 +199,7 @@ export interface LaunchOptions {
    *
    * Pairs with — but is independent of — {@link bypassInject}. Capture
    * flows set both `true`; harness conformance runs set `hermetic: true`
-   * with full inject pipeline active. PLAN.md §8.6 + task 0256.
+   * with full inject pipeline active. PLAN.md §8.6 +
    */
   hermetic?: boolean;
   /**
@@ -173,13 +235,13 @@ export interface LaunchOptions {
    * - `"off"` — skip the probe entirely. Use in offline tests / when
    *   the probe service is rate-limited.
    *
-   * The probe is a single GET through wreq (using the matrix's
-   * `wreqPreset`, so the geo service sees the same JA4/headers as user
-   * traffic). 4-attempt cap, 2s per endpoint. Probe results are NOT
-   * cached across sessions — proxy IPs rotate.
+   * The probe is a single GET through Chromium itself (Session.fetch via
+   * CDP `Network.loadNetworkResource`), so the geo service sees the same
+   * JA4 / headers as user traffic by definition. 4-attempt cap, 2s per
+   * endpoint. Probe results are NOT cached across sessions — proxy IPs
+   * rotate.
    *
    * @see PLAN.md §9 (relational consistency, IP/TZ/Locale axis)
-   * @see tasks/0262-ip-tz-locale-exit-consistency.md
    */
   geoConsistency?: GeoConsistencyMode;
 }
@@ -193,8 +255,8 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
   const normalized = normalizeProxy(opts.proxy);
 
   // Resolve the `MatrixV1` BEFORE spawning so matrix-derived values flow
-  // into both the `--lang` flag (task 0251) and `--window-size` flag
-  // (task 0252). The matrix is otherwise read post-spawn for inject;
+  // into both the `--lang` flag and `--window-size` flag
+  //. The matrix is otherwise read post-spawn for inject;
   // deriving early is cheap (~µs, pure function) and lets us close the
   // I-5 leaks between Chromium's native network/OS-window state and the
   // JS-layer spoof.
@@ -203,14 +265,34 @@ 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
+    // — 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.
   //
-  // Probe the apparent exit IP through the configured proxy (using wreq
-  // with the matrix's `wreqPreset` so the geo service sees the same JA4
-  // / headers as user traffic). Then cross-reference against
+  // Probe the apparent exit IP through the configured proxy. Post-0.7
+  // the probe runs through Chromium itself (Session.fetch via CDP
+  // `Network.loadNetworkResource`), so the geo service sees the same
+  // JA4 / headers as user traffic by definition. Cross-reference against
   // `(matrix.timezone, matrix.locale)` and apply `geoConsistency`. The
   // adjusted matrix flows into BOTH `spawnChromium` (so `--lang` reflects
   // any override) AND `Session` (so inject + the CDP `Emulation.set
@@ -222,7 +304,7 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
   let adjustedMatrix = matrix;
   if (geoMode !== "off") {
     const geo = await probeExitGeo({
-      ...(normalized?.netProxy !== undefined ? { proxy: normalized.netProxy } : {}),
+      ...(normalized?.proxy !== undefined ? { proxy: normalized.proxy } : {}),
       matrix,
     });
     // Strict mode throws GeoMismatchError on real mismatch; let it
@@ -237,10 +319,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 } : {}),
@@ -252,13 +360,13 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
     // multi-locale list still flows through `matrix.languages` to the
     // inject layer's `navigator.languages` spoof; Chromium derives the
     // q-weighted `Accept-Language` value from the single `--lang` primary
-    // automatically. Task 0251.
+    // automatically.
     locale: adjustedMatrix.locale,
     // Pin OS-level outer window from the matrix's display geometry so
     // `window.outerWidth/outerHeight` (which reads from the OS window,
     // NOT the JS-spoofed `screen.*`) matches the spoof. Closes the
     // `fingerprint-scan.com` 800×600 leak under `--headless=new`.
-    // UDC fixes the same issue at `__init__.py:410-411`. Task 0252.
+    // UDC fixes the same issue at `__init__.py:410-411`.
     //
     // (`adjustedMatrix.display` === `matrix.display` since geo reconcile
     // only touches timezone/locale/languages — but we use the adjusted
@@ -288,10 +396,11 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
     seed: opts.seed,
     ...(opts.timeout !== undefined ? { defaultTimeoutMs: opts.timeout } : {}),
     ...(opts.bypassInject === true ? { bypassInject: true } : {}),
-    // Forward the same proxy (with auth, if any) to the net FFI so
-    // out-of-band Session.fetch traffic shares the apparent egress.
-    // `@mochi.js/net` (wreq) accepts the full `user:pass@host` URL form.
-    ...(normalized !== undefined ? { netProxy: normalized.netProxy } : {}),
+    // Proxy auth is the only piece that needs explicit Session-side
+    // wiring (the `--proxy-server` flag is already on Chromium's command
+    // line above). Out-of-band `Session.fetch` traffic rides Chromium's
+    // network stack post-0.7, so it inherits the `--proxy-server` egress
+    // automatically — no per-call proxy URL needed.
     ...(normalized?.auth !== undefined ? { proxyAuth: normalized.auth } : {}),
     ...(opts.challenges !== undefined ? { challenges: opts.challenges } : {}),
   });
@@ -306,19 +415,59 @@ 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.
+   */
+  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.
+   *
+   * @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:
  *   - `server`: auth-stripped URL safe to feed `--proxy-server=`.
- *   - `netProxy`: the URL handed to the network FFI. Preserves credentials
- *     (wreq accepts `user:pass@host` inline) so out-of-band fetches
- *     authenticate against the same proxy.
+ *   - `proxy`: the auth-stripped URL forwarded to the geo-probe so it
+ *     can record the egress on diagnostics. (Kept for API parity even
+ *     though the probe now rides Session.fetch + Chromium's network
+ *     stack — i.e. picks up `--proxy-server` automatically.)
  *   - `auth`: parsed credentials for the CDP auth handler. Undefined when
  *     no creds were supplied.
  *
@@ -327,7 +476,7 @@ export type Mochi = typeof mochi;
 function normalizeProxy(p: LaunchOptions["proxy"]):
   | {
       server: string;
-      netProxy: string;
+      proxy: string;
       auth?: { username: string; password: string };
     }
   | undefined {
@@ -337,7 +486,7 @@ function normalizeProxy(p: LaunchOptions["proxy"]):
     const parsed = parseProxyUrl(p);
     return {
       server: parsed.server,
-      netProxy: p,
+      proxy: parsed.server,
       ...(parsed.auth !== undefined ? { auth: parsed.auth } : {}),
     };
   }
@@ -346,40 +495,64 @@ function normalizeProxy(p: LaunchOptions["proxy"]):
   const parsed = parseProxyUrl(p.server);
   const auth =
     p.username !== undefined ? { username: p.username, password: p.password ?? "" } : parsed.auth;
-  // Reconstruct the netProxy URL preserving any explicit auth (wreq path).
-  const netProxy = auth !== undefined ? injectAuth(parsed.server, auth) : parsed.server;
   return {
     server: parsed.server,
-    netProxy,
+    proxy: parsed.server,
     ...(auth !== undefined ? { auth } : {}),
   };
 }
 
 /**
- * Inject `username:password@` into a server URL, percent-encoding both
- * components so reserved characters round-trip cleanly through wreq's URL
- * parser.
+ * 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 injectAuth(server: string, auth: { username: string; password: string }): string {
-  const u = encodeURIComponent(auth.username);
-  const p = encodeURIComponent(auth.password);
-  // server is `<protocol>://<host>:<port>` (per parseProxyUrl).
-  const idx = server.indexOf("://");
-  if (idx < 0) return server;
-  const head = server.slice(0, idx + 3);
-  const tail = server.slice(idx + 3);
-  return `${head}${u}:${p}@${tail}`;
+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 —
+  const picked = defaultProfileForHost();
+  if (picked === null) {
+    throw new Error(unsupportedHostMessage(process.platform, process.arch));
+  }
+  return {
+    profile: synthesizePlaceholderProfile(picked),
+    id: picked,
+    autoPicked: true,
+  };
 }
 
 /**
- * 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.
+ * 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",
@@ -409,7 +582,9 @@ function resolveProfile(profile: ProfileId | ProfileV1): ProfileV1 {
     locale: "en-US",
     languages: ["en-US", "en"],
     behavior: { hand: "right", tremor: 0.18, wpm: 60, scrollStyle: "smooth" },
-    wreqPreset: "chrome_131_linux",
+    // Deprecated — kept for one release for migration; runtime no longer
+    // reads the field. Drops in 0.8.
+    wreqPreset: "chrome_148_linux",
     userAgent:
       "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
     uaCh: {},

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;
+  }
+}

package/src/page/element-handle.ts

@@ -17,7 +17,6 @@
  * which is fine for a v0.2 surface.
  *
  * @see PLAN.md §8.2 / §8.3
- * @see tasks/0253-closed-shadow-piercing-locator.md
  */
 
 import type { MessageRouter } from "../cdp/router";

package/src/page/piercing.ts

@@ -33,7 +33,6 @@
  * brief — a per-page cache layer is a v0.3+ concern).
  *
  * @see PLAN.md §8.2 — `DOM.getDocument` / `DOM.resolveNode` are not forbidden
- * @see tasks/0253-closed-shadow-piercing-locator.md
  */
 
 import type { PierceDomNode } from "../cdp/types";

package/src/page/selector.ts

@@ -31,7 +31,6 @@
  * Throws `SelectorParseError` on syntactically invalid input. The matcher
  * itself never throws — unsupported nodes just don't match.
  *
- * @see tasks/0253-closed-shadow-piercing-locator.md
  * @see PLAN.md §8.2 (forbidden CDP — neither `DOM.getDocument` nor
  *   `DOM.resolveNode` is forbidden; both fine).
  */