cdp-mcp 0.2.1 → 0.4.0

package/dist/util/format.d.ts

@@ -1,20 +0,0 @@
-import type { Protocol } from "devtools-protocol";
-export declare function truncate(s: string, max?: number): string;
-export declare function previewRemoteObject(obj: Protocol.Runtime.RemoteObject): string;
-export declare function describeRemote(obj: Protocol.Runtime.RemoteObject): {
-    type: string;
-    preview: string;
-    objectId?: string;
-};
-export declare function toolText(text: string): {
-    content: {
-        type: "text";
-        text: string;
-    }[];
-};
-export declare function toolJson(value: unknown): {
-    content: {
-        type: "text";
-        text: string;
-    }[];
-};

package/dist/util/format.js

@@ -1,65 +0,0 @@
-const MAX_PREVIEW = 200;
-export function truncate(s, max = MAX_PREVIEW) {
-    if (s.length <= max)
-        return s;
-    return s.slice(0, max) + `…(+${s.length - max} chars)`;
-}
-// Compact textual preview of a CDP RemoteObject without dereferencing further.
-export function previewRemoteObject(obj) {
-    if (obj.unserializableValue)
-        return obj.unserializableValue;
-    if (obj.type === "undefined")
-        return "undefined";
-    if (obj.subtype === "null")
-        return "null";
-    if (obj.type === "string")
-        return JSON.stringify(obj.value ?? "");
-    if (obj.type === "number" || obj.type === "boolean" || obj.type === "bigint") {
-        return String(obj.value);
-    }
-    if (obj.type === "function") {
-        return obj.description ? truncate(obj.description) : "function";
-    }
-    if (obj.preview) {
-        return truncate(previewFromPreview(obj.preview));
-    }
-    if (obj.description)
-        return truncate(obj.description);
-    return obj.className ?? obj.subtype ?? obj.type;
-}
-function previewFromPreview(p) {
-    if (p.subtype === "array") {
-        const items = (p.properties ?? [])
-            .map((pp) => previewProperty(pp))
-            .join(", ");
-        return `[${items}${p.overflow ? ", …" : ""}]`;
-    }
-    const items = (p.properties ?? [])
-        .map((pp) => `${pp.name}: ${previewProperty(pp)}`)
-        .join(", ");
-    const head = p.description && p.description !== "Object" ? `${p.description} ` : "";
-    return `${head}{${items}${p.overflow ? ", …" : ""}}`;
-}
-function previewProperty(p) {
-    if (p.type === "string")
-        return JSON.stringify(p.value ?? "");
-    if (p.value !== undefined)
-        return p.value;
-    return p.type;
-}
-export function describeRemote(obj) {
-    return {
-        type: obj.subtype ?? obj.type,
-        preview: previewRemoteObject(obj),
-        ...(obj.objectId ? { objectId: obj.objectId } : {}),
-    };
-}
-// Wrap any value into the MCP tool content envelope.
-export function toolText(text) {
-    return { content: [{ type: "text", text }] };
-}
-// Stringify a JSON result with a stable shape for the LLM to parse.
-export function toolJson(value) {
-    return toolText(JSON.stringify(value, null, 2));
-}
-//# sourceMappingURL=format.js.map

package/dist/util/format.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/util/format.ts"],"names":[],"mappings":"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"}

package/dist/util/log.d.ts

@@ -1,6 +0,0 @@
-export declare const log: {
-    debug: (msg: string, meta?: Record<string, unknown>) => void;
-    info: (msg: string, meta?: Record<string, unknown>) => void;
-    warn: (msg: string, meta?: Record<string, unknown>) => void;
-    error: (msg: string, meta?: Record<string, unknown>) => void;
-};

package/dist/util/log.js

