@runuai/host 0.9.152 → 0.9.153

package/lib/mcp-gateway.ts

@@ -96,6 +96,7 @@ import {
   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";
 
@@ -1580,20 +1581,65 @@ export async function stopMcpGateway(): Promise<void> {
 
 // --- task container wiring (ADR-057 task-up writers) -------------------------
 
-/** Idempotent node -e merge of entries (argv[2]) into a JSON file (argv[1])
- *  under a top-level object key (argv[3], default "mcpServers") — reused for
- *  Claude's /workspace/.mcp.json + Cursor's ~/.cursor/mcp.json (mcpServers)
- *  and OpenCode's ~/.config/opencode/opencode.json (mcp). Creates the parent
- *  dir when missing. */
+/** 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);
-fs.mkdirSync(path.dirname(p), { recursive: true });
+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 {
@@ -1603,15 +1649,47 @@ try {
   if (!error || error.code !== "ENOENT") throw error;
 }
 if (!plainObject(j)) throw new Error("MCP config root must be an object");
-if (j[key] === undefined) j[key] = {};
+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;
-for (const [k, v] of Object.entries(JSON.parse(process.argv[2]))) {
-  if (JSON.stringify(j[key][k]) !== JSON.stringify(v)) { j[key][k] = v; changed = true; }
+// 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),
@@ -1638,6 +1716,7 @@ if (changed || original === null) {
     try { fs.unlinkSync(tmp); } catch {}
   }
 }
+for (const warning of warnings) process.stderr.write(warning);
 `.trim();
 
 /**
@@ -1646,8 +1725,8 @@ if (changed || original === null) {
  * 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 definitions and
- * malformed configs fail without being modified.
+ * 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");
@@ -1658,11 +1737,15 @@ 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");
 }
@@ -1676,7 +1759,11 @@ for (const [slug, url] of Object.entries(desired)) {
 }
 
 fs.mkdirSync(home, { recursive: true });
-const file = path.join(home, "config.toml");
+// 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");
@@ -1684,10 +1771,10 @@ try {
   if (!error || error.code !== "ENOENT") throw error;
 }
 
-function runCodex(args) {
+function runCodex(args, codexHome = sourceHome) {
   return child.spawnSync(codexBin, args, {
     encoding: "utf8",
-    env: Object.assign({}, process.env, { CODEX_HOME: home }),
+    env: Object.assign({}, process.env, { CODEX_HOME: codexHome }),
     maxBuffer: 1024 * 1024,
     timeout: 5000,
     killSignal: "SIGKILL",
@@ -1709,7 +1796,7 @@ function exactKeys(value, keys) {
 
 function managedDefinitionUrl(value, slug) {
   const topKeys = [
-    "disabled_reason", "disabled_tools", "enabled", "enabled_tools", "name",
+    "auth_status", "disabled_reason", "enabled", "name",
     "startup_timeout_sec", "tool_timeout_sec", "transport"
   ];
   const transportKeys = ["args", "command", "cwd", "env", "env_vars", "type"];
@@ -1717,8 +1804,7 @@ function managedDefinitionUrl(value, slug) {
     value.name === slug &&
     value.enabled === true &&
     value.disabled_reason === null &&
-    value.enabled_tools === null &&
-    value.disabled_tools === null &&
+    value.auth_status === "unsupported" &&
     value.startup_timeout_sec === null &&
     value.tool_timeout_sec === null &&
     exactKeys(value.transport, transportKeys) &&
@@ -1750,15 +1836,18 @@ function gatewayIdentity(value, slug) {
   } catch {
     return null;
   }
-  if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+  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) {
+  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_-]+)$/.exec(segments[1]);
-  if (!token) 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] };
 }
 
@@ -1779,12 +1868,12 @@ function escapeRegExp(value) {
 }
 
 /**
- * Replace only the URL token inside a raw block Uai can prove it authored.
+ * 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 rewriteManagedRawBlock(text, slug, oldUrl, desiredUrl) {
+function editManagedRawBlock(text, slug, oldUrl, desiredUrl) {
   const prefix =
     "(^|\\r?\\n)\\[mcp_servers\\." + escapeRegExp(slug) + "\\]\\r?\\n" +
     "command = \\\"npx\\\"\\r?\\n";
@@ -1824,64 +1913,176 @@ function rewriteManagedRawBlock(text, slug, oldUrl, desiredUrl) {
   if (matches.length !== 1) return null;
   const match = matches[0];
   const start = match.index || 0;
-  const replacement = match[0].replace(
-    JSON.stringify(oldUrl),
-    JSON.stringify(desiredUrl)
-  );
+  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);
 }
 
-function getDefinition(slug) {
-  const result = runCodex(["mcp", "get", slug, "--json"]);
+/** 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 mcp get " + slug + " failed: " + detail(result));
+    throw new Error("Codex config is invalid: " + detail(result));
   }
   let value;
   try {
     value = JSON.parse(result.stdout);
   } catch {
-    throw new Error("codex mcp get " + slug + " returned invalid JSON");
+    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;
 }
 
-// One list call validates the whole TOML document and identifies truly absent
-// servers. A malformed document therefore fails before any append.
-const listedResult = runCodex(["mcp", "list", "--json"]);
-if (listedResult.status !== 0) {
-  throw new Error("Codex config is invalid: " + detail(listedResult));
+/** 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");
+  }
 }
-let listed;
-try {
-  listed = JSON.parse(listedResult.stdout);
-} catch {
-  throw new Error("codex mcp list returned invalid JSON");
+
+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);
 }
-if (!Array.isArray(listed) ||
-    !listed.every((entry) => plainObject(entry) && typeof entry.name === "string")) {
-  throw new Error("codex mcp list returned an invalid server list");
+
+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 matches = listed.filter((entry) => entry.name === slug);
-  if (matches.length === 0) {
+  const definition = bySlug.get(slug);
+  if (definition === undefined) {
     missing.push([slug, url]);
     continue;
   }
-  if (matches.length !== 1) {
-    throw new Error("Codex MCP server " + slug + " is foreign - left unchanged");
-  }
-  const definition = getDefinition(slug);
-  if (exactDefinition(definition, slug, url)) continue;
-  const oldUrl = managedDefinitionUrl(definition, slug);
-  if (oldUrl === null || !sameTaskGateway(oldUrl, url, slug)) {
-    throw new Error("Codex MCP server " + slug + " is foreign - left unchanged");
+  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]);
 }
-if (missing.length === 0 && rewrites.length === 0) process.exit(0);
+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]) => [
@@ -1892,8 +2093,15 @@ const blocks = missing.map(([slug, url]) => [
   "",
 ].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 = rewriteManagedRawBlock(next, slug, oldUrl, desiredUrl);
+  const rewritten = editManagedRawBlock(next, slug, oldUrl, desiredUrl);
   if (rewritten === null) {
     throw new Error("Codex MCP server " + slug + " has foreign TOML text - left unchanged");
   }
@@ -1906,8 +2114,26 @@ if (blocks.length > 0) {
 }
 
 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(
-  home,
+  sourceHome,
   "." + path.basename(file) + "." + process.pid + "." +
     crypto.randomBytes(8).toString("hex") + ".tmp"
 );
@@ -1926,50 +2152,239 @@ try {
   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();
 
-// Do not memoize a syntactically bad append/rewrite as success. Codex is again
-// the authority, and every changed definition must normalize exactly.
-for (const [slug, url] of [
-  ...missing,
-  ...rewrites.map(([slug, _oldUrl, url]) => [slug, url]),
-]) {
-  if (!exactDefinition(getDefinition(slug), slug, url)) {
-    throw new Error("Codex MCP server " + slug + " failed verification");
+/** 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 full writer (including its
-// 10s lock wait and every engine-specific command) gets 25s before TERM and
-// 5s more before KILL, below the 40s host backstop.
+// 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_WRITE_TIMEOUT_S = 25;
+const MCP_CONFIG_MIN_WRITE_TIMEOUT_S = 25;
 const MCP_CONFIG_WRITE_KILL_AFTER_S = 5;
-const MCP_CONFIG_HOST_TIMEOUT_MS = 40_000;
+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 — mcp-remote shims appended once per slug to config.toml.
+ *   - Codex — reconciled mcp-remote shims in config.toml.
  *   - Cursor — ~/.cursor/mcp.json ({ url } form; the adapter passes
  *     `--approve-mcps`).
- *   - Grok — `grok mcp add -s user` into every GROK_HOME the task may use
- *     (idempotent per slug; project scope is refused in an untrusted folder).
+ *   - 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). Written only when the task has connections.
+ *     token is the auth).
  * Safe to re-run every ensure. `engineKinds` is the roster's agent kinds.
  */
 export async function setupMcpTaskConfig(
@@ -2032,74 +2447,98 @@ export async function setupMcpTaskConfig(
         oauth: false,
       };
     }
-    // Browser migration touches these same Claude/Codex files. Keep every Uai
-    // writer in one critical section so neither side can erase the other's
-    // update between a read and its replacement/append.
+    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))}`,
-      // Codex is stdio-only. Ask Codex itself to classify the TOML before
-      // atomically appending any missing mcp-remote shims.
-      ...(has("codex") && connections.length > 0
-        ? codexHomes.map(
-            (home) =>
-              `node -e ${shellQuote(ENSURE_CODEX_MCP_TOML)} ${shellQuote(home)} ${shellQuote(
-                JSON.stringify(codexEntries),
-              )}`,
-          )
-        : []),
-    ].join(" && ");
-    const writes = [
-      "mkdir -p /workspace/.claude",
-      `flock -w 10 ${MCP_CONFIG_LOCK_PATH} sh -lc ${shellQuote(lockedWrites)}`,
-      // Cursor: reads ~/.cursor/mcp.json (the adapter passes --approve-mcps).
-      ...(has("cursor") && connections.length > 0
+      )} /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)}`,
           ]
         : []),
