@moondeck/station 0.0.1 → 1.0.1

package/lib/browser-testing.ts

@@ -0,0 +1,1537 @@
+/**
+ * ADR-053: in-container browser for agents — Playwright MCP wiring.
+ *
+ * When a task's project opted into browser testing, session start calls
+ * `setupBrowserTesting`, which installs Chromium and points both engines at
+ * it. Idempotent, and safe to call repeatedly:
+ *
+ *   - `/workspace/.mcp.json` — Claude Code's project-scoped MCP config,
+ *     declaring the `browser` server (headFUL on DISPLAY :99).
+ *   - `/workspace/.claude/settings.json` — `enableAllProjectMcpServers` so
+ *     headless sessions load it without an approval prompt.
+ *   - Every active Codex account's `config.toml` — an
+ *     `[mcp_servers.browser]` block in the account's private CODEX_HOME copy.
+ *
+ * Our `browser` entry is RE-ASSERTED on every call — rewritten, not skipped
+ * when present, and not gated on a marker. Recovery/start credential
+ * injection and account provisioning can replace a Codex config before the
+ * serialized setup boundary, so a marker would only ever prove what we once
+ * wrote, not what is there now. (Live auth refresh deliberately excludes
+ * config.toml.) Only shapes uai itself wrote are touched; anything else is
+ * reported and left alone. When a rewrite was needed, affected sessions are
+ * recycled once the browser is ready and their active turn is done, since
+ * agent CLIs read MCP servers once at process start.
+ *
+ * Phase 2 (the WATCHABLE browser): Chromium runs headful under Xvfb (:99),
+ * mirrored by x11vnc → websockify/noVNC on container port 6080 — which the
+ * cloud surfaces as the synthetic "browser" preview, so the human can watch
+ * the agents click around from the preview menu. The viewer stack is
+ * (re)started on every setup call, lockfile/pidfile-guarded, so it survives
+ * container restarts.
+ *
+ * Browser binaries land on the host-wide `uai-playwright` volume
+ * (PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers, mounted by the generated
+ * compose) so Chromium downloads once per HOST.
+ *
+ * The browser install DOES block session start, on purpose — see
+ * `setupBrowserTesting`. Everything else here is best-effort. The apt/viewer
+ * chain stays backgrounded; the browser does not depend on it.
+ *
+ * Hard-won asdf rules (2026-07-07): npx resolves ONLY where a .tool-versions
+ * applies → always `-w /workspace`; and root has no ~/.tool-versions →
+ * root execs also need `-e HOME=/home/node`.
+ */
+import { createHash } from "node:crypto";
+
+import {
+  taskAppContainerName,
+  taskContainerBackend,
+  taskContainerCli,
+} from "./task-container-cli";
+import { MCP_CONFIG_LOCK_PATH } from "./mcp-config-lock";
+import {
+  MACHINE_RUNTIME_AUTHORITY_ENV,
+  RUNTIME_AUTHORITY_ENV,
+  runtimeAuthorityDockerExecArgs,
+} from "./runtime-authority";
+import { STANDARD_DEFAULT_NODE_VERSION } from "./standard-image";
+import type { TaskEnvironmentHandle } from "./task-environment/types";
+import { isEnvironmentTransportProvider } from "./task-environment/types";
+
+const SERVER_DISPLAY = ":99";
+/**
+ * The virtual screen, and the ONLY place its size is written.
+ *
+ * Chromium's window has to be told the same numbers (see CHROMIUM_ARGS). There
+ * is no window manager on this display — nothing to maximise a window or
+ * service a resize — so the window is whatever size it was created at, forever.
+ * Two independent copies of "1440x900" would drift, and the failure is quiet:
+ * the page renders at the size you asked for while the window shows part of it.
+ */
+const SCREEN_W = 1440;
+const SCREEN_H = 900;
+const XVFB_CMD = `Xvfb ${SERVER_DISPLAY} -screen 0 ${SCREEN_W}x${SCREEN_H}x24 -nolisten tcp`;
+
+/**
+ * The MCP server package — PINNED, deliberately, and the single source of
+ * truth for the whole browser stack.
+ *
+ * Every Playwright release wants one exact Chromium *build number*, and
+ * treats any other build as "not installed". So the pre-warm and the runtime
+ * must resolve the same `playwright-core`, or the browser never launches.
+ * `@playwright/mcp@latest` cannot promise that: it floats, and its pinned
+ * `playwright-core` floats with it.
+ *
+ * That is not hypothetical — it was the live bug (task 01kye1b8..., Jul 2026,
+ * fixed here). Provisioning ran `playwright@latest install chromium` (build
+ * 1234) while the MCP resolved to 0.0.78 → build 1232, so EVERY container
+ * started with a dead browser and a black VNC preview, forever: a version
+ * mismatch never heals on retry. A follow-up isolated diagnostic also proved
+ * that `playwright install` garbage-collects builds it does not recognise and
+ * can delete another revision from the shared host volume. That eviction was
+ * deliberately induced while diagnosing the incident, not observed as part
+ * of the original outage, but it makes an unflagged pre-warm unsafe.
+ *
+ * The fix is structural: browsers are installed THROUGH this exact package
+ * (below), so provisioning and runtime cannot disagree by construction. To
+ * upgrade, change this one string — the pre-warm follows automatically.
+ */
+export const MCP_PKG = "@playwright/mcp@0.0.78";
+
+/**
+ * The browser to launch AND to pre-warm. One constant feeding both
+ * `--browser` and `install-browser`, so the two can never name different
+ * browsers either. (In current playwright-core `chromium` is an alias for the
+ * `chrome-for-testing` channel — hence the error text agents used to hit.)
+ */
+export const BROWSER = "chromium";
+
+/**
+ * Install the exact Chromium build `MCP_PKG`'s bundled playwright-core wants.
+ *
+ * `install-browser` is the MCP's own passthrough to that playwright-core, so
+ * the build is right by construction, and it is idempotent and fast (~0.5s)
+ * once present.
+ *
+ * `PLAYWRIGHT_SKIP_BROWSER_GC=1` is load-bearing, not decoration.
+ * `install-browser` is NOT inherently additive — `@playwright/mcp`'s `cli.js`
+ * literally rewrites the word to `install`, and Playwright's registry install
+ * then garbage-collects: it keeps a `.links` entry per installed
+ * playwright-core under the browsers path and deletes any build no LIVE link
+ * still wants. Since `/opt/pw-browsers` is a host-WIDE volume, an unflagged
+ * install in one container evicts browsers other tasks are mid-use of; that
+ * is measured, not theorised (a stale build vanishes on the very next run).
+ * The flag is honoured by the pinned core and makes the install genuinely
+ * additive, so provisioning can never be the thing that breaks another task.
+ *
+ * The cost is that dead builds are never reclaimed automatically. That is not
+ * the ~300 MB of download it sounds like: unpacked, one build set is ~980 MB
+ * (measured — 641 MB Chromium + 340 MB headless shell), so every pin bump
+ * strands about a gigabyte per host until someone prunes `/opt/pw-browsers`.
+ * Still the right trade against deleting a browser out from under a running
+ * agent, but it is a real cost and the prune is a real chore.
+ *
+ * Bounded IN the container too. `dockerCli`'s own timeout SIGKILLs the local
+ * `docker exec` client, and docker does not forward that to the process
+ * inside (moby/moby#9098) — so a host-side bound alone would let a wedged
+ * installer keep running, and keep holding Playwright's registry lock, while
+ * we conclude it failed and spawn agents anyway. Kept under the host-side
+ * bound so this is the one that fires.
+ */
+const INSTALL_TIMEOUT_S = 280;
+
+// The env assignment leads: `timeout N VAR=1 cmd` makes timeout try to exec
+// "VAR=1" as a program and exit 127 without running anything. As a shell
+// prefix it applies to `timeout` and is inherited straight through.
+// `--kill-after` because plain `timeout` only sends TERM: an installer wedged
+// in an uninterruptible or signal-ignoring state would absorb it and keep the
+// registry lock, which is the whole thing this is here to prevent.
+const INSTALL_BROWSER =
+  `PLAYWRIGHT_SKIP_BROWSER_GC=1 timeout --kill-after=10 ${INSTALL_TIMEOUT_S} ` +
+  `npx -y ${MCP_PKG} install-browser ${BROWSER}`;
+const INSTALL_LOG = "/tmp/uai-pw-browser.log";
+
+/**
+ * Chromium flags the MCP has no CLI passthrough for, so they ride a config file
+ * (`--config`, `browser.launchOptions.args`).
+ *
+ * `--window-size`/`--window-position` because there is NO WINDOW MANAGER on the
+ * virtual display. Chromium opens at its own default — 1050x880 inside a
+ * 1440x900 screen — and with nothing to service resize requests, stays there. A
+ * later `browser_resize` then only APPEARS to work: Playwright falls back to a
+ * CDP device-metrics override, so the page renders at the requested width while
+ * the window still shows the leftmost 1050px. Everything past that edge is
+ * painted where nobody can see it and nothing reports an error. Window creation
+ * is the only moment the size can be set.
+ *
+ * `--test-type` suppresses "You are using an unsupported command-line flag:
+ * --no-sandbox", which we cannot avoid triggering — no user namespaces in the
+ * container, so the sandbox has to go. Measured on this exact launch path
+ * (persistent context): the infobar costs 56px of viewport, permanently, in a
+ * window a human is watching.
+ */
+const CHROMIUM_ARGS = [
+  "--test-type",
+  "--window-position=0,0",
+  `--window-size=${SCREEN_W},${SCREEN_H}`,
+];
+const MCP_LAUNCH_CONFIG = "/tmp/uai-playwright-mcp.json";
+/**
+ * Base64, not raw JSON. This command is embedded three ways — a JSON value in
+ * `.mcp.json`, a TOML LITERAL in Codex's config, and an `sh -lc` argument — and
+ * a literal TOML string cannot contain a single quote at all (`tomlString`
+ * throws rather than emit one). Base64's alphabet has no quotes, so the same
+ * bytes survive every layer with no escaping rules to get wrong.
+ */
+const MCP_LAUNCH_CONFIG_B64 = Buffer.from(
+  JSON.stringify({ browser: { launchOptions: { args: CHROMIUM_ARGS } } }),
+).toString("base64");
+/** Host-side backstop, deliberately looser than the in-container `timeout`. */
+const INSTALL_TIMEOUT_MS = 300_000;
+const MCP_CONFIG_PATH = "/workspace/.mcp.json";
+export const DEFAULT_CODEX_HOME = "/home/node/.codex";
+const CLAUDE_SETTINGS_PATH = "/workspace/.claude/settings.json";
+const CONFIG_RESULT_TOKEN = "__UAI_BROWSER_CONFIG__";
+
+/**
+ * The pre-warm run at session start. No `|| true`: it is awaited now, so its
+ * exit status is the readiness signal we log on.
+ */
+export const PREWARM_CMD = `${INSTALL_BROWSER} >${INSTALL_LOG} 2>&1`;
+
+/**
+ * The MCP server launcher — self-sufficient by design (learned live: a
+ * session that spawns while the apt installs are still running got a DEAD
+ * mcp server, and the agent had to improvise). It ensures its own display
+ * when Xvfb exists (headful → watchable), and falls back to a HEADLESS
+ * browser while the viewer packages are still installing — the agent always
+ * gets working tools. `sh -lc` + cd /workspace for the asdf shims. No
+ * single quotes in here: it's embedded in single-quoted JSON/TOML strings.
+ */
+// X's own lockfile is the display-up signal — no pgrep (pgrep -f guards
+// self-matched their launcher's cmdline and skipped every start; found
+// live 2026-07-08), and it also detects displays an AGENT started itself.
+const X_LOCK = `/tmp/.X${SERVER_DISPLAY.slice(1)}-lock`;
+
+// NOTHING that can download belongs on this path. An MCP client gives the
+// server a fixed budget to complete its handshake — Codex 10s, Claude Code
+// 30s — and neither config raises it, so a ~90s install here doesn't delay
+// the first session, it LOSES it. Readiness is established before agents
+// spawn instead (see setupBrowserTesting), where a slow install is merely
+// slow. Ensuring the display is fine: Xvfb is local and instant.
+const SERVER_LAUNCHER =
+  `cd /workspace; ` +
+  // Writing a local file is not a download — it stays off the handshake budget.
+  `echo ${MCP_LAUNCH_CONFIG_B64} | base64 -d > ${MCP_LAUNCH_CONFIG}; ` +
+  `if command -v Xvfb >/dev/null 2>&1; then ` +
+  `[ -e ${X_LOCK} ] || (nohup ${XVFB_CMD} >>/tmp/uai-xvfb.log 2>&1 &); ` +
+  `sleep 1; export DISPLAY=${SERVER_DISPLAY}; ` +
+  `exec npx -y ${MCP_PKG} --config ${MCP_LAUNCH_CONFIG} ` +
+  `--browser ${BROWSER} --no-sandbox; ` +
+  `else ` +
+  `exec npx -y ${MCP_PKG} --config ${MCP_LAUNCH_CONFIG} ` +
+  `--browser ${BROWSER} --no-sandbox --headless; ` +
+  `fi`;
+
+const SERVER_COMMAND = "sh";
+/** Exported for the test that locks the pin/browser invariants. */
+export const SERVER_ARGS: [string, string] = ["-lc", SERVER_LAUNCHER];
+
+/** The `browser` server definition every engine gets. */
+const SERVER_DEF = { command: SERVER_COMMAND, args: SERVER_ARGS };
+
+/** Cursor reads stdio servers from ~/.cursor/mcp.json (the adapter passes
+ * `--approve-mcps`); same JSON shape as Claude's project file. */
+const CURSOR_MCP_PATH = "/home/node/.cursor/mcp.json";
+
+/** Grok: `grok mcp add` (add-or-update) in USER scope, once per GROK_HOME a
+ * task may run under (the default ~/.grok and each ~/.grok-acct-<id>) —
+ * `GROK_HOME` redirects the user config. PROJECT scope looked simpler but
+ * grok refuses repo-local servers in an untrusted folder, and /workspace is
+ * not a git repo so nothing ever trusts it (live 2026-09-08: "folder
+ * untrusted … re-run with --trust", no such flag headless). The launcher has
+ * no single quotes by construction (see SERVER_LAUNCHER). */
+const GROK_BIN = "/home/node/.grok/bin/grok";
+export const DEFAULT_GROK_HOME = "/home/node/.grok";
+export function grokBrowserAddCommand(home: string): string {
+  if (!/^\/home\/node\/\.grok(-acct-[A-Za-z0-9_-]+)?$/.test(home)) {
+    throw new Error("invalid Grok home");
+  }
+  return (
+    `GROK_HOME=${home} ${GROK_BIN} mcp add browser -s user -t stdio ` +
+    `${SERVER_COMMAND} -- ${SERVER_ARGS.map((arg) => `'${arg}'`).join(" ")}`
+  );
+}
+
+const CLAUDE_SETTINGS_JSON = JSON.stringify(
+  { enableAllProjectMcpServers: true },
+  null,
+  2,
+);
+
+const MANAGED_PACKAGE = "@playwright/mcp@<uai-version>";
+
+/**
+ * Every browser-server shape uai has shipped. Ownership is an exact semantic
+ * allowlist, with only the package version normalised: a pin bump is ours,
+ * but one extra flag, env var, timeout, cwd, or tool filter is a human's
+ * customisation and must survive untouched.
+ */
+const HISTORICAL_SERVER_DEFS: Array<Record<string, unknown>> = [
+  {
+    command: "npx",
+    args: [
+      "-y",
+      "@playwright/mcp@latest",
+      "--headless",
+      "--browser",
+      "chromium",
+      "--no-sandbox",
+    ],
+  },
+  {
+    command: "npx",
+    args: [
+      "-y",
+      "@playwright/mcp@latest",
+      "--browser",
+      "chromium",
+      "--no-sandbox",
+    ],
+    env: { DISPLAY: SERVER_DISPLAY },
+  },
+  {
+    command: "sh",
+    args: [
+      "-lc",
+      `cd /workspace; if command -v Xvfb >/dev/null 2>&1; then ` +
+        `pgrep -f "Xvfb ${SERVER_DISPLAY}" >/dev/null 2>&1 || ` +
+        `(${XVFB_CMD} >>/tmp/uai-xvfb.log 2>&1 &); ` +
+        `sleep 1; export DISPLAY=${SERVER_DISPLAY}; ` +
+        `exec npx -y @playwright/mcp@latest --browser chromium --no-sandbox; ` +
+        `else exec npx -y @playwright/mcp@latest --browser chromium --no-sandbox --headless; fi`,
+    ],
+  },
+  {
+    command: "sh",
+    args: [
+      "-lc",
+      `cd /workspace; if command -v Xvfb >/dev/null 2>&1; then ` +
+        `[ -e ${X_LOCK} ] || (nohup ${XVFB_CMD} >>/tmp/uai-xvfb.log 2>&1 &); ` +
+        `sleep 1; export DISPLAY=${SERVER_DISPLAY}; ` +
+        `exec npx -y @playwright/mcp@latest --browser chromium --no-sandbox; ` +
+        `else exec npx -y @playwright/mcp@latest --browser chromium --no-sandbox --headless; fi`,
+    ],
+  },
+  {
+    command: "sh",
+    args: [
+      "-lc",
+      `cd /workspace; npx -y @playwright/mcp@0.0.78 install-browser chromium ` +
+        `>>${INSTALL_LOG} 2>&1 || true; ` +
+        `if command -v Xvfb >/dev/null 2>&1; then ` +
+        `[ -e ${X_LOCK} ] || (nohup ${XVFB_CMD} >>/tmp/uai-xvfb.log 2>&1 &); ` +
+        `sleep 1; export DISPLAY=${SERVER_DISPLAY}; ` +
+        `exec npx -y @playwright/mcp@0.0.78 --browser chromium --no-sandbox; ` +
+        `else exec npx -y @playwright/mcp@0.0.78 --browser chromium --no-sandbox --headless; fi`,
+    ],
+  },
+  {
+    // The pinned launcher BEFORE `--config`: no window geometry and no
+    // `--test-type`, so its Chromium opened at 1050x880 on a 1440x900 screen,
+    // clipping anything wider, under an infobar. Listed so a container still
+    // running it is rewritten rather than left as it is.
+    command: "sh",
+    args: [
+      "-lc",
+      `cd /workspace; ` +
+        `if command -v Xvfb >/dev/null 2>&1; then ` +
+        `[ -e ${X_LOCK} ] || (nohup ${XVFB_CMD} >>/tmp/uai-xvfb.log 2>&1 &); ` +
+        `sleep 1; export DISPLAY=${SERVER_DISPLAY}; ` +
+        `exec npx -y ${MCP_PKG} --browser ${BROWSER} --no-sandbox; ` +
+        `else ` +
+        `exec npx -y ${MCP_PKG} --browser ${BROWSER} --no-sandbox --headless; ` +
+        `fi`,
+    ],
+  },
+  SERVER_DEF,
+];
+
+function normaliseManagedPackage(value: unknown): unknown {
+  if (typeof value === "string") {
+    return value.replace(
+      /@playwright\/mcp@(?:latest|\d+\.\d+\.\d+)(?=[\s'"]|$)/g,
+      MANAGED_PACKAGE,
+    );
+  }
+  if (Array.isArray(value)) return value.map(normaliseManagedPackage);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, normaliseManagedPackage(item)]),
+    );
+  }
+  return value;
+}
+
+/** Exported so ownership tests lock the historical allowlist itself. */
+export const MANAGED_BROWSER_DEFS = HISTORICAL_SERVER_DEFS.map(
+  normaliseManagedPackage,
+);
+
+const CODEX_MARKER = "# uai ADR-053: in-container browser (Playwright MCP)";
+
+function tomlString(value: string, quote: "'" | '"'): string {
+  if (quote === "'") {
+    if (value.includes("'")) {
+      throw new Error("Moondeck browser launcher cannot be represented as TOML literal text");
+    }
+    return `'${value}'`;
+  }
+  return JSON.stringify(value);
+}
+
+function codexBlock(
+  definition: Record<string, unknown>,
+  quote: "'" | '"',
+): string {
+  const command = String(definition.command);
+  const args = (definition.args as unknown[]).map(String);
+  const lines = [
+    "",
+    CODEX_MARKER,
+    "[mcp_servers.browser]",
+    `command = ${tomlString(command, quote)}`,
+    `args = [${args.map((arg) => tomlString(arg, quote)).join(", ")}]`,
+  ];
+  if (definition.env && typeof definition.env === "object") {
+    const pairs = Object.entries(definition.env).map(
+      ([key, value]) => `${key} = ${tomlString(String(value), quote)}`,
+    );
+    lines.push(`env = { ${pairs.join(", ")} }`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+/** Exact text shapes Uai wrote, used only after Codex confirms the semantics. */
+export const MANAGED_CODEX_BLOCKS = [
+  codexBlock(HISTORICAL_SERVER_DEFS[0]!, '"'),
+  codexBlock(HISTORICAL_SERVER_DEFS[1]!, '"'),
+  ...HISTORICAL_SERVER_DEFS.slice(2).map((definition) =>
+    codexBlock(definition, "'"),
+  ),
+]
+  .map((block) => String(normaliseManagedPackage(block)))
+  .filter((block, index, blocks) => blocks.indexOf(block) === index);
+
+const CODEX_TOML = codexBlock(SERVER_DEF, "'");
+
+/**
+ * The active migrator. Claude JSON is parsed and atomically replaced. The
+ * shipped Codex CLI is used only as the read-only semantic parser; a Codex
+ * write is allowed only when the raw block exactly matches text Uai shipped.
+ * That preserves neighboring tables/comments byte-for-byte and declines
+ * custom fields the CLI's JSON view may omit.
+ */
+export const MIGRATE_JS = String.raw`
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const child = require("node:child_process");
+
+const def = JSON.parse(process.env.UAI_BROWSER_DEF);
+const settingsDef = JSON.parse(process.env.UAI_CLAUDE_SETTINGS_DEF);
+const managedDefs = ${JSON.stringify(MANAGED_BROWSER_DEFS)};
+const packageToken = ${JSON.stringify(MANAGED_PACKAGE)};
+const managedCodexBlocks = ${JSON.stringify(MANAGED_CODEX_BLOCKS)};
+const desiredCodexBlock = ${JSON.stringify(CODEX_TOML)};
+const notes = [];
+let changed = false;
+let configured = true;
+let codexHomes = [];
+try {
+  const parsed = JSON.parse(process.env.UAI_CODEX_HOMES || "[]");
+  if (!Array.isArray(parsed) ||
+      !parsed.every(function (home) {
+        return typeof home === "string" &&
+          (home === ${JSON.stringify(DEFAULT_CODEX_HOME)} ||
+            /^\/home\/node\/\.codex-acct-[A-Za-z0-9_-]+$/.test(home));
+      })) {
+    throw new Error("invalid Codex home list");
+  }
+  codexHomes = Array.from(new Set(parsed));
+} catch (error) {
+  notes.push("Codex home list is invalid: " + String(error.message || error));
+  configured = false;
+}
+
+function plainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (plainObject(value)) {
+    const out = {};
+    for (const key of Object.keys(value).sort()) out[key] = canonical(value[key]);
+    return out;
+  }
+  return value;
+}
+
+function equal(left, right) {
+  return JSON.stringify(canonical(left)) === JSON.stringify(canonical(right));
+}
+
+function normalise(value) {
+  if (typeof value === "string") {
+    return value.replace(
+      /@playwright\/mcp@(?:latest|\d+\.\d+\.\d+)(?=[\s'"]|$)/g,
+      packageToken
+    );
+  }
+  if (Array.isArray(value)) return value.map(normalise);
+  if (plainObject(value)) {
+    const out = {};
+    for (const [key, item] of Object.entries(value)) out[key] = normalise(item);
+    return out;
+  }
+  return value;
+}
+
+function isManaged(value) {
+  const normalised = normalise(value);
+  return managedDefs.some(function (candidate) {
+    return equal(candidate, normalised);
+  });
+}
+
+function atomicWrite(file, text, expected) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const mode = fs.existsSync(file) ? fs.statSync(file).mode & 0o777 : 0o644;
+  const tmp = path.join(
+    path.dirname(file),
+    "." + path.basename(file) + "." + process.pid + "." +
+      crypto.randomBytes(8).toString("hex") + ".tmp"
+  );
+  try {
+    fs.writeFileSync(tmp, text, { encoding: "utf8", flag: "wx", mode: mode });
+    if (arguments.length >= 3) {
+      const current = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : null;
+      if (current !== expected) return false;
+    }
+    fs.renameSync(tmp, file);
+    return true;
+  } finally {
+    try { fs.unlinkSync(tmp); } catch {}
+  }
+}
+
+function atomicCreate(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = path.join(
+    path.dirname(file),
+    "." + path.basename(file) + "." + process.pid + "." +
+      crypto.randomBytes(8).toString("hex") + ".tmp"
+  );
+  try {
+    fs.writeFileSync(tmp, text, { encoding: "utf8", flag: "wx", mode: 0o644 });
+    try {
+      fs.linkSync(tmp, file);
+      return true;
+    } catch (error) {
+      if (error && error.code === "EEXIST") return false;
+      throw error;
+    }
+  } finally {
+    try { fs.unlinkSync(tmp); } catch {}
+  }
+}
+
+function ensureClaudeBrowser() {
+  const file = process.env.UAI_MCP_PATH;
+  if (!file) return { configured: true, changed: false };
+  const exists = fs.existsSync(file);
+  let original = null;
+  let document;
+  try {
+    original = exists ? fs.readFileSync(file, "utf8") : null;
+    document = exists ? JSON.parse(original) : { mcpServers: {} };
+  } catch {
+    notes.push("mcp.json is unparseable - left alone");
+    return { configured: false, changed: false };
+  }
+  if (!plainObject(document)) {
+    notes.push("mcp.json root is not an object - left alone");
+    return { configured: false, changed: false };
+  }
+  if (document.mcpServers === undefined) document.mcpServers = {};
+  if (!plainObject(document.mcpServers)) {
+    notes.push("mcp.json mcpServers is not an object - left alone");
+    return { configured: false, changed: false };
+  }
+  const current = document.mcpServers.browser;
+  if (current !== undefined && equal(current, def)) {
+    return { configured: true, changed: false };
+  }
+  if (current !== undefined && !isManaged(current)) {
+    notes.push("mcp.json browser entry is not uai-managed - left alone");
+    return { configured: true, changed: false };
+  }
+  document.mcpServers.browser = def;
+  if (!atomicWrite(file, JSON.stringify(document, null, 2) + "\n", original)) {
+    notes.push("mcp.json changed concurrently - retrying later");
+    return { configured: false, changed: false };
+  }
+  return { configured: true, changed: true };
+}
+
+function ensureCursorBrowser() {
+  const file = process.env.UAI_CURSOR_MCP_PATH;
+  if (!file) return { configured: true, changed: false };
+  const exists = fs.existsSync(file);
+  let original = null;
+  let document;
+  try {
+    original = exists ? fs.readFileSync(file, "utf8") : null;
+    document = exists ? JSON.parse(original) : { mcpServers: {} };
+  } catch {
+    notes.push("cursor mcp.json is unparseable - left alone");
+    return { configured: false, changed: false };
+  }
+  if (!plainObject(document)) {
+    notes.push("cursor mcp.json root is not an object - left alone");
+    return { configured: false, changed: false };
+  }
+  if (document.mcpServers === undefined) document.mcpServers = {};
+  if (!plainObject(document.mcpServers)) {
+    notes.push("cursor mcp.json mcpServers is not an object - left alone");
+    return { configured: false, changed: false };
+  }
+  const current = document.mcpServers.browser;
+  if (current !== undefined && equal(current, def)) {
+    return { configured: true, changed: false };
+  }
+  if (current !== undefined && !isManaged(current)) {
+    notes.push("cursor mcp.json browser entry is not uai-managed - left alone");
+    return { configured: true, changed: false };
+  }
+  document.mcpServers.browser = def;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  if (!atomicWrite(file, JSON.stringify(document, null, 2) + "\n", original)) {
+    notes.push("cursor mcp.json changed concurrently - retrying later");
+    return { configured: false, changed: false };
+  }
+  return { configured: true, changed: true };
+}
+
+function ensureClaudeSettings() {
+  const file = process.env.UAI_CLAUDE_SETTINGS_PATH;
+  if (!file || fs.existsSync(file)) return { configured: true, changed: false };
+  try {
+    const created = atomicCreate(file, JSON.stringify(settingsDef, null, 2) + "\n");
+    return { configured: true, changed: created };
+  } catch (error) {
+    notes.push("Claude settings write failed: " + String(error.message || error));
+    return { configured: false, changed: false };
+  }
+}
+
+function exactKeys(value, keys) {
+  return plainObject(value) &&
+    Object.keys(value).sort().join("\0") === keys.slice().sort().join("\0");
+}
+
+const codexTopKeys = [
+  "disabled_reason", "disabled_tools", "enabled", "enabled_tools", "name",
+  "startup_timeout_sec", "tool_timeout_sec", "transport"
+];
+
+function stringArrayOrNull(value) {
+  return value === null ||
+    (Array.isArray(value) &&
+      value.every(function (item) { return typeof item === "string"; }));
+}
+
+function validCodexEnvelope(value) {
+  if (!exactKeys(value, codexTopKeys) || value.name !== "browser" ||
+      typeof value.enabled !== "boolean" ||
+      !(value.disabled_reason === null ||
+        typeof value.disabled_reason === "string") ||
+      !stringArrayOrNull(value.enabled_tools) ||
+      !stringArrayOrNull(value.disabled_tools) ||
+      !(value.startup_timeout_sec === null ||
+        typeof value.startup_timeout_sec === "number") ||
+      !(value.tool_timeout_sec === null ||
+        typeof value.tool_timeout_sec === "number") ||
+      !plainObject(value.transport) ||
+      typeof value.transport.type !== "string") {
+    return false;
+  }
+  if (value.transport.type === "stdio") {
+    return exactKeys(
+      value.transport,
+      ["args", "command", "cwd", "env", "env_vars", "type"]
+    ) && typeof value.transport.command === "string" &&
+      Array.isArray(value.transport.args) &&
+      value.transport.args.every(function (item) {
+        return typeof item === "string";
+      }) &&
+      (value.transport.cwd === null ||
+        typeof value.transport.cwd === "string") &&
+      (value.transport.env === null || plainObject(value.transport.env)) &&
+      Array.isArray(value.transport.env_vars);
+  }
+  if (value.transport.type === "streamable_http" ||
+      value.transport.type === "sse") {
+    return exactKeys(
+      value.transport,
+      [
+        "bearer_token_env_var", "env_http_headers", "http_headers", "type",
+        "url"
+      ]
+    ) && typeof value.transport.url === "string";
+  }
+  return false;
+}
+
+/**
+ * Convert Codex's normalised JSON to the stdio shape Claude stores. Checking
+ * every default makes an added timeout, cwd, env-var mapping, tool filter, or
+ * disabled state foreign rather than accidentally uai-owned.
+ */
+function codexDefinition(value) {
+  if (!validCodexEnvelope(value) ||
+      value.enabled !== true || value.disabled_reason !== null ||
+      value.enabled_tools !== null || value.disabled_tools !== null ||
+      value.startup_timeout_sec !== null || value.tool_timeout_sec !== null) {
+    return null;
+  }
+  const transport = value.transport;
+  const transportKeys = ["args", "command", "cwd", "env", "env_vars", "type"];
+  if (!exactKeys(transport, transportKeys) || transport.type !== "stdio" ||
+      typeof transport.command !== "string" ||
+      !Array.isArray(transport.args) ||
+      !transport.args.every(function (arg) { return typeof arg === "string"; }) ||
+      transport.cwd !== null || !Array.isArray(transport.env_vars) ||
+      transport.env_vars.length !== 0 ||
+      !(transport.env === null || plainObject(transport.env))) {
+    return null;
+  }
+  if (transport.env !== null &&
+      !Object.values(transport.env).every(function (item) {
+        return typeof item === "string";
+      })) {
+    return null;
+  }
+  const result = { command: transport.command, args: transport.args };
+  if (transport.env !== null) result.env = transport.env;
+  return result;
+}
+
+function runCodex(home, args) {
+  return child.spawnSync("codex", args, {
+    encoding: "utf8",
+    env: Object.assign({}, process.env, { CODEX_HOME: home }),
+    maxBuffer: 1024 * 1024,
+    // Codex's FIRST run on a fresh machine initialises its state (sqlite)
+    // before answering; 5 s timed out on every hostless task machine
+    // (smoke 10, 2026-09-10: ETIMEDOUT for both homes) and the direct
+    // config.toml fallback did the work with an error in the log. A minute
+    // is generous for a probe that normally answers in well under a second.
+    timeout: 60000,
+    killSignal: "SIGKILL",
+  });
+}
+
+function getCodex(home) {
+  const result = runCodex(home, ["mcp", "get", "browser", "--json"]);
+  if (result.status === 0) {
+    try {
+      return { kind: "found", value: JSON.parse(result.stdout) };
+    } catch {
+      return { kind: "error", detail: "codex mcp get returned invalid JSON" };
+    }
+  }
+  const lastLine = String(result.stderr || "")
+    .split(/\r?\n/)
+    .map(function (line) { return line.trim(); })
+    .filter(Boolean)
+    .pop();
+  if (lastLine === "Error: No MCP server named 'browser' found.") {
+    return { kind: "missing" };
+  }
+  return {
+    kind: "error",
+    detail: "codex mcp get failed: " + String(lastLine || result.error || result.status),
+  };
+}
+
+function classifyCodex(state) {
+  if (state.kind !== "found") return state;
+  if (!validCodexEnvelope(state.value)) {
+    return { kind: "error", detail: "codex mcp get returned malformed browser JSON" };
+  }
+  const definition = codexDefinition(state.value);
+  if (definition && equal(definition, def)) {
+    return { kind: "current", definition: definition };
+  }
+  if (definition && isManaged(definition)) {
+    return { kind: "managed", definition: definition };
+  }
+  return {
+    kind: "foreign",
+    configured: true,
+  };
+}
+
+function tableHeaderPath(line) {
+  let index = 0;
+  const skipSpace = function () {
+    while (
+      line[index] === " " ||
+      line[index] === "\t" ||
+      line[index] === "\r"
+    ) index += 1;
+  };
+  skipSpace();
+  const array = line.startsWith("[[", index);
+  if (!array && line[index] !== "[") return null;
+  index += array ? 2 : 1;
+  const close = array ? "]]" : "]";
+  const segments = [];
+
+  while (index < line.length) {
+    skipSpace();
+    if (line.startsWith(close, index)) {
+      index += close.length;
+      skipSpace();
+      return index === line.length || line[index] === "#" ? segments : null;
+    }
+
+    let segment;
+    if (line[index] === '"') {
+      const start = index;
+      index += 1;
+      while (index < line.length) {
+        if (line[index] === "\\") {
+          index += 2;
+          continue;
+        }
+        if (line[index] === '"') {
+          index += 1;
+          break;
+        }
+        index += 1;
+      }
+      try {
+        const jsonString = line.slice(start, index).replace(
+          /\\U([0-9A-Fa-f]{8})/g,
+          function (_whole, hex) {
+            const point = Number.parseInt(hex, 16);
+            if (point <= 0xffff) {
+              return "\\u" + point.toString(16).padStart(4, "0");
+            }
+            const shifted = point - 0x10000;
+            const high = 0xd800 + (shifted >> 10);
+            const low = 0xdc00 + (shifted & 0x3ff);
+            return "\\u" + high.toString(16) + "\\u" + low.toString(16);
+          }
+        );
+        segment = JSON.parse(jsonString);
+      } catch {
+        return null;
+      }
+    } else if (line[index] === "'") {
+      const end = line.indexOf("'", index + 1);
+      if (end === -1) return null;
+      segment = line.slice(index + 1, end);
+      index = end + 1;
+    } else {
+      const bare = /^[A-Za-z0-9_-]+/.exec(line.slice(index));
+      if (!bare) return null;
+      segment = bare[0];
+      index += bare[0].length;
+    }
+    segments.push(segment);
+    skipSpace();
+    if (line[index] === ".") {
+      index += 1;
+      continue;
+    }
+    if (!line.startsWith(close, index)) return null;
+  }
+  return null;
+}
+
+function managedBlockEdit(text) {
+  const pattern = new RegExp(
+    "\\r?\\n# uai ADR-053: in-container browser \\(Playwright MCP\\)\\r?\\n" +
+      "\\[mcp_servers\\.browser\\]\\r?\\n" +
+      "command = [^\\r\\n]+\\r?\\n" +
+      "args = [^\\r\\n]+\\r?\\n" +
+      "(?:env = [^\\r\\n]+\\r?\\n)?",
+    "g"
+  );
+  // A descendant table can carry browser settings that Codex's normalised
+  // JSON omits. Reject the whole file if ANY browser table other than the
+  // single Uai-authored root exists, even when another table sits between the
+  // managed block and that descendant.
+  const browserHeaders = Array.from(
+    text.matchAll(/^[ \t]*\[\[?.+\]\]?[ \t]*(?:#.*)?\r?$/gm)
+  ).map(function (match) {
+    return tableHeaderPath(match[0]);
+  }).filter(function (segments) {
+    return segments &&
+      segments.length >= 2 &&
+      segments[0] === "mcp_servers" &&
+      segments[1] === "browser";
+  });
+  if (browserHeaders.length !== 1 || browserHeaders[0].length !== 2) {
+    return null;
+  }
+  const matches = Array.from(text.matchAll(pattern)).filter(function (match) {
+    const normalised = normalise(match[0].replace(/\r\n/g, "\n"));
+    if (!managedCodexBlocks.includes(normalised)) return false;
+    const after = (match.index || 0) + match[0].length;
+    const remainder = text.slice(after);
+    const nextHeader = remainder.search(
+      /^[ \t]*\[\[?.+\]\]?[ \t]*(?:#.*)?\r?$/m
+    );
+    const gap = nextHeader === -1 ? remainder : remainder.slice(0, nextHeader);
+    return gap.split(/\r?\n/).every(function (line) {
+      const trimmed = line.trim();
+      return trimmed === "" || trimmed.startsWith("#");
+    });
+  });
+  if (matches.length !== 1) return null;
+  const match = matches[0];
+  const start = match.index || 0;
+  const newline = match[0].includes("\r\n") ? "\r\n" : "\n";
+  const replacement = desiredCodexBlock.replace(/\n/g, newline);
+  return text.slice(0, start) + replacement + text.slice(start + match[0].length);
+}
+
+function verifyCodexWrite(home) {
+  const observed = classifyCodex(getCodex(home));
+  if (observed.kind === "current") {
+    return { configured: true, changed: true };
+  }
+  if (observed.kind === "foreign") {
+    notes.push(home + ": browser definition changed concurrently - left alone");
+    return { configured: observed.configured, changed: true };
+  }
+  if (observed.kind === "error") notes.push(home + ": " + observed.detail);
+  else notes.push(home + ": browser rewrite did not produce the pinned definition");
+  return { configured: false, changed: true };
+}
+
+function ensureCodexBrowser(home) {
+  const file = path.join(home, "config.toml");
+  try {
+    fs.mkdirSync(home, { recursive: true });
+  } catch (error) {
+    notes.push(home + ": could not create Codex home: " + String(error.message || error));
+    return { configured: false, changed: false };
+  }
+
+  // Read before asking Codex to parse. The compare-before-rename below then
+  // rejects any writer that lands after this snapshot.
+  const original = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : null;
+  const state = classifyCodex(getCodex(home));
+  if (state.kind === "current") return { configured: true, changed: false };
+  if (state.kind === "foreign") {
+    notes.push(home + ": browser definition is not uai-managed - left alone");
+    return { configured: state.configured, changed: false };
+  }
+  if (state.kind === "error") {
+    notes.push(home + ": " + state.detail);
+    return { configured: false, changed: false };
+  }
+
+  let next;
+  if (state.kind === "missing") {
+    const base = original || "";
+    const newline = base.includes("\r\n") ? "\r\n" : "\n";
+    next = base + desiredCodexBlock.replace(/\n/g, newline);
+  } else {
+    next = original === null ? null : managedBlockEdit(original);
+    if (next === null) {
+      notes.push(home + ": managed semantics have a foreign text shape - left alone");
+      return { configured: true, changed: false };
+    }
+  }
+
+  if (!atomicWrite(file, next, original)) {
+    notes.push(home + ": config.toml changed concurrently - retrying later");
+    return { configured: false, changed: false };
+  }
+  return verifyCodexWrite(home);
+}
+
+function safeOutcome(label, ensure) {
+  try {
+    return ensure();
+  } catch (error) {
+    notes.push(label + ": setup failed: " + String(error.message || error));
+    return { configured: false, changed: false };
+  }
+}
+
+for (const outcome of [
+  safeOutcome("Claude browser config", ensureClaudeBrowser),
+  safeOutcome("Claude settings", ensureClaudeSettings),
+  ...(process.env.UAI_CURSOR_MCP_PATH
+    ? [safeOutcome("Cursor browser config", ensureCursorBrowser)]
+    : []),
+  ...codexHomes.map(function (home) {
+    return safeOutcome(home, function () { return ensureCodexBrowser(home); });
+  }),
+]) {
+  configured = configured && outcome.configured;
+  changed = changed || outcome.changed;
+}
+
+console.log(
+  ${JSON.stringify(CONFIG_RESULT_TOKEN)} +
+    JSON.stringify({ configured: configured, changed: changed, notes: notes })
+);
+`;
+
+/**
+ * Start the watchable-browser stack (Xvfb → x11vnc → noVNC on :6080) if its
+ * binaries are installed and it isn't already up. x11vnc and websockify run
+ * under tiny restart loops — x11vnc EXITS whenever the X server it watches
+ * isn't up yet (the race that killed the first live run), and the loops
+ * also reattach after the display owner changes. Safe to run repeatedly:
+ * every piece is guarded by the X lockfile or a pidfile, loops included.
+ */
+/**
+ * The viewer daemons, one docker-exec each (the single-line nohup shape is
+ * the only one that reliably survives `docker exec -d`). Guards use the X
+ * lockfile and PIDFILES — never pgrep: a pgrep -f guard sharing a cmdline
+ * with its own payload self-matches and skips the start (this exact bug
+ * kept the stack down in every container until 2026-07-08).
+ *
+ * The pidfile tracks the LOOP SHELL, not the port. When a loop is orphaned
+ * — the display owner changes, or two ensures race, and the single pidfile
+ * only remembers the latest — the previous loop's websockify keeps holding
+ * 6080, and SO_REUSEADDR lets the new one bind alongside it. The kernel
+ * then round-robins connections across both, so the viewer lands on a live
+ * proxy only SOMETIMES and reconnects the rest (live 2026-09-02). So the
+ * start branch — reached only when the tracked loop is already dead — first
+ * reaps anything still holding the port, guaranteeing exactly one listener.
+ *
+ * That reap MUST be `pkill -A` (--ignore-ancestors). The step runs as
+ * `sh -c "<step>"`, so the launching shell's own cmdline carries the launch
+ * line and matches the reap pattern: plain `pkill -f` SIGTERMed that shell
+ * before it reached the nohup, and neither daemon ever started — host
+ * 0.9.94–0.9.96, every Linux runtime (the pgrep self-match above, wearing a
+ * kill; reproduced in the uai-linux VM: step exit 143, no pidfile). Both
+ * shipped images run procps-ng 4.0.2 (Debian bookworm), which has -A; an
+ * older procps rejects the flag with a usage error and reaps nothing, which
+ * merely restores the pre-reap behaviour and never the self-kill.
+ * `-A` protects the launching chain only: the apt worker below inlines
+ * these steps into `su -c` / `nohup sh -c` wrappers whose argv also
+ * matches, and a per-session reap that lands inside that worker's ~1 s
+ * viewer window can kill its node-uid shell. That only costs the worker
+ * its done-marker (set -e), so it re-runs on the next ensure and finds the
+ * pidfiles alive — self-healing, and no worse than the pre-reap world.
+ */
+const VIEWER_STEPS: string[] = [
+  // Xvfb — one-shot; the X lockfile is the truth (also set when an agent
+  // started the display itself). If it dies cleanly the lock clears and the
+  // next session ensure relaunches it. A lock whose pid is DEAD is the
+  // leftover of a SIGKILLed server — a sidecar restart kills its whole
+  // cgroup (live 2026-09-10, smoke 10: Xvfb gone, lock present, x11vnc
+  // looping on a display that never came back) — so clear it and the
+  // socket first, then launch as usual.
+  `[ -x /usr/bin/Xvfb ] || exit 0; if [ -e ${X_LOCK} ] && ! /usr/bin/kill -0 "$(/usr/bin/tr -d ' \\n' < ${X_LOCK})" 2>/dev/null; then /bin/rm -f ${X_LOCK} /tmp/.X11-unix/X${SERVER_DISPLAY.slice(1)}; fi; [ -e ${X_LOCK} ] || /usr/bin/nohup /usr/bin/${XVFB_CMD} >>/tmp/uai-xvfb.log 2>&1 &`,
+  // x11vnc under a restart loop (it exits whenever the X server isn't up
+  // yet). Pidfile-guarded.
+  `[ -x /usr/bin/x11vnc ] || exit 0; [ -f /tmp/uai-x11vnc.pid ] && /usr/bin/kill -0 "$(/usr/bin/cat /tmp/uai-x11vnc.pid)" 2>/dev/null && exit 0; /usr/bin/pkill -A -f 'x11vnc -display' 2>/dev/null; /usr/bin/nohup /bin/sh -c 'echo $$ > /tmp/uai-x11vnc.pid; while true; do /usr/bin/x11vnc -display ${SERVER_DISPLAY} -forever -shared -nopw -quiet >>/tmp/uai-x11vnc.log 2>&1; /bin/sleep 2; done' >/dev/null 2>&1 &`,
+  // websockify/noVNC under the same pattern.
+  `[ -x /usr/bin/websockify ] || exit 0; [ -f /tmp/uai-novnc.pid ] && /usr/bin/kill -0 "$(/usr/bin/cat /tmp/uai-novnc.pid)" 2>/dev/null && exit 0; /usr/bin/pkill -A -f 'websockify.*6080' 2>/dev/null; /usr/bin/nohup /bin/sh -c 'echo $$ > /tmp/uai-novnc.pid; while true; do /usr/bin/websockify --web=/usr/share/novnc 0.0.0.0:6080 localhost:5900 >>/tmp/uai-websockify.log 2>&1; /bin/sleep 2; done' >/dev/null 2>&1 &`,
+];
+
+const DEFAULT_NODE_BIN =
+  `/opt/asdf-data/installs/nodejs/${STANDARD_DEFAULT_NODE_VERSION}/bin`;
+const ROOT_RUNTIME_PATH =
+  `${DEFAULT_NODE_BIN}:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin`;
+// `npx` through ROOT_RUNTIME_PATH, not an absolute asdf path: the machine
+// image (ADR-121) carries no asdf — node is /usr/bin/node there — and the
+// absolute path made this worker exit 127 on every task machine, so its
+// done-marker was never written and each ensure re-ran it (live 2026-09-09).
+// The path lists the asdf bin first and never the shims, so a container
+// resolves exactly what it did before.
+const APT_DEPS_CMD =
+  `PATH=${ROOT_RUNTIME_PATH} npx ` +
+  "-y playwright@latest install-deps chromium";
+const APT_VIEWER_CMD =
+  "/usr/bin/apt-get install -y --no-install-recommends xvfb x11vnc novnc websockify";
+
+function aptGuardPaths(): { done: string; lock: string } {
+  const digest = createHash("sha256")
+    .update(JSON.stringify([APT_DEPS_CMD, APT_VIEWER_CMD, VIEWER_STEPS]))
+    .digest("hex")
+    .slice(0, 12);
+  const base = `/tmp/.uai-browser-apt-${digest}`;
+  return { done: `${base}.done`, lock: `${base}.lock` };
+}
+
+/** What a setup pass established. */
+export interface BrowserSetup {
+  /** The browser is installed and will launch. Retry while false. */
+  ready: boolean;
+  /** Every required engine has a usable browser MCP definition. */
+  configured: boolean;
+  /** A config had to be rewritten, so running agents hold a stale one. */
+  changed: boolean;
+}
+
+/**
+ * Wire the browser for a task.
+ *
+ * Reports readiness so the caller can retry a failed install instead of
+ * leaving live sessions pointed at a browser that will never launch, and
+ * reports whether a config was rewritten so they can be recycled onto it.
+ */
+export async function setupBrowserTesting(
+  taskId: string,
+  containerName: string,
+  hasCodex: boolean,
+  codexHomes: readonly string[] = hasCodex ? [DEFAULT_CODEX_HOME] : [],
+  environment?: Pick<TaskEnvironmentHandle, "exec" | "launchDetachedSession"> &
+    Partial<Pick<TaskEnvironmentHandle, "descriptor">>,
+  /** The roster's agent kinds: cursor and grok get the browser server too
+   * (2026-09-08 — until then only Claude/Codex were wired and both answered
+   * "no browser MCP in this session" on the Studio). */
+  engineKinds: readonly string[] = [],
+  /** Every GROK_HOME the task may run under (default + account homes). */
+  grokHomes: readonly string[] = [DEFAULT_GROK_HOME],
+): Promise<BrowserSetup> {
+  const hasCursor = engineKinds.includes("cursor");
+  const hasGrok = engineKinds.includes("grok");
+  const selectedGrokHomes = hasGrok
+    ? [...new Set(grokHomes.length > 0 ? grokHomes : [DEFAULT_GROK_HOME])]
+    : [];
+  // Machine sessions run under MACHINE_RUNTIME_AUTHORITY_ENV, so every setup
+  // exec here must too — the prewarm in particular. Warming npx under the
+  // CONTAINER authority (private NPM_CONFIG_CACHE) leaves the session-default
+  // npm cache cold, and Codex's 10s MCP startup deadline then kills the
+  // browser (and every npx-launched server) for the session's whole lifetime
+  // while Claude's 30s survives — live 2026-08-28, first codex machine task.
+  const authorityEnv =
+    isEnvironmentTransportProvider(environment?.descriptor?.locator.provider)
+      ? MACHINE_RUNTIME_AUTHORITY_ENV
+      : RUNTIME_AUTHORITY_ENV;
+  let ready = false;
+  let configured = false;
+  let changed = false;
+  // The no-handle fallbacks below exec by container name. The passed name is
+  // the Docker Compose replica shape; on the Apple backend the container has
+  // the provider's fixed name and the `docker` binary does not exist (live
+  // 2026-08-18: every fallback died with spawn docker ENOENT, which is why
+  // sessions never saw their browser MCP tools). Normalize both here.
+  const container = taskContainerBackend().apple
+    ? taskAppContainerName(taskId)
+    : containerName;
+  try {
+    const selectedCodexHomes = hasCodex
+      ? [...new Set(codexHomes.length > 0 ? codexHomes : [DEFAULT_CODEX_HOME])]
+      : [];
+    if (
+      selectedCodexHomes.some(
+        (home) =>
+          home !== DEFAULT_CODEX_HOME &&
+          !/^\/home\/node\/\.codex-acct-[A-Za-z0-9_-]+$/.test(home),
+      )
+    ) {
+      throw new Error("invalid Codex account home");
+    }
+
+    // The viewer stack restarts whenever it died (container restart, crash) —
+    // outside the marker guard on purpose. No-op until its packages install.
+    // ONE exec per daemon: the single-line nohup shape is the only one that
+    // reliably survives `docker exec -d`.
+    for (const step of VIEWER_STEPS) {
+      if (environment) {
+        await environment.launchDetachedSession({
+          projectEnvProfile: "maintenance",
+          argv: ["sh", "-c", step],
+          env: authorityEnv,
+          maxOutputBytes: 64 * 1024,
+          launchTimeoutMs: 10_000,
+        });
+      } else {
+        await taskContainerCli(
+          [
+            "exec",
+            "-d",
+            ...runtimeAuthorityDockerExecArgs(),
+            container,
+            "sh",
+            "-c",
+            step,
+          ],
+          { timeoutMs: 10_000 },
+        );
+      }
+    }
+
+    // Browser readiness — AWAITED, and deliberately OUTSIDE the marker guard.
+    //
+    // Awaited because the caller runs this before spawning agents, so this is
+    // the one place a slow install is merely slow. Detaching it (as this used
+    // to) hands the download to whoever hits the browser first, and the only
+    // candidate is the MCP server's own startup — which has a hard client
+    // deadline of 10s (Codex) / 30s (Claude Code). A cold host would lose its
+    // first session every time.
+    //
+    // Outside the guard because it is the only thing here that can be undone
+    // from outside: the volume is host-wide, so another container's Playwright
+    // can evict our build mid-task. Re-running it is how that heals — and it
+    // costs ~0.5s once the build is present.
+    const installed = environment
+      ? await (async () => {
+          const chown = await environment.exec({
+            projectEnvProfile: "maintenance",
+            argv: ["/usr/bin/chown", "node:node", "/opt/pw-browsers"],
+            user: "root",
+            env: authorityEnv,
+            timeoutMs: 5_000,
+            maxOutputBytes: 64 * 1024,
+          });
+          if (chown.exitCode !== 0) {
+            // Same non-fatal stance as the CLI path below.
+            console.warn(
+              `[browser] task ${taskId}: chown /opt/pw-browsers failed (status ${chown.exitCode}); ` +
+                `continuing with the prewarm. ${Buffer.from(chown.stderr).toString("utf8").slice(0, 200)}`,
+            );
+          }
+          return environment.exec({
+            projectEnvProfile: "maintenance",
+            argv: ["sh", "-lc", PREWARM_CMD],
+            cwd: "/workspace",
+            env: authorityEnv,
+            timeoutMs: INSTALL_TIMEOUT_MS,
+            maxOutputBytes: 256 * 1024,
+          });
+        })()
+      : await taskContainerCli(
+          [
+            "exec",
+            "-u",
+            "root",
+            ...runtimeAuthorityDockerExecArgs(),
+            container,
+            "/usr/bin/chown",
+            "node:node",
+            "/opt/pw-browsers",
+          ],
+          { timeoutMs: 5_000 },
+        ).then(async (chown) => {
+          if (chown.status !== 0) {
+            // Not fatal. On apple-container /opt/pw-browsers is a host-wide
+            // virtiofs volume whose ownership the guest cannot change (EPERM)
+            // although it is already node-owned inside the container; the
+            // prewarm below is the real test of writability, so let it decide.
+            console.warn(
+              `[browser] task ${taskId}: chown /opt/pw-browsers failed (status ${chown.status}); ` +
+                `continuing with the prewarm. ${chown.stderr.slice(0, 200)}`,
+            );
+          }
+          return taskContainerCli(
+            [
+              "exec",
+              "-w",
+              "/workspace",
+              ...runtimeAuthorityDockerExecArgs(),
+              container,
+              "sh",
+              "-lc",
+              PREWARM_CMD,
+            ],
+            { timeoutMs: INSTALL_TIMEOUT_MS },
+          );
+        });
+    const installedStatus =
+      "exitCode" in installed ? installed.exitCode : installed.status;
+    const installedStderr =
+      "stderr" in installed && installed.stderr instanceof Uint8Array
+        ? Buffer.from(installed.stderr).toString("utf8")
+        : typeof installed.stderr === "string"
+          ? installed.stderr
+          : "";
+    ready = installedStatus === 0;
+    if (!ready) {
+      // Agents still spawn — a task without a browser beats no task — but the
+      // caller retries on this, and it is logged loudly, because the symptom
+      // downstream (a browser that won't launch) reads as anything but an
+      // install that quietly failed up here.
+      console.warn(
+        `[browser] task ${taskId}: browser install failed (status ${installedStatus}); ` +
+          `see ${INSTALL_LOG} in the container. ${installedStderr.slice(0, 200)}`,
+      );
+    }
+
+    // Configs are re-asserted on EVERY call — no marker gate.
+    //
+    // A marker records what we once wrote, which is a different claim from
+    // what is on disk now. Recovery/start credential injection and account
+    // provisioning can replace config.toml before this serialized boundary
+    // (live auth refresh now excludes it). The marker lives in /workspace and
+    // survives those copies, so a gated setup could skip the rewrite and
+    // report ready while Codex had no browser at all. The migration is cheap
+    // and byte-idempotent, so the honest fix is to re-assert.
+    const writeTimeoutMs =
+      (10 + Math.max(45, 15 + selectedCodexHomes.length * 12) + 5 + 10) *
+      1_000;
+    const writeEnv = {
+      ...authorityEnv,
+      UAI_BROWSER_DEF: JSON.stringify(SERVER_DEF),
+      UAI_MCP_PATH: MCP_CONFIG_PATH,
+      UAI_CLAUDE_SETTINGS_PATH: CLAUDE_SETTINGS_PATH,
+      UAI_CLAUDE_SETTINGS_DEF: CLAUDE_SETTINGS_JSON,
+      ...(selectedCodexHomes.length > 0
+        ? { UAI_CODEX_HOMES: JSON.stringify(selectedCodexHomes) }
+        : {}),
+      ...(hasCursor ? { UAI_CURSOR_MCP_PATH: CURSOR_MCP_PATH } : {}),
+    };
+    const writeArgv = [
+      "flock",
+      "-w",
+      "10",
+      MCP_CONFIG_LOCK_PATH,
+      "timeout",
+      "--kill-after=5",
+      String(Math.max(45, 15 + selectedCodexHomes.length * 12)),
+      "node",
+      "-e",
+      MIGRATE_JS,
+    ] as [string, ...string[]];
+    const wrote = environment
+      ? await environment.exec({
+          projectEnvProfile: "maintenance",
+          argv: writeArgv,
+          cwd: "/workspace",
+          env: writeEnv,
+          timeoutMs: writeTimeoutMs,
+          maxOutputBytes: 256 * 1024,
+        })
+      : await taskContainerCli(
+          [
+            "exec",
+            "-w",
+            "/workspace",
+            "-e",
+            `UAI_BROWSER_DEF=${JSON.stringify(SERVER_DEF)}`,
+            "-e",
+            `UAI_MCP_PATH=${MCP_CONFIG_PATH}`,
+            "-e",
+            `UAI_CLAUDE_SETTINGS_PATH=${CLAUDE_SETTINGS_PATH}`,
+            "-e",
+            `UAI_CLAUDE_SETTINGS_DEF=${CLAUDE_SETTINGS_JSON}`,
+            ...(selectedCodexHomes.length > 0
+              ? ["-e", `UAI_CODEX_HOMES=${JSON.stringify(selectedCodexHomes)}`]
+              : []),
+            ...(hasCursor ? ["-e", `UAI_CURSOR_MCP_PATH=${CURSOR_MCP_PATH}`] : []),
+            ...runtimeAuthorityDockerExecArgs(),
+            container,
+            ...writeArgv,
+          ],
+          { timeoutMs: writeTimeoutMs },
+        );
+    const wroteStatus = "exitCode" in wrote ? wrote.exitCode : wrote.status;
+    const wroteStdout =
+      "stdout" in wrote && wrote.stdout instanceof Uint8Array
+        ? Buffer.from(wrote.stdout).toString("utf8")
+        : typeof wrote.stdout === "string"
+          ? wrote.stdout
+          : "";
+    const wroteStderr =
+      "stderr" in wrote && wrote.stderr instanceof Uint8Array
+        ? Buffer.from(wrote.stderr).toString("utf8")
+        : typeof wrote.stderr === "string"
+          ? wrote.stderr
+          : "";
+    if (wroteStatus !== 0) {
+      console.warn(
+        `[browser] task ${taskId}: MCP config write failed: ${wroteStderr.slice(0, 300)}`,
+      );
+    } else {
+      const resultLine = wroteStdout
+        .split(/\r?\n/)
+        .find((line) => line.startsWith(CONFIG_RESULT_TOKEN));
+      if (!resultLine) {
+        console.warn(
+          `[browser] task ${taskId}: MCP config write returned no result`,
+        );
+      } else {
+        try {
+          const result = JSON.parse(
+            resultLine.slice(CONFIG_RESULT_TOKEN.length),
+          ) as {
+            configured: boolean;
+            changed: boolean;
+            notes?: string[];
+          };
+          configured = result.configured === true;
+          changed = result.changed === true;
+          if (result.notes?.length) {
+            console.warn(`[browser] task ${taskId}: ${result.notes.join("; ")}`);
+          }
+        } catch (err) {
+          console.warn(
+            `[browser] task ${taskId}: invalid MCP config result`,
+            err,
+          );
+        }
+      }
+    }
+
+    // Grok registers through its own read-modify-write CLI (user scope,
+    // see grokBrowserAddCommand), under the same lock as gateway reconciliation
+    // so two successful CLI processes cannot silently lose each other's entry.
+    // A failure leaves the task configured-false so the next ensure retries.
+    if (hasGrok) {
+      const grokArgv = [
+        "flock",
+        "-w",
+        "10",
+        MCP_CONFIG_LOCK_PATH,
+        "sh",
+        "-lc",
+        selectedGrokHomes.map(grokBrowserAddCommand).join(" && "),
+      ] as [string, ...string[]];
+      const registered = environment
+        ? await environment.exec({
+            projectEnvProfile: "maintenance",
+            argv: grokArgv,
+            cwd: "/workspace",
+            env: authorityEnv,
+            timeoutMs: 30_000,
+            maxOutputBytes: 64 * 1024,
+          })
+        : await taskContainerCli(
+            [
+              "exec",
+              "-w",
+              "/workspace",
+              ...runtimeAuthorityDockerExecArgs(),
+              container,
+              ...grokArgv,
+            ],
+            { timeoutMs: 30_000 },
+          );
+      const grokStatus =
+        "exitCode" in registered ? registered.exitCode : registered.status;
+      if (grokStatus !== 0) {
+        configured = false;
+        console.warn(
+          `[browser] task ${taskId}: grok browser MCP registration failed (exit ${String(grokStatus)})`,
+        );
+      }
+    }
+
+    // Chromium apt libs + the viewer stack packages, then start the stack.
+    // The lock is a container-local flock acquired BEFORE detach. The worker
+    // inherits its open file description, so failures and even SIGKILL release
+    // it in the kernel and the next ensure can retry; no stale mkdir lock can
+    // strand the container forever.
+    //
+    // `install-deps` stays on floating `playwright@latest` on purpose: it
+    // installs apt SYSTEM LIBRARIES (libnss3, libatk, …), which are shared
+    // across Chromium builds and carry no build number, so they cannot
+    // participate in the mismatch MCP_PKG exists to prevent. It also touches
+    // no browser binaries, so it cannot GC the shared volume. Pinning it
+    // would mean a second version constant to keep in sync — reintroducing
+    // exactly the drift class this change removes.
+    const aptGuard = aptGuardPaths();
+    const viewerSetup = VIEWER_STEPS.map((step) => `( ${step} )`).join("; ");
+    const aptWorker = [
+      "set -e",
+      APT_DEPS_CMD,
+      APT_VIEWER_CMD,
+      // Close lock fd 9 before starting long-lived viewer grandchildren, or
+      // they inherit it and keep the apt lock forever after this worker exits.
+      `/usr/bin/su -s /bin/sh node -c ${shellQuote(viewerSetup)} 9>&-`,
+      "/usr/bin/chown -R node:node /home/node/.npm 2>/dev/null || true",
+      `/usr/bin/touch ${aptGuard.done}`,
+    ].join("; ");
+    const guardedAptStart = [
+      `[ -f ${aptGuard.done} ] && exit 0`,
+      `exec 9>${aptGuard.lock}`,
+      "/usr/bin/flock -n 9 || exit 0",
+      // A different worker may have completed between the first check and
+      // this lock acquisition.
+      `[ -f ${aptGuard.done} ] && exit 0`,
+      `/usr/bin/nohup /bin/sh -c ${shellQuote(aptWorker)} 9>&9 </dev/null ` +
+        ">/tmp/uai-pw-deps.log 2>&1 &",
+    ].join("; ");
+
+    const rootWorkerEnv = {
+      ...authorityEnv,
+      NPM_CONFIG_CACHE: "/tmp/uai-root-npm-cache",
+      npm_config_cache: "/tmp/uai-root-npm-cache",
+      NPM_CONFIG_LOGS_DIR: "/tmp/uai-root-npm-cache/_logs",
+      npm_config_logs_dir: "/tmp/uai-root-npm-cache/_logs",
+    };
+    if (environment) {
+      await environment.exec({
+        projectEnvProfile: "maintenance",
+        argv: ["/bin/sh", "-c", guardedAptStart],
+        user: "root",
+        cwd: "/workspace",
+        env: rootWorkerEnv,
+        timeoutMs: 10_000,
+        maxOutputBytes: 64 * 1024,
+      });
+    } else {
+      await taskContainerCli(
+        [
+          "exec",
+          "-u",
+          "root",
+          // HOME=/home/node is for asdf version resolution ONLY — without the
+          // cache redirect below, root's npx writes ROOT-OWNED entries into
+          // node's ~/.npm and breaks the node user's own npx (which launches
+          // the MCP server). Found live 2026-07-08.
+          "-w",
+          "/workspace",
+          ...runtimeAuthorityDockerExecArgs(),
+          // These root-worker exceptions must follow the common authority args:
+          // Docker/npm use the final value when a spelling is repeated. Keep
+          // both cases aligned so npm's case-insensitive config lookup cannot
+          // fall back to node's private cache or logs directory.
+          "-e",
+          "NPM_CONFIG_CACHE=/tmp/uai-root-npm-cache",
+          "-e",
+          "npm_config_cache=/tmp/uai-root-npm-cache",
+          "-e",
+          "NPM_CONFIG_LOGS_DIR=/tmp/uai-root-npm-cache/_logs",
+          "-e",
+          "npm_config_logs_dir=/tmp/uai-root-npm-cache/_logs",
+          container,
+          "/bin/sh",
+          "-c",
+          guardedAptStart,
+        ],
+        { timeoutMs: 10_000 },
+      );
+    }
+    console.log(
+      `[browser] task ${taskId}: Playwright MCP wired (browser ${ready ? "ready" : "NOT ready"}; apt deps backgrounded)`,
+    );
+    return { ready, configured, changed };
+  } catch (err) {
+    // Best-effort by design — a task without a browser still runs.
+    console.warn(`[browser] task ${taskId}: setup failed`, err);
+    return { ready, configured, changed };
+  }
+}
+
+/** Single-quote for `sh -c` (POSIX-safe). */
+function shellQuote(text: string): string {
+  return `'${text.replace(/'/g, `'\\''`)}'`;
+}