xmux-bridge 1.0.39 → 1.0.41

package/README.md

@@ -24,11 +24,6 @@ brew tap DwvN-Lee/xmux
 brew install xmux
 ```
 
-Homebrew owns the stable runtime under `$(brew --prefix)/opt/xmux/libexec`.
-The installed `xmux` command exports that path as `XMUX_INSTALL_DIR` and then
-execs the runtime wrapper in `libexec/bin/xmux`. Ad hoc local directories, npx
-caches, and zsh plugin directories are not part of the normal runtime path.
-
 Configure Codex integration explicitly:
 
 ```bash
@@ -36,21 +31,8 @@ xmux setup-codex
 xmux doctor-codex
 ```
 
-Homebrew installs the XMux CLI/runtime only. `xmux setup-codex` is the command
-that mutates `~/.codex`: it registers the `xmux_lead` MCP server through the
-versioned npm package, points that MCP runtime back at Homebrew with
-`XMUX_INSTALL_DIR`, adds the installed `xmux` path to Codex shell policy,
-installs the scoped XMux command rule, and refreshes available XMux skills
-under `~/.codex/skills`. Runtime-only installs do not include skill source
-files, so pass an external skill source when refreshing skills:
-
-```bash
-xmux setup-codex --skills-dir /path/to/xmux-skills
-```
-
-`XMUX_CODEX_SKILLS_DIR` provides the same source path for automation. Without
-`--skills-dir` or `XMUX_CODEX_SKILLS_DIR`, `setup-codex` skips skill refresh
-and leaves existing user-owned skills untouched.
+`xmux setup-codex` registers XMux with Codex, and `xmux doctor-codex` checks
+that the integration is ready.
 
 Start the Codex lead from the target project directory:
 
@@ -148,7 +130,7 @@ Runtime state is project-local:
 Runtime path environment names are now split by responsibility:
 
 ```text
-XMUX_INSTALL_DIR  # XMux source/install directory
+XMUX_INSTALL_DIR  # XMux install root
 XMUX_PROJECT_DIR  # project root where Codex is working
 XMUX_STATE_DIR    # project-local runtime state, usually $XMUX_PROJECT_DIR/.codex/xmux
 ```
@@ -156,35 +138,25 @@ XMUX_STATE_DIR    # project-local runtime state, usually $XMUX_PROJECT_DIR/.code
 Codex uses the normal user runtime under `~/.codex`. XMux does not create an
 isolated Codex home for a team, and Codex teammate mode is unsupported.
 
-Agent automation uses `xmux` from the Codex shell policy PATH that
-`xmux setup-codex` writes to `~/.codex/config.toml`. If that wrapper is
-unavailable, it falls back to the explicit XMux executable. The user-facing
-bootstrap command remains `xmux -n <session>` after setup; ad hoc local paths
-and shell-loading details are not part of the agent contract.
+Agent automation uses the installed `xmux` command that `xmux setup-codex`
+makes available to Codex. The user-facing bootstrap command remains
+`xmux -n <session>` after setup.
 
 The Codex lead MCP server is `xmux_lead`. `xmux setup-codex` configures it so
 Codex can route requests, wait for teammate responses, read events, and inspect
 team status.
-The global MCP config is install-scoped: the MCP command is a versioned npm
-entrypoint, while `XMUX_INSTALL_DIR` points at the Homebrew runtime that owns
-wrapper scripts, state discovery, and lifecycle. It does not pin
-`XMUX_PROJECT_DIR`/`XMUX_STATE_DIR`; those values come from the active
-`xmux -n <session>` lead runtime.
-
-Provider teammates write responses through `bridge-mcp-server.js`, using the
-team runtime environment prepared by XMux. The bridge and mailbox paths are
+The installed `xmux` command owns the tmux runtime. The `xmux_lead` MCP server
+is delivered as a versioned npm entrypoint, and Codex skills are optional
+shortcuts for orchestrating that runtime. The MCP command is install-scoped and
+does not pin `XMUX_PROJECT_DIR`/`XMUX_STATE_DIR`; those values come from the
+active `xmux -n <session>` lead runtime.
+
+Provider teammates write responses through `mcp/servers/bridge.js`, using the
+team runtime environment prepared by XMux. The MCP and mailbox paths are
 implementation details behind Codex-led teammate orchestration.
 
-The explicit Codex setup installs available XMux skills under
-`~/.codex/skills` only from `--skills-dir` or `XMUX_CODEX_SKILLS_DIR`.
-Homebrew does not install Codex skills or repo-local plugin files; normal
-runtime operation depends on the installed `xmux` command and
-`XMUX_INSTALL_DIR`, not a checkout path.
-
-The plugin skill source of truth is `plugins/xmux/skills`; the top-level
-`skills/` directory is a mirrored distribution copy for explicit skill refresh
-workflows. Users explicitly invoke Codex skills with `$`, for example
-`$xmux-teams`. The official XMux skills cover agent-facing orchestration flows:
+Users can ask for teammate work in natural language. When XMux skills are
+available in Codex, the official skill shortcuts are:
 
 ```text
 $xmux-teams