@@ -1,34 +0,0 @@
-// Logging for an MCP stdio server.
-//
-// stdout is reserved for JSON-RPC framing — anything we write there will
-// corrupt the protocol. All logging goes to stderr.
-const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
-function envLevel() {
-    const raw = process.env.CDP_MCP_LOG?.toLowerCase();
-    if (raw === "debug" || raw === "info" || raw === "warn" || raw === "error")
-        return raw;
-    return "info";
-}
-const threshold = LEVELS[envLevel()];
-function emit(level, msg, meta) {
-    if (LEVELS[level] < threshold)
-        return;
-    const ts = new Date().toISOString();
-    const tail = meta ? " " + safeJson(meta) : "";
-    process.stderr.write(`[${ts}] ${level.toUpperCase()} ${msg}${tail}\n`);
-}
-function safeJson(v) {
-    try {
-        return JSON.stringify(v);
-    }
-    catch {
-        return String(v);
-    }
-}
-export const log = {
-    debug: (msg, meta) => emit("debug", msg, meta),
-    info: (msg, meta) => emit("info", msg, meta),
-    warn: (msg, meta) => emit("warn", msg, meta),
-    error: (msg, meta) => emit("error", msg, meta),
-};
-//# sourceMappingURL=log.js.map

package/dist/util/log.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"log.js","sourceRoot":"","sources":["../../src/util/log.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,EAAE;AACF,yEAAyE;AACzE,oDAAoD;AAIpD,MAAM,MAAM,GAA0B,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AAEnF,SAAS,QAAQ;IACf,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,WAAW,EAAE,CAAC;IACnD,IAAI,GAAG,KAAK,OAAO,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,OAAO;QAAE,OAAO,GAAG,CAAC;IACvF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;AAErC,SAAS,IAAI,CAAC,KAAY,EAAE,GAAW,EAAE,IAA8B;IACrE,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,SAAS;QAAE,OAAO;IACtC,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,KAAK,CAAC,WAAW,EAAE,IAAI,GAAG,GAAG,IAAI,IAAI,CAAC,CAAC;AACzE,CAAC;AAED,SAAS,QAAQ,CAAC,CAAU;IAC1B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB,KAAK,EAAE,CAAC,GAAW,EAAE,IAA8B,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;IAChF,IAAI,EAAE,CAAC,GAAW,EAAE,IAA8B,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC;IAC9E,IAAI,EAAE,CAAC,GAAW,EAAE,IAA8B,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC;IAC9E,KAAK,EAAE,CAAC,GAAW,EAAE,IAA8B,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;CACjF,CAAC"}

package/docs/chromium-sandboxing.md