-      // Grok: USER-scope `grok mcp add` once per GROK_HOME the task may run
-      // under (GROK_HOME redirects the user config). Project scope is refused
-      // for an untrusted folder and /workspace is no git repo (live
-      // 2026-09-08). The binary lives at ~/.grok/bin (x.ai installer); the
-      // old ~/.local/bin path failed silently behind `|| true`.
-      ...(has("grok")
-        ? grokHomes
-            .filter((home) => /^\/home\/node\/\.grok(-acct-[A-Za-z0-9_-]+)?$/.test(home))
-            .flatMap((home) =>
-              connections.map(
-                (c) =>
-                  `GROK_HOME=${home} ${GROK_BIN} mcp add ${shellQuote(c.slug)} ${shellQuote(
-                    urlFor(c.slug),
-                  )} -t http -s user >/dev/null 2>&1 || true`,
-              ),
-            )
-        : []),
+    ].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") && connections.length > 0
+      ...(has("opencode")
         ? [
             `node -e ${shellQuote(MERGE_MCP_JSON)} /home/node/.config/opencode/opencode.json ${shellQuote(
               JSON.stringify(opencodeEntries),
-            )} mcp`,
+            )} mcp opencode ${shellQuote(taskId)}`,
           ]
         : []),
     ].join(" && ");
     const steps =
       `timeout --kill-after=${MCP_CONFIG_WRITE_KILL_AFTER_S} ` +
-      `${MCP_CONFIG_WRITE_TIMEOUT_S} sh -lc ${shellQuote(writes)}`;
+      `${writeTimeoutS} sh -lc ${shellQuote(writes)}`;
     const result = environment
       ? await environment.exec({
           argv: ["sh", "-lc", steps],
           env: RUNTIME_AUTHORITY_ENV,
           projectEnvProfile: "maintenance",
-          timeoutMs: MCP_CONFIG_HOST_TIMEOUT_MS,
+          timeoutMs: hostTimeoutMs,
           maxOutputBytes: 256 * 1024,
         })
       : await taskContainerCli(
@@ -2117,19 +2556,34 @@ export async function setupMcpTaskConfig(
             "-lc",
             steps,
           ],
-          { timeoutMs: MCP_CONFIG_HOST_TIMEOUT_MS },
+          { timeoutMs: hostTimeoutMs },
         );
     const status = "exitCode" in result ? result.exitCode : result.status;
-    const stderr =
-      "stderr" in result && result.stderr instanceof Uint8Array
-        ? Buffer.from(result.stderr).toString("utf8")
-        : result.stderr;
+    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: ${stderr.slice(0, 300)}`,
+        `[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(