@@ -195,24 +167,14 @@ $xmux-diagnosis
 $xmux-send-pane
 ```
 
-Development verification for agent/runtime changes:
-
-```bash
-pytest tests -q
-zsh -n xmux.zsh
-zsh -n xmux-bridge.zsh
-node --check scripts/setup_xmux_codex_mcp.js
-git diff --check
-```
-
-Formula draft and distribution notes live in
-[Homebrew distribution](docs/operations/homebrew.md).
+Homebrew installation details live in [Homebrew installation](docs/operations/homebrew.md).
 
 ## Docs
 
 - [Documentation index](docs/README.md)
+- [Repository layout](docs/runtime/repository-layout.md)
 - [Codex lead runtime](docs/runtime/codex-lead.md)
-- [Homebrew distribution](docs/operations/homebrew.md)
+- [Homebrew installation](docs/operations/homebrew.md)
 - [Wrapper-first debugging](docs/operations/debugging.md)
 - [Claude teammate](docs/teammates/claude.md)
 - [Gemini teammate](docs/teammates/gemini.md)

package/{bridge-mcp-server.js → mcp/servers/bridge.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * bridge-mcp-server.js
+ * mcp/servers/bridge.js
  * Minimal MCP server for xmux.
  * Exposes write_to_lead(text, summary?) so Claude, Gemini, and Copilot
  * teammates can write directly to the XMux lead inbox.
@@ -140,7 +140,11 @@ function trimToCap(msgs, cap) {
 function mailboxInstallBases() {
   const seen = new Set();
   const bases = [];
-  for (const candidate of [XMUX_INSTALL_DIR, __dirname]) {
+  const packageRoot = path.basename(__dirname) === 'servers'
+    && path.basename(path.dirname(__dirname)) === 'mcp'
+    ? path.dirname(path.dirname(__dirname))
+    : __dirname;
+  for (const candidate of [XMUX_INSTALL_DIR, packageRoot, __dirname]) {
     if (!candidate) continue;
     const resolved = path.resolve(candidate);
     if (seen.has(resolved)) continue;
@@ -305,36 +309,99 @@ function buildResponse(msg) {
 
 // ── STDIO mode ────────────────────────────────────────────────────────────────
 // CRITICAL: register stdin listener FIRST to avoid race condition.
-// Provider CLIs send `initialize` immediately after spawn; if readline isn't
+// Provider CLIs send `initialize` immediately after spawn; if stdin isn't
 // listening yet the message is lost and the CLI times out (Tools: none).
 
+function writeMcpResponse(resp, framed) {
+  const body = JSON.stringify(resp);
+  if (framed) {
+    process.stdout.write(`Content-Length: ${Buffer.byteLength(body, 'utf8')}\r\n\r\n${body}`);
+  } else {
+    process.stdout.write(body + '\n');
+  }
+}
+
+function handleStdioMessage(msg, framed) {
+  const resp = buildResponse(msg);
+  if (resp) writeMcpResponse(resp, framed);
+}
+
 function startStdio() {
-  const readline = require('readline');
-  const messageQueue = [];
-  let ready = false;
+  let buffer = Buffer.alloc(0);
+
+  function parseContentLengthHeader(header) {
+    for (const line of header.split(/\r?\n/)) {
+      const match = line.match(/^Content-Length:\s*(\d+)\s*$/i);
+      if (match) return Number.parseInt(match[1], 10);
+    }
+    return null;
+  }
 
-  const rl = readline.createInterface({ input: process.stdin, terminal: false });
-  rl.on('line', (line) => {
-    if (!line.trim()) return;
+  function handleJsonPayload(payload, framed) {
+    if (!payload.trim()) return;
     let msg;
-    try { msg = JSON.parse(line); } catch (_) { return; }
-    if (ready) {
-      const resp = buildResponse(msg);
-      if (resp) process.stdout.write(JSON.stringify(resp) + '\n');
-    } else {
-      messageQueue.push(msg);
+    try {
+      msg = JSON.parse(payload);
+    } catch (_) {
+      return;
     }
+    handleStdioMessage(msg, framed);
+  }
+
+  function drain(flush = false) {
+    while (buffer.length) {
+      while (buffer[0] === 0x0a || buffer[0] === 0x0d) buffer = buffer.subarray(1);
+      if (!buffer.length) return;
+
+      const text = buffer.toString('utf8');
+      if (text.toLowerCase().startsWith('content-length:')) {
+        let headerEnd = text.indexOf('\r\n\r\n');
+        let separatorLength = 4;
+        if (headerEnd === -1) {
+          headerEnd = text.indexOf('\n\n');
+          separatorLength = 2;
+        }
+        if (headerEnd === -1) return;
+
+        const header = text.slice(0, headerEnd);
+        const contentLength = parseContentLengthHeader(header);
+        if (!Number.isFinite(contentLength) || contentLength < 0) {
+          buffer = Buffer.alloc(0);
+          return;
+        }
+
+        const bodyStart = Buffer.byteLength(text.slice(0, headerEnd + separatorLength), 'utf8');
+        if (buffer.length < bodyStart + contentLength) return;
+        const body = buffer.subarray(bodyStart, bodyStart + contentLength).toString('utf8');
+        buffer = buffer.subarray(bodyStart + contentLength);
+        handleJsonPayload(body, true);
+        continue;
+      }
+
+      const newline = buffer.indexOf(0x0a);
+      if (newline === -1) {
+        if (!flush) return;
+        const line = buffer.toString('utf8');
+        buffer = Buffer.alloc(0);
+        handleJsonPayload(line, false);
+        return;
+      }
+      const line = buffer.subarray(0, newline).toString('utf8');
+      buffer = buffer.subarray(newline + 1);
+      handleJsonPayload(line, false);
+    }
+  }
+
+  process.stdin.on('data', (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    drain(false);
   });
   // Parent CLI closed stdin → exit so MCP subprocess does not linger and
   // continue accepting writes after its intended session is over.
-  rl.on('close', () => process.exit(0));
-
-  ready = true;
-  for (const msg of messageQueue) {
-    const resp = buildResponse(msg);
-    if (resp) process.stdout.write(JSON.stringify(resp) + '\n');
-  }
-  messageQueue.length = 0;
+  process.stdin.on('end', () => {
+    drain(true);
+    process.exit(0);
+  });
 }
 
 // ── HTTP/SSE mode ─────────────────────────────────────────────────────────────

package/{xmux-lead-mcp-server.js → mcp/servers/lead.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * xmux-lead-mcp-server.js
+ * mcp/servers/lead.js
  * Stdio-only MCP server exposing XMux lead/team mailbox tools.
  *
  * Mailbox persistence is delegated to the Node mailbox CLI.
@@ -138,7 +138,11 @@ function parseJsonOutput(stdout) {
 function mailboxInstallBases() {
   const seen = new Set();
   const bases = [];
-  for (const candidate of [XMUX_INSTALL_DIR, __dirname]) {
+  const packageRoot = path.basename(__dirname) === 'servers'
+    && path.basename(path.dirname(__dirname)) === 'mcp'
+    ? path.dirname(path.dirname(__dirname))
+    : __dirname;
+  for (const candidate of [XMUX_INSTALL_DIR, packageRoot, __dirname]) {
     if (!candidate) continue;
     const resolved = path.resolve(candidate);
     if (seen.has(resolved)) continue;
@@ -451,36 +455,94 @@ function buildResponse(msg) {
   return null;
 }
 
+function writeMcpResponse(resp, framed) {
+  const body = JSON.stringify(resp);
+  if (framed) {
+    process.stdout.write(`Content-Length: ${Buffer.byteLength(body, 'utf8')}\r\n\r\n${body}`);
+  } else {
+    process.stdout.write(body + '\n');
+  }
+}
+
+function handleStdioMessage(msg, framed) {
+  const resp = buildResponse(msg);
+  if (resp) writeMcpResponse(resp, framed);
+}
+
 function startStdio() {
-  const readline = require('readline');
-  const messageQueue = [];
-  let ready = false;
+  let buffer = Buffer.alloc(0);
 
-  const rl = readline.createInterface({ input: process.stdin, terminal: false });
-  rl.on('line', (line) => {
-    if (!line.trim()) return;
+  function parseContentLengthHeader(header) {
+    for (const line of header.split(/\r?\n/)) {
+      const match = line.match(/^Content-Length:\s*(\d+)\s*$/i);
+      if (match) return Number.parseInt(match[1], 10);
+    }
+    return null;
+  }
+
+  function handleJsonPayload(payload, framed) {
+    if (!payload.trim()) return;
     let msg;
     try {
-      msg = JSON.parse(line);
+      msg = JSON.parse(payload);
     } catch (_) {
       return;
     }
+    handleStdioMessage(msg, framed);
+  }
 
-    if (ready) {
-      const resp = buildResponse(msg);
-      if (resp) process.stdout.write(JSON.stringify(resp) + '\n');
-    } else {
-      messageQueue.push(msg);
+  function drain(flush = false) {
+    while (buffer.length) {
+      while (buffer[0] === 0x0a || buffer[0] === 0x0d) buffer = buffer.subarray(1);
+      if (!buffer.length) return;
+
+      const text = buffer.toString('utf8');
+      if (text.toLowerCase().startsWith('content-length:')) {
+        let headerEnd = text.indexOf('\r\n\r\n');
+        let separatorLength = 4;
+        if (headerEnd === -1) {
+          headerEnd = text.indexOf('\n\n');
+          separatorLength = 2;
+        }
+        if (headerEnd === -1) return;
+
+        const header = text.slice(0, headerEnd);
+        const contentLength = parseContentLengthHeader(header);
+        if (!Number.isFinite(contentLength) || contentLength < 0) {
+          buffer = Buffer.alloc(0);
+          return;
+        }
+
+        const bodyStart = Buffer.byteLength(text.slice(0, headerEnd + separatorLength), 'utf8');
+        if (buffer.length < bodyStart + contentLength) return;
+        const body = buffer.subarray(bodyStart, bodyStart + contentLength).toString('utf8');
+        buffer = buffer.subarray(bodyStart + contentLength);
+        handleJsonPayload(body, true);
+        continue;
+      }
+
+      const newline = buffer.indexOf(0x0a);
+      if (newline === -1) {
+        if (!flush) return;
+        const line = buffer.toString('utf8');
+        buffer = Buffer.alloc(0);
+        handleJsonPayload(line, false);
+        return;
+      }
+      const line = buffer.subarray(0, newline).toString('utf8');
+      buffer = buffer.subarray(newline + 1);
+      handleJsonPayload(line, false);
     }
-  });
-  rl.on('close', () => process.exit(0));
-
-  ready = true;
-  for (const msg of messageQueue) {
-    const resp = buildResponse(msg);
-    if (resp) process.stdout.write(JSON.stringify(resp) + '\n');
   }
-  messageQueue.length = 0;
+
+  process.stdin.on('data', (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    drain(false);
+  });
+  process.stdin.on('end', () => {
+    drain(true);
+    process.exit(0);
+  });
 }
 
 startStdio();

package/{scripts/setup_claude_mcp.js → mcp/setup/claude.js}

@@ -28,7 +28,7 @@ function stableHomebrewXmuxInstallDir(installDir) {
 
   const prefix = resolved.split(marker, 1)[0];
   const candidate = path.join(prefix, "opt", "xmux", "libexec");
-  if (fs.existsSync(path.join(candidate, "xmux.zsh"))) {
+  if (fs.existsSync(path.join(candidate, "runtime", "shell", "xmux.zsh")) || fs.existsSync(path.join(candidate, "xmux.zsh"))) {
     return candidate;
   }
   return resolved;
@@ -36,13 +36,14 @@ function stableHomebrewXmuxInstallDir(installDir) {
 
 function stableHomebrewXmuxFilePath(filePath) {
   const resolved = absolute(filePath);
-  const installDir = path.dirname(resolved);
-  const stableInstallDir = stableHomebrewXmuxInstallDir(installDir);
-  if (stableInstallDir === installDir) {
-    return resolved;
-  }
-
-  const candidate = path.join(stableInstallDir, path.basename(resolved));
+  const marker = `${path.sep}Cellar${path.sep}xmux${path.sep}`;
+  const libexecSegment = `${path.sep}libexec${path.sep}`;
+  const libexecIndex = resolved.indexOf(libexecSegment);
+  if (!resolved.includes(marker) || libexecIndex < 0) return resolved;
+  const prefix = resolved.split(marker, 1)[0];
+  const optDir = path.join(prefix, "opt", "xmux", "libexec");
+  const relativePath = resolved.slice(libexecIndex + libexecSegment.length);
+  const candidate = path.join(optDir, relativePath);
   if (fs.existsSync(candidate)) {
     return candidate;
   }
@@ -72,7 +73,7 @@ function atomicWriteJson(filePath, data) {
 
 function usage() {
   process.stderr.write(
-    "usage: setup_claude_mcp.js <bridge_js> <project_dir> <outbox> <agent> <team> <state_dir> <install_dir>\n",
+    "usage: claude.js <bridge_js> <project_dir> <outbox> <agent> <team> <state_dir> <install_dir>\n",
   );
 }
 

package/{scripts/setup_xmux_codex_mcp.js → mcp/setup/codex.js}

@@ -19,6 +19,7 @@ const LOCAL_PLUGIN_CACHE_VERSION = "local";
 const SKILL_MARKER = ".xmux-managed-skill";
 const DEFAULT_MCP_PACKAGE = "xmux-bridge";
 const DEFAULT_MCP_BIN = "xmux-lead-mcp";
+const DEFAULT_MCP_NPX_PREFIX = path.join(".cache", "xmux", "npm-prefix");
 
 function expandUser(value) {
   const text = String(value || "");
@@ -31,26 +32,39 @@ function abs(value) {
   return path.resolve(expandUser(value));
 }
 
+function xmux_runtime_shell_path(installDir) {
+  return path.join(abs(installDir), "runtime", "shell", "xmux.zsh");
+}
+
+function has_xmux_runtime(installDir) {
+  const root = abs(installDir);
+  return fs.existsSync(xmux_runtime_shell_path(root)) || fs.existsSync(path.join(root, "xmux.zsh"));
+}
+
 function stable_homebrew_xmux_install_dir(xmuxInstallDir) {
   const installDir = abs(xmuxInstallDir);
   const marker = `${path.sep}Cellar${path.sep}xmux${path.sep}`;
   if (!installDir.includes(marker) || !installDir.endsWith(`${path.sep}libexec`)) {
     return installDir;
   }
-  if (!fs.existsSync(path.join(installDir, "xmux.zsh"))) {
+  if (!has_xmux_runtime(installDir)) {
     return installDir;
   }
   const prefix = installDir.split(marker, 1)[0];
   const candidate = path.join(prefix, "opt", "xmux", "libexec");
-  return fs.existsSync(path.join(candidate, "xmux.zsh")) ? candidate : installDir;
+  return has_xmux_runtime(candidate) ? candidate : installDir;
 }
 
 function stable_homebrew_xmux_file_path(inputPath) {
   const resolved = abs(inputPath);
-  const installDir = path.dirname(resolved);
-  const stableInstallDir = stable_homebrew_xmux_install_dir(installDir);
-  if (stableInstallDir === installDir) return resolved;
-  const candidate = path.join(stableInstallDir, path.basename(resolved));
+  const marker = `${path.sep}Cellar${path.sep}xmux${path.sep}`;
+  const libexecSegment = `${path.sep}libexec${path.sep}`;
+  const libexecIndex = resolved.indexOf(libexecSegment);
+  if (!resolved.includes(marker) || libexecIndex < 0) return resolved;
+  const prefix = resolved.split(marker, 1)[0];
+  const optDir = path.join(prefix, "opt", "xmux", "libexec");
+  const relativePath = resolved.slice(libexecIndex + libexecSegment.length);
+  const candidate = path.join(optDir, relativePath);
   return fs.existsSync(candidate) ? candidate : resolved;
 }
 
@@ -138,14 +152,15 @@ function package_spec_has_version(packageSpec) {
 }
 
 function xmux_version_from_install_dir(xmuxInstallDir) {
-  const content = read_text(path.join(abs(xmuxInstallDir), "xmux.zsh"));
+  const root = abs(xmuxInstallDir);
+  const content = read_text(xmux_runtime_shell_path(root)) || read_text(path.join(root, "xmux.zsh"));
   const match = content.match(/^XMUX_VERSION=["']([^"']+)["']/m);
   return match ? match[1] : "";
 }
 
 function default_mcp_package_spec(xmuxInstallDir, packageName = "", packageVersion = "") {
   const installPackage = read_json(path.join(abs(xmuxInstallDir), "package.json")) || {};
-  const scriptPackage = read_json(path.join(path.dirname(path.dirname(abs(__filename))), "package.json")) || {};
+  const scriptPackage = read_json(path.join(path.dirname(path.dirname(path.dirname(abs(__filename)))), "package.json")) || {};
   const name = packageName
     || process.env.XMUX_MCP_NPM_PACKAGE
     || installPackage.name
@@ -172,21 +187,33 @@ function node_mcp_config(serverPath) {
   };
 }
 
-function npx_mcp_config(packageSpec, binName = DEFAULT_MCP_BIN) {
+function default_mcp_npx_prefix(configPath = "") {
+  const fallback = path.join(os.homedir(), DEFAULT_MCP_NPX_PREFIX);
+  if (!configPath) return fallback;
+  const configDir = path.dirname(abs(configPath));
+  if (path.basename(configDir) === ".codex") {
+    return path.join(path.dirname(configDir), DEFAULT_MCP_NPX_PREFIX);
+  }
+  return path.join(configDir, DEFAULT_MCP_NPX_PREFIX);
+}
+
+function npx_mcp_config(packageSpec, binName = DEFAULT_MCP_BIN, npxPrefix = "") {
+  const prefix = abs(npxPrefix || process.env.XMUX_MCP_NPX_PREFIX || default_mcp_npx_prefix());
   return {
     mode: "npx",
     command: "npx",
-    args: ["-y", "-p", packageSpec, binName],
+    args: ["--prefix", prefix, "-y", "-p", packageSpec, binName],
     package_spec: packageSpec,
     bin: binName,
-    label: `npx -y -p ${packageSpec} ${binName}`,
+    npx_prefix: prefix,
+    label: `npx --prefix ${prefix} -y -p ${packageSpec} ${binName}`,
   };
 }
 
 function resolve_mcp_config(xmuxInstallDir, opts = {}) {
   if (opts.server_path) return node_mcp_config(opts.server_path);
   const packageSpec = default_mcp_package_spec(xmuxInstallDir, opts.mcp_package, opts.mcp_version);
-  return npx_mcp_config(packageSpec, opts.mcp_bin || DEFAULT_MCP_BIN);
+  return npx_mcp_config(packageSpec, opts.mcp_bin || DEFAULT_MCP_BIN, opts.mcp_npx_prefix || "");
 }
 
 function normalize_mcp_config(mcpConfigOrServerPath, xmuxInstallDir = "", opts = {}) {
@@ -198,6 +225,7 @@ function normalize_mcp_config(mcpConfigOrServerPath, xmuxInstallDir = "", opts =
       server_path: mcpConfigOrServerPath.server_path || "",
       package_spec: mcpConfigOrServerPath.package_spec || "",
       bin: mcpConfigOrServerPath.bin || "",
+      npx_prefix: mcpConfigOrServerPath.npx_prefix || "",
       label: mcpConfigOrServerPath.label || [
         mcpConfigOrServerPath.command,
         ...(mcpConfigOrServerPath.args || []),
@@ -212,6 +240,12 @@ function mcp_args_toml(mcpConfig) {
   return `args = [${mcpConfig.args.map(toml_quote).join(", ")}]`;
 }
 
+function ensure_mcp_runtime_dirs(mcpConfig) {
+  if (mcpConfig.mode === "npx" && mcpConfig.npx_prefix) {
+    fs.mkdirSync(mcpConfig.npx_prefix, { recursive: true });
+  }
+}
+
 function build_block(mcpConfigOrServerPath, xmuxInstallDir) {
   const mcpConfig = normalize_mcp_config(mcpConfigOrServerPath, xmuxInstallDir);
   const pathEnv = resolve_path_with_node();
@@ -252,7 +286,7 @@ function is_xmux_runtime_bin_path(candidatePath, currentXmuxBin) {
   if (expanded === abs(currentXmuxBin)) return true;
   if (path.basename(expanded) !== "bin") return false;
   const installDir = path.dirname(expanded);
-  if (fs.existsSync(path.join(installDir, "xmux.zsh")) && fs.existsSync(path.join(expanded, "xmux"))) {
+  if (has_xmux_runtime(installDir) && fs.existsSync(path.join(expanded, "xmux"))) {
     return true;
   }
   if (path.basename(installDir) !== "libexec") return false;
@@ -399,7 +433,7 @@ function install_xmux_command_rule(configPath) {
   let content = remove_marker_block(read_text(filePath), RULE_BEGIN, RULE_END);
   const block = [
     RULE_BEGIN,
-    "# Allow the scoped XMux wrapper command; XMux skills still control operation scope.",
+    "# Allow the scoped XMux wrapper command; user intent and XMux wrappers control operation scope.",
     'prefix_rule(pattern=["xmux"], decision="allow")',
     RULE_END,
   ].join("\n");
@@ -548,12 +582,12 @@ function _xmux_lead_mcp_processes_from_ps(psOutput) {
   const processes = [];
   for (const rawLine of String(psOutput || "").split(/\r?\n/)) {
     const stripped = rawLine.trim();
-    if (!stripped.includes("xmux-lead-mcp-server.js")) continue;
+    if (!stripped.includes("mcp/servers/lead.js") && !stripped.includes("xmux-lead-mcp-server.js")) continue;
     const match = stripped.match(/^(\d+)\s+(.*)$/);
     if (!match) continue;
     const [, pid, command] = match;
     const tokens = splitShellWords(command.trim());
-    const serverPath = tokens.find((token) => token.endsWith("xmux-lead-mcp-server.js")) || "";
+    const serverPath = tokens.find((token) => token.endsWith("mcp/servers/lead.js") || token.endsWith("xmux-lead-mcp-server.js")) || "";
     if (!serverPath) continue;
     processes.push({ pid, command: command.trim(), server_path: abs(serverPath) });
   }
@@ -571,7 +605,7 @@ function running_xmux_lead_mcp_processes() {
 
 function _is_homebrew_xmux_mcp_server(serverPath) {
   const normalized = abs(serverPath);
-  return normalized.endsWith("xmux-lead-mcp-server.js")
+  return (normalized.endsWith(`${path.sep}mcp${path.sep}servers${path.sep}lead.js`) || normalized.endsWith("xmux-lead-mcp-server.js"))
     && normalized.includes(`${path.sep}Cellar${path.sep}xmux${path.sep}`)
     && normalized.includes(`${path.sep}libexec${path.sep}`);
 }
@@ -616,7 +650,7 @@ function doctor_codex(configPath, xmuxInstallDir, mcpConfigOrServerPath, skillsD
   } else if (installedNames.size) {
     notes.push(["OK", `XMux Codex skills installed under ${skills_root(configPath)}`]);
   } else {
-    notes.push(["WARN", "no XMux skill source directory found; pass --skills-dir or set XMUX_CODEX_SKILLS_DIR"]);
+    notes.push(["OK", "optional XMux skills are not configured"]);
   }
 
   if (fs.existsSync(plugin_cache_path(configPath))) {
@@ -665,6 +699,7 @@ function parse_args(argv) {
     mcp_package: "",
     mcp_version: "",
     mcp_bin: DEFAULT_MCP_BIN,
+    mcp_npx_prefix: "",
   };
   for (let i = 0; i < argv.length;) {
     const arg = argv[i];
@@ -687,6 +722,7 @@ function parse_args(argv) {
       "--mcp-package",
       "--mcp-version",
       "--mcp-bin",
+      "--mcp-npx-prefix",
     ].includes(arg) && i + 1 < argv.length) {
       const key = arg.slice(2).replace(/-/g, "_");
       opts[key] = expandUser(argv[i + 1]);
@@ -725,7 +761,8 @@ function resolve_config_path(opts) {
 function main(argv = process.argv.slice(2)) {
   const opts = parse_args(argv);
   const configPath = resolve_config_path(opts);
-  const scriptInstallDir = path.dirname(path.dirname(abs(__filename)));
+  opts.mcp_npx_prefix = abs(opts.mcp_npx_prefix || process.env.XMUX_MCP_NPX_PREFIX || default_mcp_npx_prefix(configPath));
+  const scriptInstallDir = path.dirname(path.dirname(path.dirname(abs(__filename))));
   const rawInstallDir = abs(opts.xmux_install_dir || scriptInstallDir);
   const xmuxInstallDir = stable_homebrew_xmux_install_dir(rawInstallDir);
   const xmuxProjectDir = abs(opts.xmux_project_dir || default_xmux_project_dir());
@@ -736,6 +773,8 @@ function main(argv = process.argv.slice(2)) {
     return doctor_codex(configPath, xmuxInstallDir, mcpConfig, opts.skills_dir, opts.quiet);
   }
 
+  ensure_mcp_runtime_dirs(mcpConfig);
+
   let content = remove_xmux_blocks(read_text(configPath));
   if (opts.remove) {
     content = remove_codex_shell_environment(content, xmuxInstallDir);
@@ -770,7 +809,9 @@ function main(argv = process.argv.slice(2)) {
   console.log("     xmux_project_dir: inherited from xmux-launched Codex runtime");
   console.log("     xmux_state_dir: inherited from xmux-launched Codex runtime");
   if (installedSkills.length) console.log(`     skills: ${installedSkills.join(", ")}`);
-  else if (opts.install_skills) console.log("     skills: skipped; pass --skills-dir or set XMUX_CODEX_SKILLS_DIR");
+  else if (opts.install_skills && (opts.skills_dir || process.env.XMUX_CODEX_SKILLS_DIR)) {
+    console.log("     skills: no importable XMux skills found");
+  }
   console.log("     plugin_cache: disabled; stale XMux plugin cache removed if present");
   return 0;
 }
@@ -788,6 +829,7 @@ module.exports = {
   remove_xmux_blocks,
   build_block,
   default_mcp_package_spec,
+  default_mcp_npx_prefix,
   resolve_mcp_config,
   path_with_xmux_bin,
   ensure_codex_shell_environment,