@runuai/host 0.8.42 → 0.8.44

package/lib/browser-testing.ts

@@ -2,42 +2,190 @@
  * ADR-053: in-container browser for agents — Playwright MCP wiring.
  *
  * When a task's project opted into browser testing, session start calls
- * `setupBrowserTesting`, which (idempotently, via a versioned marker file)
- * writes the MCP config for BOTH engines and kicks the installs in the
- * background:
+ * `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.
- *   - `~/.codex/config.toml` — an `[mcp_servers.browser]` block (appended
- *     once; the task owns a private copy of this file).
+ *   - 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, pgrep-guarded, so it survives container
- * restarts.
+ * (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. Everything here is
- * best-effort and never blocks session start.
+ * 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 { dockerCli } from "./docker-exec";
+import { createHash } from "node:crypto";
 
-// v3: self-sufficient MCP launcher + loop-wrapped viewer daemons. Bumping
-// re-runs setup on live channels; config writes stay `[ -f ] ||`-guarded so
-// a task keeps the configs it started with.
-const MARKER = "/workspace/.uai/.browser-mcp-ready-v3";
+import { dockerCli } from "./docker-exec";
+import { MCP_CONFIG_LOCK_PATH } from "./mcp-config-lock";
 
 const SERVER_DISPLAY = ":99";
-const XVFB_CMD = `Xvfb ${SERVER_DISPLAY} -screen 0 1440x900x24 -nolisten tcp`;
+/**
+ * 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
@@ -53,28 +201,32 @@ const XVFB_CMD = `Xvfb ${SERVER_DISPLAY} -screen 0 1440x900x24 -nolisten tcp`;
 // 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 @playwright/mcp@latest --browser chromium --no-sandbox; ` +
+  `exec npx -y ${MCP_PKG} --config ${MCP_LAUNCH_CONFIG} ` +
+  `--browser ${BROWSER} --no-sandbox; ` +
   `else ` +
-  `exec npx -y @playwright/mcp@latest --browser chromium --no-sandbox --headless; ` +
+  `exec npx -y ${MCP_PKG} --config ${MCP_LAUNCH_CONFIG} ` +
+  `--browser ${BROWSER} --no-sandbox --headless; ` +
   `fi`;
 
 const SERVER_COMMAND = "sh";
-const SERVER_ARGS = ["-lc", SERVER_LAUNCHER];
+/** Exported for the test that locks the pin/browser invariants. */
+export const SERVER_ARGS: [string, string] = ["-lc", SERVER_LAUNCHER];
 
-const MCP_JSON = JSON.stringify(
-  {
-    mcpServers: {
-      browser: { command: SERVER_COMMAND, args: SERVER_ARGS },
-    },
-  },
-  null,
-  2,
-);
+/** The `browser` server definition both engines get. */
+const SERVER_DEF = { command: SERVER_COMMAND, args: SERVER_ARGS };
 
 const CLAUDE_SETTINGS_JSON = JSON.stringify(
   { enableAllProjectMcpServers: true },
@@ -82,14 +234,687 @@ const CLAUDE_SETTINGS_JSON = JSON.stringify(
   2,
 );
 
-const CODEX_TOML = [
-  "",
-  "# uai ADR-053: in-container browser (Playwright MCP)",
-  "[mcp_servers.browser]",
-  `command = '${SERVER_COMMAND}'`,
-  `args = [${SERVER_ARGS.map((a) => `'${a}'`).join(", ")}]`,
-  "",
-].join("\n");
+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("Uai 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 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,
+    timeout: 5000,
+    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),
+  ...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
@@ -118,12 +943,59 @@ const VIEWER_STEPS: string[] = [
   `command -v websockify >/dev/null 2>&1 || exit 0; [ -f /tmp/uai-novnc.pid ] && kill -0 "$(cat /tmp/uai-novnc.pid)" 2>/dev/null && exit 0; nohup sh -c 'echo $$ > /tmp/uai-novnc.pid; while true; do websockify --web=/usr/share/novnc 0.0.0.0:6080 localhost:5900 >>/tmp/uai-websockify.log 2>&1; sleep 2; done' >/dev/null 2>&1 &`,
 ];
 
+const APT_DEPS_CMD = "npx -y playwright@latest install-deps chromium";
+const APT_VIEWER_CMD =
+  "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,
-): Promise<void> {
+  codexHomes: readonly string[] = hasCodex ? [DEFAULT_CODEX_HOME] : [],
+): Promise<BrowserSetup> {
+  let ready = false;
+  let configured = false;
+  let changed = false;
   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
@@ -134,65 +1006,165 @@ export async function setupBrowserTesting(
       });
     }
 