@@ -1,197 +0,0 @@
-# Chromium sandboxing
-
-**Last updated: 2026-05-16**
-
-This project launches Chromium in two different contexts:
-
-- L3 e2e tests and L4 evals launch a real browser through `launch_chrome`.
-- Agents then control that browser through CDP, including `Runtime.evaluate`,
-  `Debugger.*`, DOM interaction, console inspection, and network inspection.
-
-That makes sandboxing a host setup and threat-model decision, not just a
-Chrome flag. This document is the canonical reference for `--no-sandbox`,
-AppArmor, unprivileged user namespaces, snap confinement, and Bubblewrap.
-
-## Current default
-
-`launch_chrome` defaults to `sandbox: false`, which adds `--no-sandbox`.
-
-The default exists because Ubuntu 23.10+ and 24.04 commonly restrict
-unprivileged user namespaces through AppArmor. Playwright-bundled Chromium
-does not ship with a SUID `chrome_sandbox` helper. On those hosts, launching
-Chromium without `--no-sandbox` can fail before the DevTools port opens:
-
-```text
-zygote_host_impl_linux.cc: No usable sandbox!
-```
-
-From `chrome-launcher`, that often surfaces as a startup port poll timeout or
-`ECONNREFUSED`.
-
-Other Linux distributions may allow Chromium's unprivileged user namespace
-sandbox path by default. Validate the actual host before assuming the Ubuntu
-automation default is necessary there.
-
-Use `sandbox: true` only when the host has a working Chromium sandbox path:
-
-- An AppArmor policy that permits the specific Chromium binary to create the
-  unprivileged user namespace it needs.
-- Or a working SUID `chrome_sandbox` helper installed alongside that binary.
-
-## Why the Chromium sandbox still matters
-
-The MCP caller is already highly privileged relative to the page. It can ask
-the server to evaluate JavaScript, drive the DOM, set breakpoints, inspect
-scopes, and read browser-observed network activity. For that caller, the
-Chromium renderer sandbox is not the primary trust boundary.
-
-The Chromium sandbox still matters for hostile page content and browser
-exploitation risk. With the sandbox enabled, Chromium isolates renderer, GPU,
-and utility child processes from the browser process using mechanisms such as
-namespaces, seccomp filters, brokered filesystem access, and per-process
-capability reduction. With `--no-sandbox`, a compromised renderer has a much
-larger blast radius inside the browser process tree.
-
-So the project default is a pragmatic automation default, not a claim that
-`--no-sandbox` is equally safe.
-
-## How the mechanisms relate
-
-These mechanisms solve different problems:
-
-- Chromium sandbox: Chromium's internal process sandbox. It is the boundary
-  between web content renderer processes and the rest of the browser.
-- AppArmor: host-enforced mandatory access control. It can confine Chromium,
-  and on recent Ubuntu systems it can also restrict whether an unprivileged
-  process may create user namespaces.
-- Snap confinement: the packaging sandbox used by snap-installed Chromium.
-  It can hide or remap filesystem locations and has caused DevTools port and
-  `userDataDir` friction in local runs.
-- Bubblewrap (`bwrap`): a small Linux sandboxing tool that starts a process in
-  new namespaces with a controlled filesystem, process, and optional network
-  view.
-
-Bubblewrap is useful defense-in-depth around a browser or eval job. For
-example, it can run the whole MCP server plus browser process tree with only
-the repository and selected temp/profile directories writable. That helps
-prevent accidental or malicious access to unrelated files such as SSH keys,
-cloud credentials, or the rest of the home directory.
-
-Bubblewrap is not a clean substitute for Chromium's own sandbox. If Chromium
-runs with `--no-sandbox` inside Bubblewrap, the entire browser process tree is
-inside an outer container-like boundary, but Chromium's internal renderer
-isolation is still disabled. A renderer compromise may be contained by the
-outer Bubblewrap filesystem or network policy, but it is not contained in the
-same way as Chromium's per-renderer sandbox.
-
-## Recommended posture
-
-Local development:
-
-- Treat the current default, `sandbox: false`, as a host-capability fallback:
-  it keeps work moving when Chromium sandbox setup is the blocker.
-- Prefer `sandbox: true` once the host has a known-good Chromium sandbox path.
-
-CI and L4 eval hosts:
-
-- Keep the default working and deterministic. If `--no-sandbox` is needed for
-  Playwright-bundled Chromium on Ubuntu, document that in the host setup.
-- Consider running the whole job inside an outer sandbox, VM, container, or
-  Bubblewrap profile with a throwaway browser profile and limited writable
-  paths.
-
-Untrusted browsing:
-
-- Prefer Chromium's sandbox on.
-- Use a throwaway `userDataDir`.
-- Add host-level confinement such as AppArmor, a container, VM, or Bubblewrap.
-- Do not treat `bwrap + --no-sandbox` as equivalent to Chromium sandboxing.
-
-This outer containment also pairs with the agent-operator threat (prompt-injected
-page content steering the agent into actions or unscoped filesystem writes); see
-the agent-operator threat model and deployment hardening in
-[SECURITY.md](../SECURITY.md). A containerized outer-sandbox run mode that would
-make this contained posture the default is a direction under consideration.
-
-## Validated hosts
-
-Hosts where `sandbox: true` has been verified working against this project, with the supporting posture:
-
-| Host | OS | Arch | `sandbox: true` | AppArmor profile | Notes |
-|---|---|---|---|---|---|
-| Ubuntu 24.04 arm64 (Parallels VM) | Ubuntu 24.04 | arm64 | ✓ | `/etc/apparmor.d/cdp-mcp-chromium` (named-unconfined, mirrors Ubuntu's stock `chrome` / `msedge` / `brave`) | `kernel.apparmor_restrict_unprivileged_userns = 0` was set as a side effect of enabling Bubblewrap, so the kernel-level userns restriction is already off system-wide. The AppArmor profile gives Playwright Chromium a stable named label (instead of `unconfined`) and grants `userns,` explicitly, so `sandbox: true` keeps working even if a future kernel/package update flips the global knob back to `1`. |
-
-When adding a new host to this table:
-
-1. Run the smoke tests below and capture the values.
-2. If `kernel.apparmor_restrict_unprivileged_userns` is `1` (Ubuntu's stock default) and `sandbox: true` is desired, install a profile under `/etc/apparmor.d/` mirroring Ubuntu's stock `chrome` / `msedge` / `brave` shape:
-   ```apparmor
-   abi <abi/4.0>,
-   include <tunables/global>
-
-   profile cdp-mcp-chromium /path/to/chromium flags=(unconfined) {
-     userns,
-     include if exists <local/cdp-mcp-chromium>
-   }
-   ```
-   Load with `sudo apparmor_parser -r /etc/apparmor.d/cdp-mcp-chromium`. The profile auto-loads at boot from `/etc/apparmor.d/`.
-3. Verify the running browser process is labelled correctly:
-   ```sh
-   cat /proc/<chromium-pid>/attr/current
-   ```
-   Expect the profile name (e.g. `cdp-mcp-chromium (unconfined)`), not `unconfined` alone.
-4. Add a row to the table above.
-
-Other hosts to characterize as they come online: Fedora — Fedora uses SELinux rather than AppArmor and ships userns enabled by default, so `sandbox: true` is expected to work without host-side profile work. The `dnf install bubblewrap` path is also first-class on Fedora.
-
-## Smoke tests
-
-Check whether unprivileged user namespaces are enabled:
-
-```sh
-cat /proc/sys/kernel/unprivileged_userns_clone
-cat /proc/sys/user/max_user_namespaces
-```
-
-Expected working values are usually `1` for
-`kernel.unprivileged_userns_clone` and a nonzero number for
-`user.max_user_namespaces`.
-
-On Ubuntu, AppArmor may still restrict unprivileged user namespaces:
-
-```sh
-sysctl kernel.apparmor_restrict_unprivileged_userns
-```
-
-Minimal Bubblewrap smoke tests:
-
-```sh
-bwrap --unshare-user --uid 0 --gid 0 --ro-bind / / /usr/bin/true
-bwrap --unshare-user --uid 0 --gid 0 --unshare-net --ro-bind / / /usr/bin/true
-```
-
-If the first command fails with `setting up uid map: Permission denied`, the
-host still blocks the user namespace setup Bubblewrap needs.
-
-If the second command fails with `loopback: Failed RTM_NEWADDR: Operation not
-permitted`, the network namespace setup is still blocked.
-
-Project-level browser check:
-
-```sh
-npm run test:e2e
-```
-
-For a direct MCP check, call `launch_chrome` with `sandbox: true` on the host
-you want to validate. If Chromium cannot create a usable sandbox, it will fail
-before exposing its DevTools target.
-
-## Decision summary
-
-- `--no-sandbox` remains the automation default because it keeps Ubuntu
-  Playwright-Chromium runs working.
-- `sandbox: true` is the preferred security posture when the host supports it.
-- AppArmor is the long-term host policy path for allowing Chromium's needed
-  user namespace behavior narrowly.
-- Bubblewrap is an outer containment layer and is valuable defense-in-depth.
-- Bubblewrap does not replace Chromium's internal renderer sandbox.

package/docs/known-chromium-gaps.md

@@ -1,138 +0,0 @@
-# Known Chromium gaps
-
-Specs in the L3 e2e suite that fail (or fail intermittently) on Chromium but
-pass on Chrome stable. Every entry below is a real coverage gap on Linux
-ARM64 + Chromium (the day-1 primary target) — not a CI-only concession.
-
-If the gap is mitigatable in production code, link the fix PR. If it's a CDP
-protocol-version difference, link the Chromium release that includes the fix.
-
-| Spec | Skip tag | CDP method missing/changed | Chromium version that fixes it | Tracking |
-|---|---|---|---|---|
-| _none yet — populate as L3 lands_ | | | | |
-
-## Pre-flagged risks (not yet observed; documented for triage)
-
-These are known protocol-version-sensitive areas the test+eval plan flagged
-as risky during planning. Add a row above when one of them actually fires
-on the e2e suite.
-
-- **`Network.loadNetworkResource`** — Used by `src/sourcemap/loader.ts:113`
-  to fetch source maps through the browser's network stack (so cookies/
-  origin/auth flow naturally). Older Chromium revisions ship a more limited
-  param set (no `options.includeCredentials`, no `options.disableCache`);
-  the production code already has a Node-fetch fallback, but verify the
-  fallback path is exercised under the older Chromium.
-
-- **`Page.captureScreenshot`** flag set — `captureBeyondViewport` and
-  `quality` (when `format=jpeg`) gained options across versions. The
-  screenshot e2e spec asserts byte-shape, not flag-respect, so this is
-  most likely to surface as a "bytes don't match" assertion under older
-  Chromium.
-
-## Conventions
-
-- Add a `// @chromium-skip — <gap-id>` comment on the spec's `it()` line.
-- Set the spec to `it.skipIf(process.env.CDP_TEST_BROWSER === "chromium")` or
-  use vitest's `.skip` with a runtime check.
-- Every skip MUST have a corresponding row in the table above. **Enforced** by
-  `scripts/check-chromium-skips.mjs` — runs as `pretest:e2e` on every PR and
-  also as `npm run lint:chromium-skips`. Greps `test/e2e/**/*.test.ts` for
-  `@chromium-skip` tags and `it.skipIf`/`describe.skipIf` Chromium guards,
-  parses the table above, exits 1 if any skip lacks a row OR any row points
-  at a spec that no longer exists. Zero-skip state (the current state) is
-  fine — the script is a no-op.
-
-_(no entries below this line yet means no L3 specs needed a Chromium skip)_
-
-## Known host gaps (not Chromium-version issues)
-
-These are host/library combinations where the e2e suite cannot run end-to-
-end, separate from the per-Chromium-version skip mechanism above. Listed
-here so future contributors don't waste a debug cycle.
-
-- **Windows 11 + chrome-launcher 1.2.1.** `chrome-launcher.launch()`'s
-  internal startup-port poll always fails with `ECONNREFUSED` on this Win11
-  configuration, regardless of headless mode (`--headless=new`, classic
-  `--headless`, or non-headless), browser (Chrome stable from Program
-  Files, Playwright-bundled Chromium under `~/AppData/Local/ms-playwright/
-  chromium-XXXX/chrome-win64/chrome.exe`), or how the port is selected
-  (chrome-launcher-managed vs explicit). Spawning `chrome.exe` directly via
-  `Start-Process` and probing `/json/version` over HTTP works fine — only
-  chrome-launcher's launch path fails. The same code works on Linux (CI)
-  and is widely used elsewhere, so this is a Windows-host quirk rather
-  than a cdp-mcp issue. **Workaround**: run L3 changes under WSL2
-  (Ubuntu) or push and let CI validate (but see WSL2 caveat below). Unit
-  + L2 tests work fine on native Windows.
-
-  *Originally hit on agents/l3-impl during PR #11 implementation.
-  Cross-confirmed by Codex reviewer who diagnosed the on-CI failure
-  separately — turned out to be a different root cause (Codex blocker on
-  --remote-debugging-port=0 in chromeFlags overriding chrome-launcher's
-  own port). After that fix, CI on Linux is the live validation; Win11
-  local-host status remains as documented here.*
-
-- **macOS arm64 + system unbranded Chromium (brew cask).** The `chromium`
-  Homebrew cask is **deprecated** ("does not pass the macOS Gatekeeper
-  check; will be disabled 2026-09-01"). Install completes and the wrapper
-  script lands at `/opt/homebrew/bin/chromium`, but on first launch
-  Gatekeeper rejects the `.app` as "damaged" and the binary is unusable
-  for unattended e2e/eval runs. Workaround for darwin-arm64: use Playwright
-  Chrome-for-Testing (`npx playwright install chromium`) — `resolveBrowser`
-  picks it up automatically from `~/Library/Caches/ms-playwright/chromium-
-  <rev>/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/
-  Google Chrome for Testing` (CfT layout added to `pickPlaywrightExe` in
-  the same PR that landed this entry). The resolver also explicitly skips
-  the brew-cask wrapper on darwin (`isBrewCaskChromium`) so users who
-  tried the deprecated cask first — and then turn to Playwright per this
-  entry — fall through to the Playwright cache instead of getting the
-  Gatekeeper-rejected wrapper back from Step 2. Functionally Chromium-
-  channel at a fixed protocol revision, but Google-branded — call it out
-  if your eval needs *unbranded* Chromium. Building Chromium from source
-  on macOS is multi-hour + multi-GB ongoing maintenance; not a viable
-  automation path.
-
-  *Originally hit while validating set_breakpoint idempotency on a
-  macOS arm64 host.*
-
-- **WSL2 (Ubuntu) + snap-installed chromium.** Default-template Ubuntu on
-  WSL2 ships chromium as a snap (`/snap/bin/chromium`), which runs in a
-  confined namespace. chrome-launcher launches the binary successfully
-  (visible window appears under WSLg) but its startup-port poll
-  `ECONNREFUSEs` on iter 1 and often iter 2 — the debug port either
-  binds to a different port than chrome-launcher polled (race) or is
-  invisible across the snap sandbox boundary. After 2-4 retries the
-  agent's tool-use loop eventually picks an instance that responds, so
-  the eval does run, but every trial pays an inflated cost in retry
-  iterations and the trace is contaminated with WARN entries that look
-  like real failures. Same chrome-launcher code path is clean on macOS,
-  Linux native, and Linux CI.
-
-  **Workaround options**: (a) **prefer macOS or Linux native** for
-  interactive eval iteration — a macOS arm64 host confirmed clean;
-  (b) install non-snap chromium in WSL2 via apt or
-  symlink Playwright's bundled chromium to `/usr/local/bin/chromium-browser`
-  before the snap path; (c) accept the noise and rely on CI for the
-  authoritative signal. Don't rely on WSL2 for eval validation runs.
-
-  *A re-run on the same commit (`f0ce92a`) on a native host showed 0
-  chrome-launcher errors, isolating the cause to the WSL2 + snap-chromium
-  combination rather than the harness.*
-
-- **Ubuntu 23.10+ (incl. 24.04) + Playwright-bundled Chromium.** Recent
-  Ubuntu kernels restrict unprivileged user namespaces via AppArmor, and
-  Playwright-bundled Chromium ships without a SUID `chrome_sandbox`
-  helper. Without `--no-sandbox`, Chromium FATALs at startup
-  (`zygote_host_impl_linux.cc: No usable sandbox!`) before opening its
-  debug port — chrome-launcher's port-poll loop then times out with
-  ECONNREFUSED, looking exactly like the WSL2/snap gap above but with a
-  different root cause. **Mitigation:** `launchChrome` defaults
-  `sandbox: false` so `--no-sandbox` is added automatically; eval
-  pipelines on this host work out-of-the-box. For the full security model,
-  including `sandbox: true`, AppArmor, snap confinement, and Bubblewrap, see
-  [docs/chromium-sandboxing.md](./chromium-sandboxing.md).
-
-  *First observed on an Ubuntu 24.04 arm64 host (Parallels VM) while
-  validating the L4 eval suite. Quick eval went from FAIL/$0.34/445s
-  (chrome-launcher retry storm) to PASS/$0.31/107s once `--no-sandbox`
-  was the default.*