@moondeck/station 0.0.0-stage → 1.0.0

package/lib/mcp-gateway.ts

@@ -0,0 +1,2594 @@
+/**
+ * MCP gateway (ADR-057) — the host-side proxy that puts the owner's MCP
+ * connections in front of task containers WITHOUT the credentials ever
+ * entering them.
+ *
+ * Containers call `http://<gateway-host>:<port>/t/<token>/<slug>` (Docker:
+ * host.docker.internal; Apple: the vmnet gateway IP); the
+ * gateway resolves the per-task token to an ACL file written at session
+ * ensure (which connections this task may use), attaches the connection's
+ * Authorization header host-side (refreshing OAuth tokens as needed), and
+ * streams the MCP traffic through (streamable HTTP + SSE). Every request
+ * lands in an audit JSONL. Disconnecting a connection kills its secrets in
+ * the host store, so the gateway 401s instantly — the kill switch.
+ *
+ * VERIFY-ON-MAC: OrbStack forwards host.docker.internal to loopback-bound
+ * host services; if not, set UAI_MCP_GATEWAY_BIND=0.0.0.0 (the unguessable
+ * per-task token stays the auth).
+ *
+ * ADR-154 §11: a task on cloud credentials is served from its lease instead
+ * (credential-consumers/mcp.ts): the header comes from memory, every request
+ * goes through the SSRF rule, and an expired or refused OAuth token is
+ * refreshed by the cloud's broker, never here. On a runner past its
+ * credentials floor nothing falls back to the local store.
+ */
+
+import {
+  appendFileSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import {
+  createServer as createHttpServer,
+  type IncomingMessage,
+  type Server as HttpServer,
+  type ServerResponse,
+} from "node:http";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import {
+  createServer as createNetServer,
+  type Server as NetServer,
+  type Socket,
+} from "node:net";
+import { Readable, pipeline } from "node:stream";
+import { resolve } from "node:path";
+
+import { env } from "./env";
+import {
+  appleContainerRuntimeBinding,
+  pinnedContainerRuntimeProvider,
+} from "./container-runtime";
+import {
+  taskAppContainerName,
+  taskContainerBackend,
+  taskContainerCli,
+} from "./task-container-cli";
+import { MCP_CONFIG_LOCK_PATH } from "./mcp-config-lock";
+import {
+  RUNTIME_AUTHORITY_ENV,
+  runtimeAuthorityDockerExecArgs,
+} from "./runtime-authority";
+import type { TaskEnvironmentHandle } from "./task-environment/types";
+import { LeftOwnCredentialsError, onOwnCredentials, whileOnOwnCredentials } from "./cloud-credential-host";
+import { authHeaderFor, getConnection } from "./mcp-connections";
+import {
+  forgetLeasedMcp,
+  holdLeasedMcp,
+  leasedMcpFor,
+  type McpRequestHold,
+  type LeasedMcpConnection,
+} from "./credential-consumers/mcp";
+import { safeRequest, type SafeHttpDeps, type SafeHttpResponse } from "./safe-http";
+import { agentClisReady } from "./standard-image";
+import { isSafeHostTaskId, assertSafeHostTaskId } from "./task-identity";
+import type { McpGatewayCapability } from "../src/protocol";
+import { isEnvironmentTransportProvider } from "./task-environment/types";
+import { sidecarTaskId } from "./sidecar";
+import {
+  TASK_FORWARDER_ACCEPT_MAGIC,
+  TASK_FORWARDER_MAX_PREAMBLE_BYTES,
+  TASK_FORWARDER_PREAMBLE_HEADER_BYTES,
+  TASK_FORWARDER_RESPONSE_BYTES,
+  decodeTaskForwarderPreamble,
+  decodeTaskForwarderResponse,
+  encodeTaskForwarderChallenge,
+  taskForwarderPreambleLength,
+  type TaskForwarderIdentity,
+} from "./task-gateway-protocol";
+import {
+  currentTaskGatewayRegistration,
+  isTaskGatewayGenerationCurrent,
+  resolveTaskGatewayEnv,
+  subscribeTaskGatewayRevocations,
+  verifyTaskGatewayAuthentication,
+} from "./task-gateway-state";
+import { MCP_GATEWAY_PORT } from "./task-gateway-port";
+import { MAX_MANIFEST_MCP } from "../src/cloud-credentials";
+
+export type { McpGatewayCapability } from "../src/protocol";
+
+export { MCP_GATEWAY_PORT };
+
+/** Loopback works only where the container runtime forwards
+ * host.docker.internal INTO the host loopback — macOS Docker
+ * (Desktop/OrbStack). Native Linux docker resolves host.docker.internal to
+ * the bridge gateway IP, where a loopback bind is unreachable: every task's
+ * MCP config carried a dead URL and the gateway showed connection-refused
+ * from inside containers (live 2026-08-24, first Linux host with an MCP
+ * connection). Apple vmnet guests cannot reach host loopback either. Both
+ * non-mac-docker cases therefore bind all interfaces — the unguessable
+ * per-task path token remains the auth (same posture the operator override
+ * has always allowed). Resolved per call: the runtime pin lands before the
+ * production listener starts, and a pin never changes within a process. */
+function gatewayBindAddress(): string {
+  const configured = process.env.UAI_MCP_GATEWAY_BIND;
+  if (configured) return configured;
+  // The pin, not the ready-gated identity: the production listener starts
+  // during boot while activation still reports `checking`, and a loopback
+  // bind chosen then would strand every vmnet guest.
+  if (pinnedContainerRuntimeProvider() === "apple-container") return "0.0.0.0";
+  return process.platform === "darwin" ? "127.0.0.1" : "0.0.0.0";
+}
+
+/** Host address a task container dials to reach this gateway. Docker guests
+ * resolve host.docker.internal; Apple vmnet guests dial the vmnet gateway IP,
+ * read once per process from the bundled CLI's network inspection (the
+ * builtin `default` network the app containers join). A resolution failure
+ * throws so the config write fails visibly and is retried on the next session
+ * ensure, rather than baking a dead URL into the task. */
+let cachedAppleGatewayHost: string | null = null;
+export async function taskGatewayHost(): Promise<string> {
+  if (pinnedContainerRuntimeProvider() !== "apple-container") {
+    return "host.docker.internal";
+  }
+  if (cachedAppleGatewayHost !== null) return cachedAppleGatewayHost;
+  const binding = appleContainerRuntimeBinding();
+  if (binding === null) {
+    throw new Error("apple-container selected without a bundled CLI binding");
+  }
+  const { execFile } = await import("node:child_process");
+  const stdout = await new Promise<string>((resolveExec, rejectExec) => {
+    execFile(
+      binding.containerCliPath,
+      ["network", "inspect", "default"],
+      { timeout: 15_000, maxBuffer: 256 * 1024 },
+      (error, out) => (error ? rejectExec(error) : resolveExec(out)),
+    );
+  });
+  const parsed = JSON.parse(stdout) as Array<{
+    status?: { ipv4Gateway?: unknown };
+  }>;
+  const gateway = parsed[0]?.status?.ipv4Gateway;
+  if (
+    typeof gateway !== "string" ||
+    !/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(gateway)
+  ) {
+    throw new Error("could not resolve the vmnet gateway address");
+  }
+  cachedAppleGatewayHost = gateway;
+  return gateway;
+}
+/** MCP request bodies are small JSON-RPC frames; cap so audit parsing (and a
+ *  hostile container) can't balloon host memory. Responses stream freely. */
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+/** Bounds the upstream CONNECT (until response headers) only. The response
+ *  BODY must never be time-bounded: MCP streamable-HTTP clients hold SSE
+ *  streams open indefinitely, and an abort mid-pipe once took the whole host
+ *  process down as an unhandled Readable 'error' (2026-07-13). */
+const UPSTREAM_CONNECT_TIMEOUT_MS = 60_000;
+const GATEWAY_RETRY_INITIAL_DELAY_MS = 1_000;
+const GATEWAY_RETRY_MAX_DELAY_MS = 15_000;
+const GATEWAY_RETRY_MIN_JITTER = 0.8;
+const GATEWAY_RETRY_JITTER_SPAN = 0.4;
+const TASK_GATEWAY_PREAUTH_TIMEOUT_MS = 3_000;
+const TASK_GATEWAY_MAX_PENDING_PREAUTH = 128;
+const TASK_GATEWAY_MAX_PENDING_PREAUTH_PER_PEER = 16;
+const TASK_GATEWAY_MAX_PENDING_PREAUTH_PER_TASK = 16;
+// MCP streamable-HTTP/SSE and proxied WebSockets can legitimately hold a
+// connection for the life of a session, so active limits are deliberately
+// separate from the tight three-second handshake limits above. They are still
+// finite: once a socket has supplied its first application byte, HTTP's header
+// and request deadlines bound time, while these counters bound cardinality.
+const TASK_GATEWAY_MAX_ACTIVE_CONNECTIONS = 2_048;
+// Direct sockets have not proved which task they belong to yet. Treat this as
+// a small, evictable staging allowance; tokenized MCP moves to the task quota
+// as soon as Node parses and validates the request path.
+const TASK_GATEWAY_MAX_DIRECT_STAGING_CONNECTIONS_PER_PEER = 16;
+const TASK_GATEWAY_MAX_ACTIVE_CONNECTIONS_PER_TASK = 256;
+
+export interface TaskMcpConnection {
+  id: string;
+  slug: string;
+}
+
+interface TaskAcl {
+  token: string;
+  connections: TaskMcpConnection[];
+}
+
+function aclDir(): string {
+  return resolve(env.dataDir, "mcp-gateway");
+}
+
+function aclPath(taskId: string): string {
+  return resolve(aclDir(), `${taskId}.json`);
+}
+
+function readAcl(taskId: string): TaskAcl | null {
+  try {
+    return JSON.parse(readFileSync(aclPath(taskId), "utf8")) as TaskAcl;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write/refresh the task's gateway ACL (the connection set snapshots the
+ * cloud's latest ensure input). The token is minted once per task and
+ * survives re-ensures so already-written .mcp.json files stay valid.
+ */
+export function ensureTaskGatewayAcl(
+  taskId: string,
+  connections: TaskMcpConnection[],
+): TaskAcl {
+  const existing = readAcl(taskId);
+  const acl: TaskAcl = {
+    token: existing?.token ?? `${taskId}.${randomBytes(24).toString("base64url")}`,
+    connections,
+  };
+  mkdirSync(aclDir(), { recursive: true, mode: 0o700 });
+  writeFileSync(aclPath(taskId), JSON.stringify(acl), { mode: 0o600 });
+  return acl;
+}
+
+export function clearTaskGatewayAcl(taskId: string): void {
+  // Defense in depth: the id becomes a filesystem path component, and some
+  // callers derive it from container-influenced data (labels). A traversal
+  // like `../container-runtime-provider` must never resolve outside the ACL
+  // directory, so an unsafe id is a no-op here rather than a deletion.
+  if (!isSafeHostTaskId(taskId)) return;
+  forgetLeasedMcp(taskId);
+  try {
+    rmSync(aclPath(taskId));
+  } catch {
+    // already gone
+  }
+}
+
+/** Strict variant used only when acknowledging orphan-GC completion. */
+export function clearTaskGatewayAclStrict(taskId: string): void {
+  assertSafeHostTaskId(taskId);
+  const path = aclPath(taskId);
+  rmSync(path, { force: true });
+  try {
+    lstatSync(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  throw new Error("task gateway ACL remains after removal");
+}
+
+function audit(entry: Record<string, unknown>): void {
+  try {
+    const dir = resolve(env.dataDir, "logs");
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(
+      resolve(dir, "mcp-audit.jsonl"),
+      `${JSON.stringify({ ts: Date.now(), ...entry })}\n`,
+    );
+  } catch {
+    // audit is best-effort
+  }
+}
+
+function deny(res: ServerResponse, status: number, message: string): void {
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(JSON.stringify({ error: message }));
+}
+
+/** The request's body, or null past MAX_BODY_BYTES. With `signal`, an abort
+ *  ends the request where it is (the read rejects): a task that stops
+ *  sending mid-body never holds what waits for its request to end. */
+async function readBody(req: IncomingMessage, signal?: AbortSignal): Promise<Buffer | null> {
+  const stop = (): void => {
+    req.destroy(new Error("request ended"));
+  };
+  if (signal?.aborted) stop();
+  else signal?.addEventListener("abort", stop, { once: true });
+  try {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    for await (const chunk of req) {
+      const buf = chunk as Buffer;
+      size += buf.length;
+      if (size > MAX_BODY_BYTES) return null;
+      chunks.push(buf);
+    }
+    return Buffer.concat(chunks);
+  } finally {
+    signal?.removeEventListener("abort", stop);
+  }
+}
+
+/** JSON-RPC method (+ tool name for tools/call) out of a request body. */
+function rpcSummary(body: Buffer): { method?: string; tool?: string } {
+  try {
+    const json = JSON.parse(body.toString("utf8")) as {
+      method?: string;
+      params?: { name?: string };
+    };
+    return {
+      method: typeof json.method === "string" ? json.method : undefined,
+      tool:
+        json.method === "tools/call" && typeof json.params?.name === "string"
+          ? json.params.name
+          : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+const FORWARD_REQ_HEADERS = [
+  "content-type",
+  "accept",
+  "mcp-session-id",
+  "last-event-id",
+  "mcp-protocol-version",
+];
+const FORWARD_RES_HEADERS = ["content-type", "mcp-session-id"];
+
+export interface AuthenticatedTaskGatewayConnection
+  extends TaskForwarderIdentity {
+  readonly socket: Socket;
+  /** Re-check immediately before using task authority. */
+  readonly isCurrent: () => boolean;
+}
+
+export type TaskGatewayTlsHandler = (
+  connection: AuthenticatedTaskGatewayConnection,
+) => void;
+
+let taskGatewayTlsHandler: TaskGatewayTlsHandler | null = null;
+
+/**
+ * Register the TLS consumer used by the ADR-153 secrets proxy. There is one
+ * gateway and therefore one consumer; a second registration is a wiring bug.
+ */
+export function registerTaskGatewayTlsHandler(
+  handler: TaskGatewayTlsHandler,
+): () => void {
+  if (taskGatewayTlsHandler !== null) {
+    throw new Error("task gateway TLS handler is already registered");
+  }
+  taskGatewayTlsHandler = handler;
+  return () => {
+    if (taskGatewayTlsHandler === handler) taskGatewayTlsHandler = null;
+  };
+}
+
+function loopbackPeer(socket: Socket): boolean {
+  const address = socket.remoteAddress ?? "";
+  return (
+    address === "::1" ||
+    /^127(?:\.\d{1,3}){3}$/.test(address) ||
+    /^::ffff:127(?:\.\d{1,3}){3}$/i.test(address)
+  );
+}
+
+async function handleEnvRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  identity: TaskForwarderIdentity | null,
+): Promise<void> {
+  // Keep the task hook's deliberately tiny response grammar stable. Node adds
+  // Date by default, but the response is local, non-cacheable, and has no use
+  // for a wall-clock header.
+  res.sendDate = false;
+  if (identity === null) return deny(res, 404, "not found");
+  if (req.method !== "GET") {
+    res.setHeader("allow", "GET");
+    return deny(res, 405, "method not allowed");
+  }
+  const snapshot = resolveTaskGatewayEnv(identity);
+  if (snapshot === null) return deny(res, 503, "task env unavailable");
+  const headers = {
+    etag: snapshot.etag,
+    "cache-control": "no-store",
+  };
+  if (req.headers["if-none-match"] === snapshot.etag) {
+    res.writeHead(304, { ...headers, "content-length": "0" });
+    res.end();
+    return;
+  }
+  res.writeHead(200, {
+    ...headers,
+    "content-type": "text/plain; charset=utf-8",
+    "content-length": String(snapshot.body.length),
+  });
+  res.end(snapshot.body);
+}
+
+async function handleMcpRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  claimTaskQuota: (socket: Socket, taskId: string) => boolean,
+): Promise<void> {
+  const match = /^\/t\/([^/]+)\/([^/?]+)\/?(?:\?.*)?$/.exec(req.url ?? "");
+  if (!match) return deny(res, 404, "not found");
+  const [, token, slug] = match as unknown as [string, string, string];
+
+  const taskId = token.split(".")[0] ?? "";
+  const acl = readAcl(taskId);
+  const expected = acl ? Buffer.from(acl.token) : null;
+  const provided = Buffer.from(token);
+  if (
+    !acl ||
+    !expected ||
+    expected.length !== provided.length ||
+    !timingSafeEqual(expected, provided)
+  ) {
+    return deny(res, 401, "unknown task token");
+  }
+  // A direct connection is admitted only to an evictable peer staging pool.
+  // Once its unguessable ACL token proves the task, move the close-scoped
+  // reservation into that task's quota before using any task authority. An
+  // authenticated forwarder is already in this quota, and must name the same
+  // task if it sends an MCP request over its connection.
+  if (!claimTaskQuota(req.socket, taskId)) {
+    res.shouldKeepAlive = false;
+    res.setHeader("connection", "close");
+    return deny(res, 429, "task connection limit reached");
+  }
+  // ADR-154 §11: a task on cloud credentials is served from its lease.
+  const lease = leasedMcpFor(taskId);
+  if (lease || leaseOnly) {
+    if (!lease?.open) return deny(res, 503, "credentials unavailable");
+    const leased = lease.connections.get(slug);
+    if (!leased) return deny(res, 404, `no connection "${slug}" for this task`);
+    // Named but unreadable: unavailable, never "no such connection".
+    const hold = "unavailable" in leased ? null : holdLeasedMcp(taskId, slug);
+    if (!hold) return deny(res, 503, "credentials unavailable");
+    return serveLeasedConnection(req, res, taskId, hold);
+  }
+  // ADR-154: the runner's own connections only while it is on its own
+  // credentials; from the moment it begins leaving them, none is read.
+  if (!onOwnCredentials()) return deny(res, 503, "credentials unavailable");
+  const entry = acl.connections.find((c) => c.slug === slug);
+  if (!entry) return deny(res, 404, `no connection "${slug}" for this task`);
+  const conn = getConnection(entry.id);
+  if (!conn || conn.status !== "connected") {
+    // Disconnected since the task started — the kill switch answering.
+    return deny(res, 401, `connection "${slug}" is no longer available`);
+  }
+
+  const body =
+    req.method === "POST" || req.method === "PUT" ? await readBody(req) : null;
+  if ((req.method === "POST" || req.method === "PUT") && body === null) {
+    return deny(res, 413, "request body too large");
+  }
+
+  const headers: Record<string, string> = {};
+  for (const name of FORWARD_REQ_HEADERS) {
+    const v = req.headers[name];
+    if (typeof v === "string") headers[name] = v;
+  }
+
+  // The controller lives for the whole exchange: the timer only guards the
+  // connect phase (cleared once headers land), and a client hang-up reaps the
+  // upstream so dead streams don't accumulate.
+  const controller = new AbortController();
+  res.on("close", () => controller.abort());
+
+  const attempt = async (forceRefresh: boolean): Promise<Response> => {
+    // Counted (leaving waits for a refresh under way), and never a local
+    // header sent once leaving has begun, however long the read took.
+    const reading = whileOnOwnCredentials(() => authHeaderFor(conn, forceRefresh));
+    if (reading === null) throw new LeftOwnCredentialsError();
+    const auth = await reading;
+    if (!onOwnCredentials()) throw new LeftOwnCredentialsError();
+    if (auth) headers[auth.name] = auth.value;
+    const connectTimer = setTimeout(
+      () => controller.abort(),
+      UPSTREAM_CONNECT_TIMEOUT_MS,
+    );
+    try {
+      return await fetch(conn.url, {
+        method: req.method,
+        headers,
+        body: body ?? undefined,
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(connectTimer);
+    }
+  };
+
+  let upstream: Response;
+  try {
+    upstream = await attempt(false);
+    if (upstream.status === 401 && conn.authKind === "oauth") {
+      upstream = await attempt(true);
+    }
+  } catch (err) {
+    if (err instanceof LeftOwnCredentialsError) return deny(res, 503, "credentials unavailable");
+    audit({ taskId, slug, method: req.method, error: String(err) });
+    return deny(res, 502, "upstream unreachable");
+  }
+
+  const summary = body ? rpcSummary(body) : {};
+  audit({
+    taskId,
+    slug,
+    method: req.method,
+    rpc: summary.method,
+    tool: summary.tool,
+    status: upstream.status,
+  });
+
+  const resHeaders: Record<string, string> = {};
+  for (const name of FORWARD_RES_HEADERS) {
+    const v = upstream.headers.get(name);
+    if (v) resHeaders[name] = v;
+  }
+  res.writeHead(upstream.status, resHeaders);
+  if (upstream.body) {
+    // pipeline (NOT .pipe) so a mid-stream error — client gone, upstream
+    // reset, abort — tears both ends down instead of crashing the process
+    // as an unhandled Readable 'error'.
+    pipeline(
+      Readable.fromWeb(upstream.body as Parameters<typeof Readable.fromWeb>[0]),
+      res,
+      (err) => {
+        if (err && err.name !== "AbortError") {
+          audit({ taskId, slug, stream: "ended", error: err.name });
+        }
+      },
+    );
+  } else {
+    res.end();
+  }
+}
+
+/** ADR-154 §13: a runner past its credentials floor serves MCP only from
+ *  leases; a task without one is answered 503, never from the local store. */
+let leaseOnly = false;
+
+export function setMcpGatewayLeaseOnly(on: boolean): void {
+  leaseOnly = on;
+}
+
+/** Tests only: the SSRF rule's injectable resolver and trust roots. */
+let leasedSafeHttpDeps: SafeHttpDeps = {};
+export function setLeasedMcpSafeHttpDepsForTests(deps: SafeHttpDeps): void {
+  leasedSafeHttpDeps = deps;
+}
+
+const LEASED_METHODS = new Set(["GET", "POST", "DELETE"]);
+
+/**
+ * One request for a leased connection: attach its header, send it under the
+ * SSRF rule, and stream the answer back. The request is held on its task: the
+ * gate closing, a cleanup, or the task hanging up ends it wherever it is,
+ * connecting, waiting for headers or streaming. An OAuth token past its
+ * expiry is refreshed first and never sent; a 401 is retried once, only with
+ * a newer token for the very connection the request began with.
+ */
+async function serveLeasedConnection(
+  req: IncomingMessage,
+  res: ServerResponse,
+  taskId: string,
+  hold: McpRequestHold,
+): Promise<void> {
+  const slug = hold.connection.slug;
+  // From the start: a hang-up ends the request before headers too.
+  const client = new AbortController();
+  res.once("close", () => {
+    client.abort();
+    hold.end();
+  });
+  const signal = AbortSignal.any([hold.signal, client.signal]);
+  const method = req.method ?? "GET";
+  if (!LEASED_METHODS.has(method)) return deny(res, 405, "method not allowed");
+  let body: Buffer | null = null;
+  if (method === "POST") {
+    try {
+      body = await readBody(req, signal);
+    } catch {
+      // Ended before its body arrived: the gate closed, or the task went.
+      if (!res.destroyed && !res.headersSent) deny(res, 503, "credentials unavailable");
+      return;
+    }
+    if (body === null) return deny(res, 413, "request body too large");
+  }
+  const forwarded: Record<string, string> = {};
+  for (const name of FORWARD_REQ_HEADERS) {
+    const v = req.headers[name];
+    if (typeof v === "string") forwarded[name] = v;
+  }
+
+  let connection = hold.current();
+  if (!connection) return deny(res, 503, "credentials unavailable");
+  if (connection.authKind === "oauth" && connection.expiresAt !== null && connection.expiresAt <= Date.now()) {
+    connection = await hold.refresh(connection);
+    if (!connection) return deny(res, 503, "credentials unavailable");
+  }
+
+  const attempt = (current: LeasedMcpConnection): Promise<SafeHttpResponse> =>
+    safeRequest(
+      {
+        url: current.url,
+        method: method as "GET" | "POST" | "DELETE",
+        headers: current.header ? { ...forwarded, [current.header.name]: current.header.value } : forwarded,
+        ...(body ? { body } : {}),
+        signal,
+      },
+      undefined,
+      leasedSafeHttpDeps,
+    );
+
+  let upstream: SafeHttpResponse;
+  try {
+    upstream = await attempt(connection);
+    if (upstream.status === 401 && connection.authKind === "oauth") {
+      upstream.body.destroy();
+      const refreshed = await hold.refresh(connection);
+      if (!refreshed) return deny(res, 401, `connection "${slug}" needs a new sign-in`);
+      connection = refreshed;
+      upstream = await attempt(connection);
+    }
+  } catch (err) {
+    if (signal.aborted) return deny(res, 503, "credentials unavailable");
+    audit({ taskId, slug, method, error: err instanceof Error ? err.message : String(err) });
+    return deny(res, 502, "upstream unreachable");
+  }
+
+  const summary = body ? rpcSummary(body) : {};
+  audit({ taskId, slug, method, rpc: summary.method, tool: summary.tool, status: upstream.status });
+  const resHeaders: Record<string, string> = {};
+  for (const name of FORWARD_RES_HEADERS) {
+    const v = upstream.headers[name];
+    if (typeof v === "string") resHeaders[name] = v;
+  }
+  res.writeHead(upstream.status, resHeaders);
+  // A stream ends with its task's gate or its client: the signal destroys the
+  // upstream body, and the pipeline tears down both ends.
+  pipeline(upstream.body, res, (err) => {
+    if (err && err.name !== "AbortError" && !signal.aborted) {
+      audit({ taskId, slug, stream: "ended", error: err.name });
+    }
+  });
+}
+
+async function handleGatewayRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  authenticatedSockets: WeakMap<Socket, TaskForwarderIdentity>,
+  claimTaskQuota: (socket: Socket, taskId: string) => boolean,
+): Promise<void> {
+  const pathname = (() => {
+    try {
+      return new URL(req.url ?? "", "http://uai.invalid").pathname;
+    } catch {
+      return "";
+    }
+  })();
+  if (pathname === "/env" && req.url === "/env") {
+    const socket = req.socket;
+    let identity = authenticatedSockets.get(socket) ?? null;
+    if (identity === null) {
+      const fixedTaskId = sidecarTaskId();
+      if (fixedTaskId !== null && loopbackPeer(socket)) {
+        identity = currentTaskGatewayRegistration(fixedTaskId);
+      }
+    }
+    await handleEnvRequest(req, res, identity);
+    return;
+  }
+  await handleMcpRequest(req, res, claimTaskQuota);
+}
+
+type GatewayTransportServer = NetServer & {
+  closeAllConnections?: () => void;
+};
+
+function readSocketBytes(
+  socket: Socket,
+  length: number,
+  deadline: number,
+): Promise<Buffer> {
+  return new Promise((resolveRead, rejectRead) => {
+    let settled = false;
+    const finish = (error: Error | null, bytes?: Buffer): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.off("readable", onReadable);
+      socket.off("error", onError);
+      socket.off("end", onEnd);
+      socket.off("close", onClose);
+      if (error) rejectRead(error);
+      else if (bytes) resolveRead(bytes);
+      else rejectRead(new Error("task gateway stream ended"));
+    };
+    const tryRead = (): void => {
+      const bytes = socket.read(length) as Buffer | null;
+      if (bytes === null) return;
+      if (bytes.length !== length) {
+        finish(new Error("truncated task gateway frame"));
+        return;
+      }
+      finish(null, bytes);
+    };
+    const onReadable = (): void => tryRead();
+    const onError = (): void => finish(new Error("task gateway socket error"));
+    const onEnd = (): void => {
+      tryRead();
+      if (!settled) finish(new Error("truncated task gateway frame"));
+    };
+    const onClose = (): void => finish(new Error("task gateway socket closed"));
+    const remainingMs = Math.max(1, deadline - Date.now());
+    const timer = setTimeout(
+      () => finish(new Error("task gateway pre-auth timed out")),
+      remainingMs,
+    );
+    timer.unref();
+    socket.on("readable", onReadable);
+    socket.once("error", onError);
+    socket.once("end", onEnd);
+    socket.once("close", onClose);
+    tryRead();
+  });
+}
+
+interface TaskGatewayDemuxOptions {
+  readonly httpServer: HttpServer;
+  readonly authenticatedSockets: WeakMap<Socket, TaskForwarderIdentity>;
+  readonly authenticatedConnections: Map<Socket, TaskForwarderIdentity>;
+  readonly preauthTimeoutMs: number;
+  readonly maxPendingPreauth: number;
+  readonly maxPendingPreauthPerPeer: number;
+  readonly maxPendingPreauthPerTask: number;
+  readonly maxActiveConnections: number;
+  readonly maxDirectStagingConnectionsPerPeer: number;
+  readonly maxActiveConnectionsPerTask: number;
+  readonly nonce: () => Buffer;
+  readonly tlsHandler: () => TaskGatewayTlsHandler | null;
+}
+
+interface AuthenticatedTaskForwarder {
+  readonly identity: TaskForwarderIdentity;
+  /** Release the task-scoped pre-auth reservation exactly once. */
+  readonly release: () => void;
+}
+
+function createTaskGatewayDemux(options: TaskGatewayDemuxOptions): {
+  accept: (socket: Socket) => void;
+  claimTaskQuota: (socket: Socket, taskId: string) => boolean;
+} {
+  let pendingPreauth = 0;
+  const pendingPeerBySocket = new Map<Socket, string>();
+  const pendingSocketsByPeer = new Map<string, Set<Socket>>();
+  const pendingByTask = new Map<string, number>();
+  let activeConnections = 0;
+  const activeScopeBySocket = new Map<
+    Socket,
+    { kind: "peer" | "task"; key: string }
+  >();
+  const activeSocketsByPeer = new Map<string, Set<Socket>>();
+  const activeSocketsByTask = new Map<string, Set<Socket>>();
+  const activeUnauthenticatedSockets = new Set<Socket>();
+
+  const peerKey = (socket: Socket): string => {
+    if (loopbackPeer(socket)) return "loopback";
+    const address = (socket.remoteAddress ?? "unknown").toLowerCase();
+    return address.startsWith("::ffff:") ? address.slice(7) : address;
+  };
+
+  const releasePreauth = (socket: Socket): void => {
+    const peer = pendingPeerBySocket.get(socket);
+    if (peer === undefined) return;
+    pendingPeerBySocket.delete(socket);
+    pendingPreauth -= 1;
+    const peerSockets = pendingSocketsByPeer.get(peer);
+    peerSockets?.delete(socket);
+    if (peerSockets?.size === 0) pendingSocketsByPeer.delete(peer);
+  };
+
+  const reservePreauth = (socket: Socket, peer: string): void => {
+    pendingPreauth += 1;
+    pendingPeerBySocket.set(socket, peer);
+    const peerSockets = pendingSocketsByPeer.get(peer) ?? new Set<Socket>();
+    peerSockets.add(socket);
+    pendingSocketsByPeer.set(peer, peerSockets);
+  };
+
+  const releaseActive = (socket: Socket): void => {
+    const scope = activeScopeBySocket.get(socket);
+    if (scope === undefined) return;
+    activeScopeBySocket.delete(socket);
+    activeConnections -= 1;
+    const scopedSockets =
+      scope.kind === "task"
+        ? activeSocketsByTask.get(scope.key)
+        : activeSocketsByPeer.get(scope.key);
+    scopedSockets?.delete(socket);
+    if (scope.kind === "peer") activeUnauthenticatedSockets.delete(socket);
+    if (scopedSockets?.size === 0) {
+      if (scope.kind === "task") activeSocketsByTask.delete(scope.key);
+      else activeSocketsByPeer.delete(scope.key);
+    }
+  };
+
+  const evictUnauthenticated = (socket: Socket): void => {
+    // Release synchronously: Socket's close event is asynchronous and the
+    // replacement must be able to reserve the slot in this turn.
+    releaseActive(socket);
+    socket.destroy();
+  };
+
+  /** Transfer one fully-demultiplexed socket into a close-scoped quota.
+   * Forwarder-authenticated traffic and fixed-sidecar traffic are charged to
+   * their proved task. Direct HTTP starts in an evictable peer staging pool;
+   * a valid MCP token moves it to the non-evictable task pool below. */
+  const reserveActive = (
+    socket: Socket,
+    scope: { kind: "peer" | "task"; key: string },
+  ): boolean => {
+    if (activeScopeBySocket.has(socket)) return true;
+    const scopedSockets =
+      scope.kind === "task"
+        ? activeSocketsByTask.get(scope.key)
+        : activeSocketsByPeer.get(scope.key);
+    const scopedLimit =
+      scope.kind === "task"
+        ? options.maxActiveConnectionsPerTask
+        : options.maxDirectStagingConnectionsPerPeer;
+    if ((scopedSockets?.size ?? 0) >= scopedLimit) {
+      if (scope.kind === "task") return false;
+      const oldest = scopedSockets?.values().next().value as Socket | undefined;
+      if (oldest) evictUnauthenticated(oldest);
+    }
+    if (activeConnections >= options.maxActiveConnections) {
+      // Never evict a proved task socket: it may be a long-lived MCP SSE stream
+      // or secrets-proxy tunnel. Unproved direct traffic is replaceable, which
+      // keeps a handful of peers from filling the global pool permanently.
+      const oldest = activeUnauthenticatedSockets.values().next().value as
+        | Socket
+        | undefined;
+      if (!oldest) return false;
+      evictUnauthenticated(oldest);
+    }
+    const currentScopedSockets =
+      scope.kind === "task"
+        ? activeSocketsByTask.get(scope.key)
+        : activeSocketsByPeer.get(scope.key);
+    const nextScopedSockets = currentScopedSockets ?? new Set<Socket>();
+    nextScopedSockets.add(socket);
+    if (scope.kind === "task") {
+      activeSocketsByTask.set(scope.key, nextScopedSockets);
+    } else {
+      activeSocketsByPeer.set(scope.key, nextScopedSockets);
+      activeUnauthenticatedSockets.add(socket);
+    }
+    activeScopeBySocket.set(socket, scope);
+    activeConnections += 1;
+    socket.once("close", () => releaseActive(socket));
+    return true;
+  };
+
+  const claimTaskQuota = (socket: Socket, taskId: string): boolean => {
+    const current = activeScopeBySocket.get(socket);
+    if (current === undefined) return false;
+    if (current.kind === "task") return current.key === taskId;
+
+    const taskSockets = activeSocketsByTask.get(taskId);
+    if (
+      (taskSockets?.size ?? 0) >= options.maxActiveConnectionsPerTask
+    ) {
+      return false;
+    }
+
+    const peerSockets = activeSocketsByPeer.get(current.key);
+    peerSockets?.delete(socket);
+    if (peerSockets?.size === 0) activeSocketsByPeer.delete(current.key);
+    activeUnauthenticatedSockets.delete(socket);
+
+    const nextTaskSockets = taskSockets ?? new Set<Socket>();
+    nextTaskSockets.add(socket);
+    activeSocketsByTask.set(taskId, nextTaskSockets);
+    activeScopeBySocket.set(socket, { kind: "task", key: taskId });
+    return true;
+  };
+
+  const rememberAuthenticated = (
+    socket: Socket,
+    identity: TaskForwarderIdentity,
+  ): void => {
+    if (options.authenticatedConnections.has(socket)) return;
+    options.authenticatedSockets.set(socket, identity);
+    options.authenticatedConnections.set(socket, identity);
+    socket.once("close", () => {
+      options.authenticatedConnections.delete(socket);
+    });
+  };
+
+  const dispatchHttp = (
+    socket: Socket,
+    firstByte: Buffer,
+    identity: TaskForwarderIdentity | null,
+    activeScope: { kind: "peer" | "task"; key: string },
+  ): void => {
+    if (!reserveActive(socket, activeScope)) {
+      socket.destroy();
+      return;
+    }
+    if (identity) rememberAuthenticated(socket, identity);
+    socket.unshift(firstByte);
+    options.httpServer.emit("connection", socket);
+  };
+
+  const dispatchTls = (
+    socket: Socket,
+    firstByte: Buffer,
+    identity: TaskForwarderIdentity,
+  ): void => {
+    const handler = options.tlsHandler();
+    if (
+      !handler ||
+      !isTaskGatewayGenerationCurrent(identity) ||
+      !reserveActive(socket, { kind: "task", key: identity.taskId })
+    ) {
+      socket.destroy();
+      return;
+    }
+    rememberAuthenticated(socket, identity);
+    socket.unshift(firstByte);
+    try {
+      handler({
+        ...identity,
+        socket,
+        isCurrent: () => isTaskGatewayGenerationCurrent(identity),
+      });
+    } catch {
+      socket.destroy();
+    }
+  };
+
+  const authenticate = async (
+    socket: Socket,
+    firstByte: Buffer,
+    deadline: number,
+  ): Promise<AuthenticatedTaskForwarder | null> => {
+    const headerTail = await readSocketBytes(
+      socket,
+      TASK_FORWARDER_PREAMBLE_HEADER_BYTES - 1,
+      deadline,
+    );
+    const header = Buffer.concat([firstByte, headerTail]);
+    const preambleLength = taskForwarderPreambleLength(header);
+    if (
+      preambleLength === null ||
+      preambleLength > TASK_FORWARDER_MAX_PREAMBLE_BYTES
+    ) {
+      return null;
+    }
+    const payload = await readSocketBytes(
+      socket,
+      preambleLength - header.length,
+      deadline,
+    );
+    const identity = decodeTaskForwarderPreamble(
+      Buffer.concat([header, payload], preambleLength),
+    );
+    if (identity === null || !isSafeHostTaskId(identity.taskId)) return null;
+
+    const nonce = options.nonce();
+    socket.write(encodeTaskForwarderChallenge(nonce));
+    const response = await readSocketBytes(
+      socket,
+      TASK_FORWARDER_RESPONSE_BYTES,
+      deadline,
+    );
+    const mac = decodeTaskForwarderResponse(response);
+    if (
+      mac === null ||
+      !verifyTaskGatewayAuthentication(identity, nonce, mac)
+    ) {
+      return null;
+    }
+
+    // A claimed task id is untrusted until its MAC verifies. Charging its
+    // reservation earlier lets a peer lock out a real task with only the
+    // public task id.
+    const taskPending = pendingByTask.get(identity.taskId) ?? 0;
+    if (taskPending >= options.maxPendingPreauthPerTask) return null;
+    pendingByTask.set(identity.taskId, taskPending + 1);
+    let released = false;
+    const release = (): void => {
+      if (released) return;
+      released = true;
+      const next = (pendingByTask.get(identity.taskId) ?? 1) - 1;
+      if (next > 0) pendingByTask.set(identity.taskId, next);
+      else pendingByTask.delete(identity.taskId);
+    };
+    if (!reserveActive(socket, { kind: "task", key: identity.taskId })) {
+      release();
+      return null;
+    }
+    let retained = false;
+    try {
+      socket.write(TASK_FORWARDER_ACCEPT_MAGIC);
+      retained = true;
+      return { identity, release };
+    } finally {
+      // A synchronous write failure must not permanently consume this task's
+      // post-MAC quotas. Once returned, the caller owns the pending release;
+      // the active reservation remains close-scoped.
+      if (!retained) {
+        release();
+        releaseActive(socket);
+      }
+    }
+  };
+
+  return {
+    claimTaskQuota,
+    accept: (socket) => {
+      socket.pause();
+      socket.setNoDelay(true);
+      const peer = peerKey(socket);
+      const peerSockets = pendingSocketsByPeer.get(peer);
+      if (
+        peerSockets &&
+        peerSockets.size >= options.maxPendingPreauthPerPeer
+      ) {
+        // Prefer the newest connection instead of letting a peer reserve its
+        // own entire quota with idle sockets. A real hook/forwarder sends its
+        // first frame immediately, so replacing the oldest pending socket
+        // preserves progress even when several task runtimes share one NATed
+        // source address (notably desktop container VMs).
+        const oldest = peerSockets.values().next().value as Socket | undefined;
+        if (oldest) {
+          releasePreauth(oldest);
+          oldest.destroy();
+        }
+      }
+      if (pendingPreauth >= options.maxPendingPreauth) {
+        // Pending sockets carry no authority and have a short deadline. Drop
+        // the oldest globally so several peers cannot permanently consume all
+        // admission slots before a real forwarder gets a turn.
+        const oldest = pendingPeerBySocket.keys().next().value as
+          | Socket
+          | undefined;
+        if (oldest) {
+          releasePreauth(oldest);
+          oldest.destroy();
+        }
+      }
+      reservePreauth(socket, peer);
+      const deadline = Date.now() + options.preauthTimeoutMs;
+      void (async () => {
+        try {
+          const firstByte = await readSocketBytes(socket, 1, deadline);
+          if (firstByte[0] === 0x00) {
+            const authenticated = await authenticate(socket, firstByte, deadline);
+            if (authenticated === null) {
+              socket.destroy();
+              return;
+            }
+            const { identity } = authenticated;
+            try {
+              rememberAuthenticated(socket, identity);
+              if (!isTaskGatewayGenerationCurrent(identity)) {
+                socket.destroy();
+                return;
+              }
+              // The forwarder does not relay task bytes until it receives the
+              // accept frame, so this byte cannot be unauthenticated pipelining.
+              const applicationByte = await readSocketBytes(socket, 1, deadline);
+              if (applicationByte[0] === 0x16) {
+                dispatchTls(socket, applicationByte, identity);
+              } else {
+                dispatchHttp(socket, applicationByte, identity, {
+                  kind: "task",
+                  key: identity.taskId,
+                });
+              }
+            } finally {
+              authenticated.release();
+            }
+            return;
+          }
+
+          const fixedTaskId = sidecarTaskId();
+          const sidecarIdentity =
+            fixedTaskId !== null && loopbackPeer(socket)
+              ? currentTaskGatewayRegistration(fixedTaskId)
+              : null;
+          if (firstByte[0] === 0x16) {
+            // Direct TLS is valid only for the fixed one-task sidecar. Docker
+            // and Apple must prove identity through the forwarder first.
+            if (sidecarIdentity) dispatchTls(socket, firstByte, sidecarIdentity);
+            else socket.destroy();
+          } else {
+            dispatchHttp(
+              socket,
+              firstByte,
+              sidecarIdentity,
+              sidecarIdentity
+                ? { kind: "task", key: sidecarIdentity.taskId }
+                : { kind: "peer", key: peer },
+            );
+          }
+        } catch {
+          socket.destroy();
+        } finally {
+          releasePreauth(socket);
+        }
+      })();
+    },
+  };
+}
+
+export interface McpGatewayController {
+  /** Current bounded capability snapshot. Never contains a raw listener error. */
+  state(): McpGatewayCapability;
+  /** Resolve only after this listener has positively bound its configured port. */
+  waitUntilReady(timeoutMs?: number): Promise<void>;
+  /** Subscribe to semantic state changes. The current snapshot is read via state(). */
+  subscribe(
+    listener: (state: McpGatewayCapability) => void,
+  ): () => void;
+  /** Permanently stop this controller and release its listener/timer. */
+  stop(): Promise<void>;
+}
+
+export interface McpGatewayListener extends McpGatewayController {
+  /** Start once; repeated calls before stop are idempotent. */
+  start(): McpGatewayController;
+}
+
+export interface McpGatewayListenerOptions {
+  port?: number;
+  bind?: string;
+  retryInitialDelayMs?: number;
+  retryMaxDelayMs?: number;
+  serverFactory?: (
+    connectionListener: (socket: Socket) => void,
+  ) => GatewayTransportServer;
+  httpServerFactory?: (
+    requestListener: (req: IncomingMessage, res: ServerResponse) => void,
+  ) => HttpServer;
+  tlsHandler?: TaskGatewayTlsHandler;
+  preauthTimeoutMs?: number;
+  maxPendingPreauth?: number;
+  maxPendingPreauthPerPeer?: number;
+  maxPendingPreauthPerTask?: number;
+  maxActiveConnections?: number;
+  maxDirectStagingConnectionsPerPeer?: number;
+  maxActiveConnectionsPerTask?: number;
+  nonce?: () => Buffer;
+  setRetryTimeout?: (
+    callback: () => void,
+    delayMs: number,
+  ) => NodeJS.Timeout;
+  clearRetryTimeout?: (timer: NodeJS.Timeout) => void;
+  random?: () => number;
+  logger?: Pick<Console, "log" | "warn">;
+}
+
+function listenerFailureReason(
+  error: unknown,
+): "port_in_use" | "bind_failed" {
+  return (error as NodeJS.ErrnoException | null)?.code === "EADDRINUSE"
+    ? "port_in_use"
+    : "bind_failed";
+}
+
+function positiveInteger(value: number | undefined, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 1
+    ? Math.floor(value)
+    : fallback;
+}
+
+function sameGatewayState(
+  left: McpGatewayCapability,
+  right: McpGatewayCapability,
+): boolean {
+  return (
+    left.status === right.status &&
+    left.port === right.port &&
+    (left.status !== "down" ||
+      (right.status === "down" && left.reason === right.reason))
+  );
+}
+
+/**
+ * Construct one restart-safe MCP gateway listener. Exported so listener
+ * lifecycle tests can use deterministic fake servers without opening a real
+ * host port; production uses the singleton wrapper below.
+ */
+export function createMcpGatewayListener(
+  options: McpGatewayListenerOptions = {},
+): McpGatewayListener {
+  const port =
+    Number.isSafeInteger(options.port) &&
+    (options.port ?? 0) >= 1 &&
+    (options.port ?? 0) <= 65_535
+      ? (options.port as number)
+      : MCP_GATEWAY_PORT;
+  const bind = options.bind ?? gatewayBindAddress();
+  const retryInitialDelayMs = positiveInteger(
+    options.retryInitialDelayMs,
+    GATEWAY_RETRY_INITIAL_DELAY_MS,
+  );
+  const retryMaxDelayMs = Math.max(
+    retryInitialDelayMs,
+    positiveInteger(
+      options.retryMaxDelayMs,
+      GATEWAY_RETRY_MAX_DELAY_MS,
+    ),
+  );
+  const serverFactory =
+    options.serverFactory ??
+    ((connectionListener: (socket: Socket) => void) =>
+      createNetServer({ pauseOnConnect: true }, connectionListener));
+  const httpServerFactory = options.httpServerFactory ?? createHttpServer;
+  const preauthTimeoutMs = positiveInteger(
+    options.preauthTimeoutMs,
+    TASK_GATEWAY_PREAUTH_TIMEOUT_MS,
+  );
+  const maxPendingPreauth = positiveInteger(
+    options.maxPendingPreauth,
+    TASK_GATEWAY_MAX_PENDING_PREAUTH,
+  );
+  const maxPendingPreauthPerPeer = positiveInteger(
+    options.maxPendingPreauthPerPeer,
+    TASK_GATEWAY_MAX_PENDING_PREAUTH_PER_PEER,
+  );
+  const maxPendingPreauthPerTask = positiveInteger(
+    options.maxPendingPreauthPerTask,
+    TASK_GATEWAY_MAX_PENDING_PREAUTH_PER_TASK,
+  );
+  const maxActiveConnections = positiveInteger(
+    options.maxActiveConnections,
+    TASK_GATEWAY_MAX_ACTIVE_CONNECTIONS,
+  );
+  const maxDirectStagingConnectionsPerPeer = positiveInteger(
+    options.maxDirectStagingConnectionsPerPeer,
+    TASK_GATEWAY_MAX_DIRECT_STAGING_CONNECTIONS_PER_PEER,
+  );
+  const maxActiveConnectionsPerTask = positiveInteger(
+    options.maxActiveConnectionsPerTask,
+    TASK_GATEWAY_MAX_ACTIVE_CONNECTIONS_PER_TASK,
+  );
+  const nonce = options.nonce ?? (() => randomBytes(32));
+  const setRetryTimeout =
+    options.setRetryTimeout ??
+    ((callback: () => void, delayMs: number) =>
+      setTimeout(callback, delayMs));
+  const clearRetryTimeout = options.clearRetryTimeout ?? clearTimeout;
+  const random = options.random ?? Math.random;
+  const logger = options.logger ?? console;
+  const subscribers = new Set<
+    (state: McpGatewayCapability) => void
+  >();
+  const authenticatedSockets = new WeakMap<Socket, TaskForwarderIdentity>();
+  const authenticatedConnections = new Map<Socket, TaskForwarderIdentity>();
+  let claimTaskQuota = (_socket: Socket, _taskId: string): boolean => false;
+  const httpServer = httpServerFactory((req, res) => {
+    void handleGatewayRequest(
+      req,
+      res,
+      authenticatedSockets,
+      claimTaskQuota,
+    ).catch(() => deny(res, 500, "gateway error"));
+  });
+  httpServer.on("clientError", (_error, socket) => socket.destroy());
+  // This HTTP server never owns the TCP listener: authenticated sockets are
+  // demultiplexed into it. Node starts its headers/request timeout checker on
+  // the `listening` event, so emit that lifecycle event for this hidden
+  // server too or a peer can drip one byte forever after pre-authentication.
+  httpServer.emit("listening");
+  const demux = createTaskGatewayDemux({
+    httpServer,
+    authenticatedSockets,
+    authenticatedConnections,
+    preauthTimeoutMs,
+    maxPendingPreauth,
+    maxPendingPreauthPerPeer,
+    maxPendingPreauthPerTask,
+    maxActiveConnections,
+    maxDirectStagingConnectionsPerPeer,
+    maxActiveConnectionsPerTask,
+    nonce,
+    tlsHandler: () => options.tlsHandler ?? taskGatewayTlsHandler,
+  });
+  claimTaskQuota = demux.claimTaskQuota;
+  const socketsByServer = new Map<GatewayTransportServer, Set<Socket>>();
+  const unsubscribeRevocations = subscribeTaskGatewayRevocations((revoked) => {
+    for (const [socket, identity] of authenticatedConnections) {
+      if (
+        identity.taskId === revoked.taskId &&
+        identity.generation === revoked.generation
+      ) {
+        socket.destroy();
+      }
+    }
+  });
+
+  let capability: McpGatewayCapability = Object.freeze({
+    status: "starting",
+    port,
+  });
+  let server: GatewayTransportServer | null = null;
+  let retryTimer: NodeJS.Timeout | null = null;
+  let consecutiveFailures = 0;
+  let started = false;
+  let stopped = false;
+  let stopPromise: Promise<void> | null = null;
+
+  const setState = (next: McpGatewayCapability): void => {
+    const frozen = Object.freeze(next);
+    if (sameGatewayState(capability, frozen)) return;
+    capability = frozen;
+    for (const subscriber of subscribers) {
+      try {
+        subscriber(capability);
+      } catch {
+        // Capability observers must never take down the host listener.
+      }
+    }
+  };
+
+  const closeServer = (target: GatewayTransportServer): void => {
+    const sockets = socketsByServer.get(target);
+    socketsByServer.delete(target);
+    if (sockets) {
+      for (const socket of sockets) socket.destroy();
+      sockets.clear();
+    }
+    try {
+      target.close(() => undefined);
+      target.closeAllConnections?.();
+    } catch {
+      // A listener that failed before binding has nothing left to close.
+    }
+  };
+
+  const retryDelay = (): number => {
+    const exponent = Math.min(Math.max(consecutiveFailures - 1, 0), 30);
+    const baseDelayMs = Math.min(
+      retryMaxDelayMs,
+      retryInitialDelayMs * 2 ** exponent,
+    );
+    const sample = random();
+    const boundedSample = Number.isFinite(sample)
+      ? Math.min(1, Math.max(0, sample))
+      : 0.5;
+    return Math.min(
+      retryMaxDelayMs,
+      Math.max(
+        1,
+        Math.round(
+          baseDelayMs *
+            (GATEWAY_RETRY_MIN_JITTER +
+              GATEWAY_RETRY_JITTER_SPAN * boundedSample),
+        ),
+      ),
+    );
+  };
+
+  let beginAttempt: () => void;
+
+  const scheduleRetry = (
+    reason: "port_in_use" | "bind_failed",
+  ): void => {
+    if (stopped || retryTimer !== null) return;
+    consecutiveFailures += 1;
+    setState({ status: "down", port, reason });
+    const delayMs = retryDelay();
+    logger.warn(
+      `[mcp-gateway] listener down (${reason}); retrying in ${delayMs}ms`,
+    );
+    retryTimer = setRetryTimeout(() => {
+      retryTimer = null;
+      beginAttempt();
+    }, delayMs);
+    retryTimer.unref();
+  };
+
+  const listenerFailed = (
+    target: GatewayTransportServer,
+    error: unknown,
+  ): void => {
+    if (stopped || server !== target) return;
+    server = null;
+    closeServer(target);
+    scheduleRetry(listenerFailureReason(error));
+  };
+
+  beginAttempt = (): void => {
+    if (stopped || server !== null || retryTimer !== null) return;
+
+    let nextServer: GatewayTransportServer;
+    const attemptSockets = new Set<Socket>();
+    try {
+      nextServer = serverFactory((socket) => {
+        attemptSockets.add(socket);
+        socket.once("close", () => attemptSockets.delete(socket));
+        demux.accept(socket);
+      });
+    } catch {
+      scheduleRetry("bind_failed");
+      return;
+    }
+    socketsByServer.set(nextServer, attemptSockets);
+    server = nextServer;
+
+    nextServer.on("error", (error) => {
+      listenerFailed(nextServer, error);
+    });
+    nextServer.on("listening", () => {
+      if (stopped || server !== nextServer) {
+        closeServer(nextServer);
+        return;
+      }
+      consecutiveFailures = 0;
+      setState({ status: "ready", port });
+      logger.log(`[mcp-gateway] listening on ${bind}:${port}`);
+    });
+    nextServer.on("close", () => {
+      socketsByServer.delete(nextServer);
+      if (stopped || server !== nextServer) return;
+      server = null;
+      scheduleRetry("bind_failed");
+    });
+
+    try {
+      nextServer.listen(port, bind);
+    } catch (error) {
+      listenerFailed(nextServer, error);
+    }
+  };
+
+  const controller: McpGatewayListener = {
+    state: () => capability,
+    waitUntilReady: (timeoutMs = 5_000) => {
+      if (capability.status === "ready") return Promise.resolve();
+      if (capability.status === "down") {
+        return Promise.reject(
+          new Error(`MCP gateway listener is down (${capability.reason})`),
+        );
+      }
+      if (stopped) {
+        return Promise.reject(new Error("MCP gateway listener is stopped"));
+      }
+      const boundedTimeoutMs =
+        Number.isFinite(timeoutMs) && timeoutMs >= 1
+          ? Math.floor(timeoutMs)
+          : 5_000;
+      return new Promise<void>((resolveReady, rejectReady) => {
+        let settled = false;
+        let unsubscribe = (): void => undefined;
+        const finish = (error?: Error): void => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          unsubscribe();
+          if (error) rejectReady(error);
+          else resolveReady();
+        };
+        const timer = setTimeout(
+          () =>
+            finish(
+              new Error(
+                `MCP gateway listener did not become ready within ${boundedTimeoutMs}ms`,
+              ),
+            ),
+          boundedTimeoutMs,
+        );
+        timer.unref();
+        const observe = (state: McpGatewayCapability): void => {
+          if (state.status === "ready") finish();
+          else if (state.status === "down") {
+            finish(new Error(`MCP gateway listener is down (${state.reason})`));
+          }
+        };
+        unsubscribe = controller.subscribe(observe);
+        // Close the state-change race between the initial check and subscribe.
+        observe(capability);
+      });
+    },
+    subscribe: (listener) => {
+      subscribers.add(listener);
+      return () => subscribers.delete(listener);
+    },
+    start: () => {
+      if (stopped) {
+        throw new Error("MCP gateway listener cannot restart after stop");
+      }
+      if (!started) {
+        started = true;
+        beginAttempt();
+      }
+      return controller;
+    },
+    stop: () => {
+      if (stopPromise) return stopPromise;
+      stopped = true;
+      if (retryTimer !== null) {
+        clearRetryTimeout(retryTimer);
+        retryTimer = null;
+      }
+      const activeServer = server;
+      server = null;
+      stopPromise = new Promise<void>((resolveStop) => {
+        if (activeServer === null) {
+          resolveStop();
+          return;
+        }
+        let resolved = false;
+        const finish = (): void => {
+          if (resolved) return;
+          resolved = true;
+          resolveStop();
+        };
+        activeServer.once("close", finish);
+        try {
+          const sockets = socketsByServer.get(activeServer);
+          socketsByServer.delete(activeServer);
+          if (sockets) {
+            for (const socket of sockets) socket.destroy();
+          }
+          activeServer.close(finish);
+          activeServer.closeAllConnections?.();
+          if (!activeServer.listening) queueMicrotask(finish);
+        } catch {
+          finish();
+        }
+      }).finally(() => {
+        unsubscribeRevocations();
+        for (const socket of authenticatedConnections.keys()) socket.destroy();
+        authenticatedConnections.clear();
+        httpServer.closeAllConnections();
+        // Clears the hidden server's timeout-check interval. It has no own
+        // listening handle, so close is otherwise a no-op.
+        httpServer.close();
+        subscribers.clear();
+      });
+      return stopPromise;
+    },
+  };
+  return controller;
+}
+
+let gatewayController: McpGatewayListener | null = null;
+
+/** Start (or return) the process-wide gateway listener. */
+export function startMcpGateway(): McpGatewayController {
+  gatewayController ??= createMcpGatewayListener();
+  return gatewayController.start();
+}
+
+/** Task admission gate: no runtime starts until the shared listener is bound. */
+export function waitForMcpGatewayReady(timeoutMs = 5_000): Promise<void> {
+  return startMcpGateway().waitUntilReady(timeoutMs);
+}
+
+/** Stop and reset the process-wide listener (also the deterministic test seam). */
+export async function stopMcpGateway(): Promise<void> {
+  const active = gatewayController;
+  if (active === null) return;
+  await active.stop();
+  if (gatewayController === active) gatewayController = null;
+}
+
+// --- task container wiring (ADR-057 task-up writers) -------------------------
+
+/** Reconcile JSON MCP definitions atomically and with compare-before-rename.
+ * Only exact Uai gateway shapes whose URL names this task are owned: stale
+ * ones are removed, while browser and foreign/user entries are untouched. */
+export const MERGE_MCP_JSON = `
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const p = process.argv[1];
+const key = process.argv[3] || "mcpServers";
+const flavor = process.argv[4] || "claude";
+const taskId = process.argv[5];
+const plainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+if (!["claude", "cursor", "opencode"].includes(flavor)) {
+  throw new Error("invalid MCP config flavor");
+}
+if (typeof taskId !== "string" || taskId.length === 0) {
+  throw new Error("invalid MCP task id");
+}
+const desired = JSON.parse(process.argv[2]);
+if (!plainObject(desired)) {
+  throw new Error("desired MCP definitions must be an object");
+}
+const exactKeys = (value, keys) => plainObject(value) &&
+  Object.keys(value).sort().join("\\0") === keys.slice().sort().join("\\0");
+const gatewayPort = ${JSON.stringify(String(MCP_GATEWAY_PORT))};
+const managedUrl = (value) => {
+  if (flavor === "claude" && exactKeys(value, ["type", "url"]) &&
+      value.type === "http" && typeof value.url === "string") return value.url;
+  if (flavor === "cursor" && exactKeys(value, ["url"]) &&
+      typeof value.url === "string") return value.url;
+  if (flavor === "opencode" &&
+      exactKeys(value, ["enabled", "oauth", "type", "url"]) &&
+      value.type === "remote" && value.enabled === true && value.oauth === false &&
+      typeof value.url === "string") return value.url;
+  return null;
+};
+const isTaskGatewayUrl = (value, slug) => {
+  let parsed;
+  try { parsed = new URL(value); } catch { return false; }
+  if (parsed.protocol !== "http:" || (parsed.port || "80") !== gatewayPort ||
+      parsed.username || parsed.password || parsed.search || parsed.hash) return false;
+  const segments = parsed.pathname.split("/").filter(Boolean);
+  if (segments.length !== 3 || segments[0] !== "t" || segments[2] !== slug) return false;
+  const prefix = taskId + ".";
+  return value === "http://" + parsed.hostname + ":" + gatewayPort +
+      "/t/" + segments[1] + "/" + slug &&
+    segments[1].startsWith(prefix) &&
+    /^[A-Za-z0-9_-]{32}$/.test(segments[1].slice(prefix.length));
+};
+const isManaged = (value, slug) => {
+  const url = managedUrl(value);
+  return url !== null && isTaskGatewayUrl(url, slug);
+};
+for (const [slug, value] of Object.entries(desired)) {
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(slug) || !isManaged(value, slug)) {
+    throw new Error("invalid desired MCP definition for " + slug);
+  }
+}
+let original = null;
+let j = {};
+try {
+  original = fs.readFileSync(p, "utf8");
+  j = JSON.parse(original);
+} catch (error) {
+  if (!error || error.code !== "ENOENT") throw error;
+}
+if (!plainObject(j)) throw new Error("MCP config root must be an object");
+if (j[key] === undefined) {
+  if (Object.keys(desired).length === 0 && flavor !== "claude") process.exit(0);
+  j[key] = {};
+}
+if (!plainObject(j[key])) {
+  throw new Error("MCP config " + key + " must be an object");
+}
+let changed = false;
+// A foreign same-name entry is a local shadow, not a failed reconciliation:
+// preserve it, apply every other slug, and memoize success. If the user later
+// removes it, the next dirty pass or task restart installs the Uai definition.
+const skipped = new Set();
+const warnings = [];
+for (const [slug, current] of Object.entries(j[key])) {
+  if (Object.hasOwn(desired, slug)) {
+    if (JSON.stringify(current) === JSON.stringify(desired[slug])) continue;
+    if (!isManaged(current, slug)) {
+      skipped.add(slug);
+      continue;
+    }
+    j[key][slug] = desired[slug];
+    changed = true;
+  } else if (isManaged(current, slug)) {
+    delete j[key][slug];
+    changed = true;
+  }
+}
+for (const [slug, value] of Object.entries(desired)) {
+  if (!Object.hasOwn(j[key], slug)) {
+    j[key][slug] = value;
+    changed = true;
+  }
+}
+for (const slug of skipped) {
+  warnings.push(
+    "[uai-mcp] kept foreign server " + slug +
+    "; skipped its Uai definition in " + p + "\\n"
+  );
+}
+if (changed || original === null) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const mode = original === null ? 0o644 : fs.statSync(p).mode & 0o777;
+  const tmp = path.join(
+    path.dirname(p),
+    "." + path.basename(p) + "." + process.pid + "." +
+      crypto.randomBytes(8).toString("hex") + ".tmp"
+  );
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(j, null, 2) + "\\n", {
+      encoding: "utf8",
+      flag: "wx",
+      mode,
+    });
+    let current = null;
+    try {
+      current = fs.readFileSync(p, "utf8");
+    } catch (error) {
+      if (!error || error.code !== "ENOENT") throw error;
+    }
+    if (current !== original) {
+      throw new Error("MCP config changed concurrently");
+    }
+    fs.renameSync(tmp, p);
+  } finally {
+    try { fs.unlinkSync(tmp); } catch {}
+  }
+}
+for (const warning of warnings) process.stderr.write(warning);
+`.trim();
+
+/**
+ * Ensure the host-gateway MCP definitions in one Codex home.
+ *
+ * Codex itself is the TOML parser. This matters because a text search cannot
+ * distinguish `[mcp_servers.foo]` from a comment/string, and quoted or spaced
+ * spellings name the same TOML table. A same-name definition is accepted only
+ * when Codex reports the exact shape Uai writes. Foreign same-name definitions
+ * shadow only that slug; malformed configs still fail without modification.
+ */
+export const ENSURE_CODEX_MCP_TOML = String.raw`
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const child = require("child_process");
+
+const home = process.argv[1];
+const desired = JSON.parse(process.argv[2]);
+const codexBin = process.argv[3] || "codex";
+const taskId = process.argv[4];
+const plainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+if (typeof home !== "string" || !path.isAbsolute(home)) {
+  throw new Error("Codex home must be an absolute path");
+}
+if (typeof taskId !== "string" || taskId.length === 0) {
+  throw new Error("invalid MCP task id");
+}
+if (!plainObject(desired)) {
+  throw new Error("Codex MCP definitions must be an object");
+}
+for (const [slug, url] of Object.entries(desired)) {
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(slug)) {
+    throw new Error("invalid Codex MCP slug");
+  }
+  if (typeof url !== "string") {
+    throw new Error("invalid Codex MCP URL");
+  }
+}
+
+fs.mkdirSync(home, { recursive: true });
+// Codex canonicalizes CODEX_HOME before resolving relative config paths. Keep
+// the same stable target so symlinked homes validate beside the directory
+// Codex actually uses, not beside the link's lexical parent.
+const sourceHome = fs.realpathSync(home);
+const file = path.join(sourceHome, "config.toml");
+let original = null;
+try {
+  original = fs.readFileSync(file, "utf8");
+} catch (error) {
+  if (!error || error.code !== "ENOENT") throw error;
+}
+
+function runCodex(args, codexHome = sourceHome) {
+  return child.spawnSync(codexBin, args, {
+    encoding: "utf8",
+    env: Object.assign({}, process.env, { CODEX_HOME: codexHome }),
+    maxBuffer: 1024 * 1024,
+    timeout: 5000,
+    killSignal: "SIGKILL",
+  });
+}
+
+function detail(result) {
+  const lines = String(result.stderr || "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  return String(lines.pop() || result.error || result.status);
+}
+
+function exactKeys(value, keys) {
+  return plainObject(value) &&
+    Object.keys(value).sort().join("\0") === keys.slice().sort().join("\0");
+}
+
+function managedDefinitionUrl(value, slug) {
+  const topKeys = [
+    "auth_status", "disabled_reason", "enabled", "name",
+    "startup_timeout_sec", "tool_timeout_sec", "transport"
+  ];
+  const transportKeys = ["args", "command", "cwd", "env", "env_vars", "type"];
+  if (!(exactKeys(value, topKeys) &&
+    value.name === slug &&
+    value.enabled === true &&
+    value.disabled_reason === null &&
+    value.auth_status === "unsupported" &&
+    value.startup_timeout_sec === null &&
+    value.tool_timeout_sec === null &&
+    exactKeys(value.transport, transportKeys) &&
+    value.transport.type === "stdio" &&
+    value.transport.command === "npx" &&
+    Array.isArray(value.transport.args) &&
+    value.transport.args.length === 4 &&
+    value.transport.args[0] === "-y" &&
+    value.transport.args[1] === "mcp-remote" &&
+    typeof value.transport.args[2] === "string" &&
+    value.transport.args[3] === "--allow-http" &&
+    value.transport.cwd === null &&
+    value.transport.env === null &&
+    Array.isArray(value.transport.env_vars) &&
+    value.transport.env_vars.length === 0)) {
+    return null;
+  }
+  return value.transport.args[2];
+}
+
+function exactDefinition(value, slug, url) {
+  return managedDefinitionUrl(value, slug) === url;
+}
+
+function gatewayIdentity(value, slug) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== "http:" || (parsed.port || "80") !== "${MCP_GATEWAY_PORT}" ||
+      parsed.username || parsed.password || parsed.search || parsed.hash) {
+    return null;
+  }
+  const segments = parsed.pathname.split("/").filter(Boolean);
+  if (segments.length !== 3 || segments[0] !== "t" || segments[2] !== slug ||
+      parsed.pathname !== "/t/" + segments[1] + "/" + slug) {
+    return null;
+  }
+  const token = /^([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]{32})$/.exec(segments[1]);
+  if (!token || value !== "http://" + parsed.hostname + ":${MCP_GATEWAY_PORT}" +
+      "/t/" + segments[1] + "/" + slug) return null;
+  return { origin: parsed.origin, taskId: token[1] };
+}
+
+function sameTaskGateway(oldUrl, desiredUrl, slug) {
+  // Ownership is proven by the /t/<taskId>.<token>/<slug> path, not the
+  // origin: the gateway host is topology-dependent (container gateway IP,
+  // host.docker.internal, machine loopback behind a reverse tunnel) and
+  // migrating a task across topologies is exactly when the rewrite runs.
+  const oldIdentity = gatewayIdentity(oldUrl, slug);
+  const desiredIdentity = gatewayIdentity(desiredUrl, slug);
+  return oldIdentity !== null &&
+    desiredIdentity !== null &&
+    oldIdentity.taskId === desiredIdentity.taskId;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^$(){}|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Replace or remove a raw block Uai can prove it authored.
+ * The exact legacy three-line shape predates the marker. New blocks carry the
+ * ADR-057 marker. A quoted/spaced header, extra field, or neighboring body
+ * text is deliberately foreign even if Codex normalizes it to the same JSON.
+ */
+function editManagedRawBlock(text, slug, oldUrl, desiredUrl) {
+  const prefix =
+    "(^|\\r?\\n)\\[mcp_servers\\." + escapeRegExp(slug) + "\\]\\r?\\n" +
+    "command = \\\"npx\\\"\\r?\\n";
+  const legacyPattern = new RegExp(
+    prefix +
+      "args = \\[\\\"-y\\\", \\\"mcp-remote\\\", " +
+      escapeRegExp(JSON.stringify(oldUrl)) +
+      ", \\\"--allow-http\\\"\\](?=\\r?\\n|$)",
+    "g"
+  );
+  const markedPattern = new RegExp(
+    "(^|\\r?\\n)# uai ADR-057: host MCP gateway\\r?\\n" +
+      "\\[mcp_servers\\." + escapeRegExp(slug) + "\\]\\r?\\n" +
+      "command = \\\"npx\\\"\\r?\\n" +
+      "args = " +
+      escapeRegExp(JSON.stringify([
+        "-y", "mcp-remote", oldUrl, "--allow-http"
+      ])) +
+      "(?=\\r?\\n|$)",
+    "g"
+  );
+  const matches = [
+    ...Array.from(text.matchAll(legacyPattern)),
+    ...Array.from(text.matchAll(markedPattern)),
+  ].filter((match) => {
+    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((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 replacement = desiredUrl === null
+    ? match[1]
+    : match[0].replace(JSON.stringify(oldUrl), JSON.stringify(desiredUrl));
+  return text.slice(0, start) + replacement + text.slice(start + match[0].length);
+}
+
+/** The Codex parser has already proved the table's semantics. This raw check
+ * rejects user customizations the list view intentionally omits, while still
+ * accepting equivalent quoted/spaced table headers without claiming them as
+ * removable Uai-owned text. */
+function plainRawDefinition(text, slug) {
+  const atom = escapeRegExp(slug);
+  const header = new RegExp(
+    "^[ \\t]*\\[[ \\t]*(?:\\\"mcp_servers\\\"|'mcp_servers'|mcp_servers)" +
+      "[ \\t]*\\.[ \\t]*(?:\\\"" + atom + "\\\"|'" + atom + "'|" + atom + ")" +
+      "[ \\t]*\\][ \\t]*(?:#.*)?$",
+    "gm"
+  );
+  const matches = Array.from(text.matchAll(header));
+  if (matches.length !== 1) return false;
+  const match = matches[0];
+  const remainder = text.slice((match.index || 0) + match[0].length);
+  const nextHeader = remainder.search(/^[ \t]*\[\[?.+\]\]?[ \t]*(?:#.*)?\r?$/m);
+  const body = nextHeader === -1 ? remainder : remainder.slice(0, nextHeader);
+  const fields = body
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line !== "" && !line.startsWith("#"));
+  return fields.length === 2 &&
+    fields.some((line) => /^command[ \t]*=/.test(line)) &&
+    fields.some((line) => /^args[ \t]*=/.test(line));
+}
+
+/** Any descendant table is user/Codex-authored state that the parent marker
+ * does not prove Uai owns. Scan the whole document: TOML permits unrelated
+ * tables between a parent and its descendants. */
+function hasRawDescendantTable(text, slug) {
+  const atom = escapeRegExp(slug);
+  return new RegExp(
+    "^[ \\t]*\\[\\[?[ \\t]*(?:\\\"mcp_servers\\\"|'mcp_servers'|mcp_servers)" +
+      "[ \\t]*\\.[ \\t]*(?:\\\"" + atom + "\\\"|'" + atom + "'|" + atom + ")" +
+      "[ \\t]*\\.",
+    "m"
+  ).test(text);
+}
+
+function listDefinitions(codexHome = sourceHome) {
+  // One list call validates the whole TOML document and identifies truly
+  // absent servers. A malformed document fails before any edit.
+  const result = runCodex(["mcp", "list", "--json"], codexHome);
+  if (result.status !== 0) {
+    throw new Error("Codex config is invalid: " + detail(result));
+  }
+  let value;
+  try {
+    value = JSON.parse(result.stdout);
+  } catch {
+    throw new Error("codex mcp list returned invalid JSON");
+  }
+  if (!Array.isArray(value) ||
+      !value.every((entry) => plainObject(entry) && typeof entry.name === "string")) {
+    throw new Error("codex mcp list returned an invalid server list");
+  }
+  return value;
+}
+
+/** Validate a candidate before publication through the same Codex parser used
+ * for the real home. The sibling directory preserves ../ relative paths; its
+ * top-level symlinks preserve paths within CODEX_HOME without copying secrets
+ * or other account state. */
+function validateCandidate(text, mode) {
+  const validationHome = fs.mkdtempSync(path.join(
+    path.dirname(sourceHome),
+    "." + path.basename(sourceHome) + ".uai-validate-"
+  ));
+  try {
+    for (const name of fs.readdirSync(sourceHome)) {
+      if (name === path.basename(file)) continue;
+      fs.symlinkSync(
+        path.join(sourceHome, name),
+        path.join(validationHome, name)
+      );
+    }
+    const validationFile = path.join(validationHome, path.basename(file));
+    fs.writeFileSync(validationFile, text, {
+      encoding: "utf8",
+      flag: "wx",
+      mode,
+    });
+    const definitions = listDefinitions(validationHome);
+    if (fs.readFileSync(validationFile, "utf8") !== text) {
+      throw new Error("Codex changed its config during candidate validation");
+    }
+    return definitions;
+  } finally {
+    fs.rmSync(validationHome, { recursive: true, force: true });
+  }
+}
+
+for (const [slug, url] of Object.entries(desired)) {
+  if (gatewayIdentity(url, slug)?.taskId !== taskId) {
+    throw new Error("invalid desired Codex MCP gateway URL");
+  }
+}
+
+const listed = listDefinitions();
+const bySlug = new Map();
+for (const entry of listed) {
+  if (bySlug.has(entry.name)) {
+    throw new Error("Codex MCP server " + entry.name + " is duplicated - left unchanged");
+  }
+  bySlug.set(entry.name, entry);
+}
+
+const managed = new Map();
+const customized = new Set();
+for (const [slug, definition] of bySlug) {
+  const url = managedDefinitionUrl(definition, slug);
+  if (url !== null && gatewayIdentity(url, slug)?.taskId === taskId) {
+    if (!hasRawDescendantTable(original || "", slug) &&
+        editManagedRawBlock(original || "", slug, url, url) !== null) {
+      managed.set(slug, url);
+    } else {
+      customized.add(slug);
+    }
+  }
+}
+
+const missing = [];
+const rewrites = [];
+// As with JSON configs, a foreign definition shadows only this slug in this
+// home. Other homes and engine writers must still run.
+const skipped = new Set();
+const warnings = [];
+for (const [slug, url] of Object.entries(desired)) {
+  const definition = bySlug.get(slug);
+  if (definition === undefined) {
+    missing.push([slug, url]);
+    continue;
+  }
+  if (exactDefinition(definition, slug, url) &&
+      plainRawDefinition(original || "", slug)) continue;
+  const oldUrl = managed.get(slug);
+  if (oldUrl === undefined || !sameTaskGateway(oldUrl, url, slug)) {
+    skipped.add(slug);
+    continue;
+  }
+  rewrites.push([slug, oldUrl, url]);
+}
+const removals = [...managed.entries()].filter(([slug]) =>
+  !Object.hasOwn(desired, slug)
+);
+for (const slug of skipped) {
+  warnings.push(
+    "[uai-mcp] kept foreign Codex server " + slug +
+    "; skipped its Uai definition in " + home + "\n"
+  );
+}
+for (const slug of customized) {
+  if (!Object.hasOwn(desired, slug)) {
+    warnings.push(
+      "[uai-mcp] kept customized Codex server " + slug +
+      "; skipped its Uai removal in " + home + "\n"
+    );
+  }
+}
+if (missing.length === 0 && rewrites.length === 0 && removals.length === 0) {
+  for (const warning of warnings) process.stderr.write(warning);
+  process.exit(0);
+}
+
+const newline = original && original.includes("\r\n") ? "\r\n" : "\n";
+const blocks = missing.map(([slug, url]) => [
+  "# uai ADR-057: host MCP gateway",
+  "[mcp_servers." + slug + "]",
+  'command = "npx"',
+  "args = " + JSON.stringify(["-y", "mcp-remote", url, "--allow-http"]),
+  "",
+].join(newline)).join(newline);
+let next = original || "";
+for (const [slug, oldUrl] of removals) {
+  const removed = editManagedRawBlock(next, slug, oldUrl, null);
+  if (removed === null) {
+    throw new Error("Codex MCP server " + slug + " has foreign TOML text - left unchanged");
+  }
+  next = removed;
+}
+for (const [slug, oldUrl, desiredUrl] of rewrites) {
+  const rewritten = editManagedRawBlock(next, slug, oldUrl, desiredUrl);
+  if (rewritten === null) {
+    throw new Error("Codex MCP server " + slug + " has foreign TOML text - left unchanged");
+  }
+  next = rewritten;
+}
+if (next.length > 0 && !next.endsWith("\n")) next += newline;
+if (blocks.length > 0) {
+  if (next.length > 0 && !next.endsWith(newline + newline)) next += newline;
+  next += blocks;
+}
+
+const mode = original === null ? 0o644 : fs.statSync(file).mode & 0o777;
+// Validate and verify the complete candidate before it can replace the real
+// file. This is the final safety boundary for TOML spellings the conservative
+// raw ownership checks do not recognize (for example escaped quoted keys).
+const verified = validateCandidate(next, mode);
+const verifiedBySlug = new Map(verified.map((entry) => [entry.name, entry]));
+for (const [slug, url] of Object.entries(desired)) {
+  if (skipped.has(slug)) continue;
+  if (!exactDefinition(verifiedBySlug.get(slug), slug, url) ||
+      !plainRawDefinition(next, slug)) {
+    throw new Error("Codex MCP server " + slug + " failed verification");
+  }
+}
+for (const [slug] of removals) {
+  if (verifiedBySlug.has(slug)) {
+    throw new Error("Codex MCP server " + slug + " was not removed");
+  }
+}
+
+const tmp = path.join(
+  sourceHome,
+  "." + path.basename(file) + "." + process.pid + "." +
+    crypto.randomBytes(8).toString("hex") + ".tmp"
+);
+try {
+  fs.writeFileSync(tmp, next, {
+    encoding: "utf8",
+    flag: "wx",
+    mode,
+  });
+  let current = null;
+  try {
+    current = fs.readFileSync(file, "utf8");
+  } catch (error) {
+    if (!error || error.code !== "ENOENT") throw error;
+  }
+  if (current !== original) {
+    throw new Error("Codex config changed concurrently");
+  }
+  if (fs.realpathSync(home) !== sourceHome) {
+    throw new Error("Codex home changed concurrently");
+  }
+  fs.renameSync(tmp, file);
+} finally {
+  try { fs.unlinkSync(tmp); } catch {}
+}
+for (const warning of warnings) process.stderr.write(warning);
+`.trim();
+
+/** Reconcile one GROK_HOME through Grok's own parser/writer. Compatibility
+ * sources and project scope are disabled for the ownership probe: only an
+ * exact user-scope HTTP entry routed through this task's gateway is removed
+ * or replaced. */
+export const RECONCILE_GROK_MCP = String.raw`
+const child = require("child_process");
+const path = require("path");
+
+const home = process.argv[1];
+const desired = JSON.parse(process.argv[2]);
+const grokBin = process.argv[3];
+const taskId = process.argv[4];
+const plainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+if (typeof home !== "string" || !path.isAbsolute(home)) {
+  throw new Error("Grok home must be an absolute path");
+}
+if (!plainObject(desired)) {
+  throw new Error("Grok MCP definitions must be an object");
+}
+if (typeof grokBin !== "string" || !path.isAbsolute(grokBin)) {
+  throw new Error("Grok binary must be an absolute path");
+}
+if (typeof taskId !== "string" || taskId.length === 0) {
+  throw new Error("invalid MCP task id");
+}
+
+function gatewayIdentity(value, slug) {
+  let parsed;
+  try { parsed = new URL(value); } catch { return null; }
+  if (parsed.protocol !== "http:" || (parsed.port || "80") !== "${MCP_GATEWAY_PORT}" ||
+      parsed.username || parsed.password || parsed.search || parsed.hash) return null;
+  const segments = parsed.pathname.split("/").filter(Boolean);
+  if (segments.length !== 3 || segments[0] !== "t" || segments[2] !== slug ||
+      parsed.pathname !== "/t/" + segments[1] + "/" + slug) return null;
+  const prefix = taskId + ".";
+  if (!segments[1].startsWith(prefix) ||
+      !/^[A-Za-z0-9_-]{32}$/.test(segments[1].slice(prefix.length))) return null;
+  if (value !== "http://" + parsed.hostname + ":${MCP_GATEWAY_PORT}" +
+      "/t/" + segments[1] + "/" + slug) return null;
+  return { taskId: taskId };
+}
+
+for (const [slug, url] of Object.entries(desired)) {
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(slug) ||
+      typeof url !== "string" || gatewayIdentity(url, slug) === null) {
+    throw new Error("invalid desired Grok MCP definition for " + slug);
+  }
+}
+
+function run(args) {
+  return child.spawnSync(grokBin, args, {
+    cwd: "/",
+    encoding: "utf8",
+    env: Object.assign({}, process.env, {
+      GROK_HOME: home,
+      GROK_CURSOR_MCPS_ENABLED: "false",
+      GROK_CLAUDE_MCPS_ENABLED: "false",
+    }),
+    maxBuffer: 1024 * 1024,
+    timeout: 5000,
+    killSignal: "SIGKILL",
+  });
+}
+
+function detail(result) {
+  const lines = String(result.stderr || result.stdout || "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  return String(lines.pop() || result.error || result.status);
+}
+
+function list() {
+  const result = run(["mcp", "list", "--json"]);
+  if (result.status !== 0) {
+    throw new Error("Grok config is invalid: " + detail(result));
+  }
+  let value;
+  try { value = JSON.parse(result.stdout); }
+  catch { throw new Error("grok mcp list returned invalid JSON"); }
+  if (!Array.isArray(value) ||
+      !value.every((entry) => plainObject(entry) && typeof entry.name === "string")) {
+    throw new Error("grok mcp list returned an invalid server list");
+  }
+  return value;
+}
+
+function managedUrl(entry, slug) {
+  if (!plainObject(entry)) return null;
+  const keys = Object.keys(entry).sort().join("\0");
+  if (keys !== ["enabled", "name", "scope", "url"].sort().join("\0") ||
+      entry.name !== slug || entry.scope !== "user" || entry.enabled !== true ||
+      typeof entry.url !== "string") return null;
+  return gatewayIdentity(entry.url, slug) === null ? null : entry.url;
+}
+
+const current = new Map();
+const managed = new Map();
+for (const entry of list()) {
+  if (current.has(entry.name)) {
+    throw new Error("Grok MCP server " + entry.name + " is duplicated - left unchanged");
+  }
+  current.set(entry.name, entry);
+  const url = managedUrl(entry, entry.name);
+  if (url !== null) managed.set(entry.name, url);
+}
+
+const additions = [];
+// A user-scope foreign entry shadows only this slug in this GROK_HOME.
+const skipped = new Set();
+const warnings = [];
+for (const [slug, url] of Object.entries(desired)) {
+  const entry = current.get(slug);
+  if (entry === undefined) {
+    additions.push([slug, url]);
+  } else if (managed.get(slug) === url) {
+    continue;
+  } else if (managed.has(slug)) {
+    additions.push([slug, url]);
+  } else {
+    skipped.add(slug);
+  }
+}
+const removals = [...managed.keys()].filter((slug) => !Object.hasOwn(desired, slug));
+for (const slug of skipped) {
+  warnings.push(
+    "[uai-mcp] kept foreign Grok server " + slug +
+    "; skipped its Uai definition in " + home + "\n"
+  );
+}
+if (additions.length === 0 && removals.length === 0) {
+  for (const warning of warnings) process.stderr.write(warning);
+  process.exit(0);
+}
+
+for (const [slug, url] of additions) {
+  const result = run(["mcp", "add", slug, url, "-t", "http", "-s", "user"]);
+  if (result.status !== 0) {
+    throw new Error("grok mcp add " + slug + " failed: " + detail(result));
+  }
+}
+for (const slug of removals) {
+  const result = run(["mcp", "remove", slug, "-s", "user"]);
+  if (result.status !== 0) {
+    throw new Error("grok mcp remove " + slug + " failed: " + detail(result));
+  }
+}
+
+const verified = new Map(list().map((entry) => [entry.name, entry]));
+for (const [slug, url] of Object.entries(desired)) {
+  if (skipped.has(slug)) continue;
+  if (managedUrl(verified.get(slug), slug) !== url) {
+    throw new Error("Grok MCP server " + slug + " failed verification");
+  }
+}
+for (const slug of removals) {
+  if (verified.has(slug)) {
+    throw new Error("Grok MCP server " + slug + " was not removed");
+  }
+}
+for (const warning of warnings) process.stderr.write(warning);
+`.trim();
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/** Config homes are independent, but every Uai/browser writer must remain
+ * behind one flock. Run a bounded batch at a time so the supported account ×
+ * agent count cannot turn the outer timeout into a deterministic failure. */
+const MCP_CONFIG_HOME_WRITE_CONCURRENCY = 8;
+
+function boundedParallelShell(
+  commands: readonly string[],
+  width = MCP_CONFIG_HOME_WRITE_CONCURRENCY,
+): string | null {
+  if (commands.length === 0) return null;
+  const batches: string[] = [];
+  for (let offset = 0; offset < commands.length; offset += width) {
+    const batch = commands.slice(offset, offset + width);
+    const launches = batch.map(
+      (command, index) => `(${command}) & uai_mcp_pid_${index}=$!`,
+    );
+    const waits = batch.map(
+      (_command, index) =>
+        `wait "$uai_mcp_pid_${index}" || uai_mcp_status=1`,
+    );
+    batches.push(
+      `{ ${launches.join("; ")}; uai_mcp_status=0; ${waits.join("; ")}; ` +
+        `[ "$uai_mcp_status" -eq 0 ]; }`,
+    );
+  }
+  return batches.join(" && ");
+}
+
+// The host must never win this timeout race: killing the local `docker exec`
+// client does not kill its in-container child. The in-runtime deadline scales
+// with bounded home batches below; the host backstop always follows TERM/KILL.
+/** The grok CLI inside task containers/machines (x.ai installer path). */
+const GROK_BIN = "/home/node/.grok/bin/grok";
+const MCP_CONFIG_MIN_WRITE_TIMEOUT_S = 25;
+const MCP_CONFIG_WRITE_KILL_AFTER_S = 5;
+const MCP_CONFIG_HOST_GRACE_S = 10;
+const MCP_CONFIG_CODEX_BATCH_BUDGET_S = 3;
+// One home can replace/remove two disjoint maximum-size memberships. Grok's
+// CLI has no bulk mutation, so give a bounded batch a budget proportional to
+// the accepted manifest ceiling rather than pretending it is constant work.
+const MCP_CONFIG_GROK_BATCH_BUDGET_S = 2 + Math.ceil(MAX_MANIFEST_MCP / 4);
+
+/**
+ * Write the task's MCP configs inside the container, one shape per engine on
+ * the roster — all pointing at the same host gateway URLs:
+ *   - Claude — /workspace/.mcp.json (merged; coexists with the ADR-053 browser
+ *     server). Written unconditionally: the adapter passes `--mcp-config`.
+ *   - Codex — reconciled mcp-remote shims in config.toml.
+ *   - Cursor — ~/.cursor/mcp.json ({ url } form; the adapter passes
+ *     `--approve-mcps`).
+ *   - Grok — reconciled through `grok mcp` in every GROK_HOME the task may use
+ *     (project scope is refused in an untrusted folder).
+ *   - OpenCode — ~/.config/opencode/opencode.json `mcp` block (type:"remote",
+ *     oauth:false so it treats the gateway URL as a plain server; the path
+ *     token is the auth).
+ * Safe to re-run every ensure. `engineKinds` is the roster's agent kinds.
+ */
+export async function setupMcpTaskConfig(
+  taskId: string,
+  containerName: string,
+  connections: TaskMcpConnection[],
+  engineKinds: string[],
+  codexHomes: readonly string[] = ["/home/node/.codex"],
+  environment?: Pick<TaskEnvironmentHandle, "exec"> &
+    Partial<Pick<TaskEnvironmentHandle, "descriptor">>,
+  /** Every GROK_HOME the task may run under (default + account homes). */
+  grokHomes: readonly string[] = ["/home/node/.grok"],
+): Promise<boolean> {
+  // No early return on empty: the claude adapter passes
+  // `--mcp-config /workspace/.mcp.json` unconditionally (ADR-057), so the
+  // file must exist — an empty mcpServers map — even with no connections.
+  try {
+    // Boot-time standard-image maintenance can briefly replace the shared CLI
+    // shims used by these in-container writers. The ACL is itself observable
+    // state, so hold the same barrier before it or any Docker side effect.
+    await agentClisReady;
+    const has = (kind: string): boolean => engineKinds.includes(kind);
+    if (
+      has("codex") &&
+      connections.some(
+        (connection) =>
+          !/^[a-z0-9][a-z0-9-]{0,63}$/.test(connection.slug),
+      )
+    ) {
+      throw new Error("invalid Codex MCP connection slug");
+    }
+    const acl = ensureTaskGatewayAcl(taskId, connections);
+    // ADR-121: a machine dials the gateway through its ssh REVERSE tunnel —
+    // the host's loopback appears at the machine's own 127.0.0.1:PORT
+    // (machine-gateway-tunnel.ts). host.docker.internal / vmnet addresses
+    // are container topology a machine can never route.
+    const gatewayHost =
+      isEnvironmentTransportProvider(environment?.descriptor?.locator.provider)
+        ? "127.0.0.1"
+        : await taskGatewayHost();
+    const urlFor = (slug: string): string =>
+      `http://${gatewayHost}:${MCP_GATEWAY_PORT}/t/${acl.token}/${slug}`;
+
+    const claudeEntries: Record<string, unknown> = {};
+    const codexEntries: Record<string, string> = {};
+    const cursorEntries: Record<string, unknown> = {};
+    const opencodeEntries: Record<string, unknown> = {};
+    for (const c of connections) {
+      claudeEntries[c.slug] = { type: "http", url: urlFor(c.slug) };
+      codexEntries[c.slug] = urlFor(c.slug);
+      // Cursor's mcp.json wants a bare { url } for remote (http/sse) servers.
+      cursorEntries[c.slug] = { url: urlFor(c.slug) };
+      // OpenCode: type:"remote" + oauth:false — the gateway needs no client
+      // auth (the path token is the secret), so suppress OpenCode's own OAuth
+      // flow that would otherwise fire on a gateway 401 and hang headless.
+      opencodeEntries[c.slug] = {
+        type: "remote",
+        url: urlFor(c.slug),
+        enabled: true,
+        oauth: false,
+      };
+    }
+    const codexWrites = has("codex")
+      ? codexHomes.map(
+          (home) =>
+            `node -e "$uai_codex_mcp_writer" ${shellQuote(home)} ` +
+            `"$uai_mcp_desired" codex "$uai_mcp_task"`,
+        )
+      : [];
+    const grokWrites = has("grok")
+      ? grokHomes
+          .filter((home) => /^\/home\/node\/\.grok(-acct-[A-Za-z0-9_-]+)?$/.test(home))
+          .map(
+            (home) =>
+              `node -e "$uai_grok_mcp_writer" ${shellQuote(home)} ` +
+              `"$uai_mcp_desired" ${GROK_BIN} "$uai_mcp_task"`,
+          )
+      : [];
+    const homeWrites = boundedParallelShell([...codexWrites, ...grokWrites]);
+    const codexBatches = Math.ceil(
+      codexWrites.length / MCP_CONFIG_HOME_WRITE_CONCURRENCY,
+    );
+    const grokBatches = Math.ceil(
+      grokWrites.length / MCP_CONFIG_HOME_WRITE_CONCURRENCY,
+    );
+    const writeTimeoutS = Math.max(
+      MCP_CONFIG_MIN_WRITE_TIMEOUT_S,
+      10 +
+        codexBatches * MCP_CONFIG_CODEX_BATCH_BUDGET_S +
+        grokBatches * MCP_CONFIG_GROK_BATCH_BUDGET_S,
+    );
+    const hostTimeoutMs =
+      (writeTimeoutS +
+        MCP_CONFIG_WRITE_KILL_AFTER_S +
+        MCP_CONFIG_HOST_GRACE_S) *
+      1_000;
+    // Browser migration touches these same Claude/Codex/Cursor files and
+    // invokes Grok's own read-modify-write CLI. Keep every shared writer in
+    // one critical section so neither side can erase the other's update.
+    const lockedWrites = [
+      `[ -f /workspace/.claude/settings.json ] || printf '%s\\n' ${shellQuote(
+        JSON.stringify({ enableAllProjectMcpServers: true }, null, 2),
+      )} > /workspace/.claude/settings.json`,
+      `node -e ${shellQuote(
+        MERGE_MCP_JSON,
+      )} /workspace/.mcp.json ${shellQuote(JSON.stringify(claudeEntries))} mcpServers claude ${shellQuote(
+        taskId,
+      )}`,
+      ...(homeWrites === null
+        ? []
+        : [
+            `uai_mcp_desired=${shellQuote(JSON.stringify(codexEntries))}`,
+            `uai_mcp_task=${shellQuote(taskId)}`,
+            ...(codexWrites.length === 0
+              ? []
+              : [`uai_codex_mcp_writer=${shellQuote(ENSURE_CODEX_MCP_TOML)}`]),
+            ...(grokWrites.length === 0
+              ? []
+              : [`uai_grok_mcp_writer=${shellQuote(RECONCILE_GROK_MCP)}`]),
+          ]),
+      // Codex/Grok homes do not share files. Bound their parallelism while
+      // holding the one cross-writer lock; each home still reconciles itself
+      // serially through its engine's parser/writer.
+      ...(homeWrites === null ? [] : [homeWrites]),
+      ...(has("cursor")
+        ? [
+            `node -e ${shellQuote(MERGE_MCP_JSON)} /home/node/.cursor/mcp.json ${shellQuote(
+              JSON.stringify(cursorEntries),
+            )} mcpServers cursor ${shellQuote(taskId)}`,
+          ]
+        : []),
+    ].join(" && ");
+    const writes = [
+      "mkdir -p /workspace/.claude",
+      `flock -w 10 ${MCP_CONFIG_LOCK_PATH} sh -lc ${shellQuote(lockedWrites)}`,
+      // OpenCode: global config `mcp` block (auto-discovered regardless of the
+      // exec cwd, and independent of any per-account OPENCODE_DATA_DIR).
+      ...(has("opencode")
+        ? [
+            `node -e ${shellQuote(MERGE_MCP_JSON)} /home/node/.config/opencode/opencode.json ${shellQuote(
+              JSON.stringify(opencodeEntries),
+            )} mcp opencode ${shellQuote(taskId)}`,
+          ]
+        : []),
+    ].join(" && ");
+    const steps =
+      `timeout --kill-after=${MCP_CONFIG_WRITE_KILL_AFTER_S} ` +
+      `${writeTimeoutS} sh -lc ${shellQuote(writes)}`;
+    const result = environment
+      ? await environment.exec({
+          argv: ["sh", "-lc", steps],
+          env: RUNTIME_AUTHORITY_ENV,
+          projectEnvProfile: "maintenance",
+          timeoutMs: hostTimeoutMs,
+          maxOutputBytes: 256 * 1024,
+        })
+      : await taskContainerCli(
+          [
+            "exec",
+            ...runtimeAuthorityDockerExecArgs(),
+            // Backend-aware fallback: the passed name is the Docker replica
+            // shape and `docker` does not exist on an apple host (live
+            // 2026-08-18: spawn docker ENOENT killed every no-handle config
+            // write, so sessions never saw their MCP tools).
+            taskContainerBackend().apple
+              ? taskAppContainerName(taskId)
+              : containerName,
+            "sh",
+            "-lc",
+            steps,
+          ],
+          { timeoutMs: hostTimeoutMs },
+        );
+    const status = "exitCode" in result ? result.exitCode : result.status;
+    const stderrValue = "stderr" in result ? result.stderr : "";
+    const stderr = stderrValue instanceof Uint8Array
+      ? Buffer.from(stderrValue).toString("utf8")
+      : String(stderrValue ?? "");
+    if (status !== 0) {
+      // Earlier writers in the && chain may have succeeded with local-shadow
+      // warnings before a later writer failed. Remove only those known soft
+      // lines so the bounded log cannot hide the hard parse/I/O diagnostic.
+      const hardStderr = stderr
+        .split(/\r?\n/)
+        .filter((line) =>
+          !/^\[uai-mcp\] kept (?:foreign|customized) .+; skipped its Uai (?:definition|removal) in /.test(line),
+        )
+        .join("\n")
+        .trim();
+      console.warn(
+        `[mcp-gateway] task ${taskId}: config write failed: ${(hardStderr || stderr).slice(0, 300)}`,
+      );
+      return false;
+    }
+    if (stderr.trim().length > 0) {
+      console.warn(
+        `[mcp-gateway] task ${taskId}: config write warning: ${stderr.slice(0, 300)}`,
+      );
+    }
+    return true;
+  } catch (err) {
+    console.warn(
+      `[mcp-gateway] task ${taskId}: setup failed: ${err instanceof Error ? err.message : err}`,
+    );
+    return false;
+  }
+}