-    const marked = await dockerCli(
-      ["exec", containerName, "test", "-f", MARKER],
+    // 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.
+    await dockerCli(
+      ["exec", "-u", "root", containerName, "chown", "node:node", "/opt/pw-browsers"],
       { timeoutMs: 5_000 },
     );
-    if (marked.status === 0) return;
-
-    const script = [
-      "set -e",
-      "mkdir -p /workspace/.uai /workspace/.claude",
-      // Claude: project-scoped MCP config + auto-approve setting. The
-      // workspace is fresh per task, so plain writes are safe; keep them
-      // conditional anyway so a human's later edits survive re-runs.
-      `[ -f /workspace/.mcp.json ] || printf '%s\\n' ${shellQuote(MCP_JSON)} > /workspace/.mcp.json`,
-      `[ -f /workspace/.claude/settings.json ] || printf '%s\\n' ${shellQuote(CLAUDE_SETTINGS_JSON)} > /workspace/.claude/settings.json`,
-      ...(hasCodex
-        ? [
-            // Codex: append once to the task's PRIVATE config copy.
-            `grep -q "mcp_servers.browser" /home/node/.codex/config.toml 2>/dev/null || printf '%s' ${shellQuote(CODEX_TOML)} >> /home/node/.codex/config.toml`,
-          ]
-        : []),
-      `touch ${MARKER}`,
-    ].join(" && ");
-
-    const wrote = await dockerCli(
-      ["exec", containerName, "sh", "-lc", script],
-      { timeoutMs: 20_000 },
+    const installed = await dockerCli(
+      ["exec", "-w", "/workspace", containerName, "sh", "-lc", PREWARM_CMD],
+      { timeoutMs: INSTALL_TIMEOUT_MS },
     );
-    if (wrote.status !== 0) {
+    ready = installed.status === 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}: MCP config write failed: ${wrote.stderr.slice(0, 300)}`,
+        `[browser] task ${taskId}: browser install failed (status ${installed.status}); ` +
+          `see ${INSTALL_LOG} in the container. ${installed.stderr.slice(0, 200)}`,
       );
-      return;
     }
 
-    // Volume ownership, then the browser download as NODE (host-wide
-    // one-timer on the shared volume).
-    await dockerCli(
-      ["exec", "-u", "root", containerName, "chown", "node:node", "/opt/pw-browsers"],
-      { timeoutMs: 5_000 },
-    );
-    await dockerCli(
+    // 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 wrote = await dockerCli(
       [
         "exec",
-        "-d",
+        // asdf resolves node only where a .tool-versions applies.
         "-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)}`]
+          : []),
         containerName,
-        "sh",
-        "-lc",
-        "npx -y playwright@latest install chromium >/tmp/uai-pw-browser.log 2>&1 || true",
+        "flock",
+        "-w",
+        "10",
+        MCP_CONFIG_LOCK_PATH,
+        "timeout",
+        "--kill-after=5",
+        String(
+          Math.max(45, 15 + selectedCodexHomes.length * 12),
+        ),
+        "node",
+        "-e",
+        MIGRATE_JS,
       ],
-      { timeoutMs: 10_000 },
+      {
+        // Lock wait + the per-home-scaled in-container bound + SIGKILL grace,
+        // with ten seconds left for Docker/process overhead. The host must
+        // never win this race: killing docker exec does not kill its child.
+        timeoutMs:
+          (10 +
+            Math.max(45, 15 + selectedCodexHomes.length * 12) +
+            5 +
+            10) *
+          1_000,
+      },
     );
-    // Chromium apt libs + the viewer stack packages, then start the stack —
-    // one ordered root chain, backgrounded, per-container.
+    if (wrote.status !== 0) {
+      console.warn(
+        `[browser] task ${taskId}: MCP config write failed: ${wrote.stderr.slice(0, 300)}`,
+      );
+    } else {
+      const resultLine = wrote.stdout
+        .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,
+          );
+        }
+      }
+    }
+
+    // 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.
+      `su -s /bin/sh node -c ${shellQuote(viewerSetup)} 9>&-`,
+      "chown -R node:node /home/node/.npm 2>/dev/null || true",
+      `touch ${aptGuard.done}`,
+    ].join("; ");
+    const guardedAptStart = [
+      `[ -f ${aptGuard.done} ] && exit 0`,
+      `exec 9>${aptGuard.lock}`,
+      "flock -n 9 || exit 0",
+      // A different worker may have completed between the first check and
+      // this lock acquisition.
+      `[ -f ${aptGuard.done} ] && exit 0`,
+      `nohup sh -lc ${shellQuote(aptWorker)} 9>&9 </dev/null ` +
+        ">/tmp/uai-pw-deps.log 2>&1 &",
+    ].join("; ");
+
     await dockerCli(
       [
         "exec",
-        "-d",
         "-u",
         "root",
         // HOME=/home/node is for asdf version resolution ONLY — without the
@@ -208,24 +1180,18 @@ export async function setupBrowserTesting(
         containerName,
         "sh",
         "-lc",
-        "{ npx -y playwright@latest install-deps chromium && " +
-          "apt-get install -y --no-install-recommends xvfb x11vnc novnc websockify && " +
-          // Older-image containers get their packages only HERE (post-apt),
-          // so kick the viewer daemons now. Each step subshelled: the steps'
-          // internal `exit 0` guards must not abort their siblings.
-          `su -s /bin/sh node -c '${VIEWER_STEPS.map((s) => `( ${s} )`)
-            .join("; ")
-            .replace(/'/g, `'\\''`)}'; ` +
-          // Heal any damage a pre-fix host already did to the cache.
-          "chown -R node:node /home/node/.npm 2>/dev/null; } " +
-          ">/tmp/uai-pw-deps.log 2>&1 || true",
+        guardedAptStart,
       ],
       { timeoutMs: 10_000 },
     );
-    console.log(`[browser] task ${taskId}: Playwright MCP wired (installs backgrounded)`);
+    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 };
   }
 }