dominus-cli 2.2.0 → 2.2.1

package/dist/mcp.js

@@ -1,20 +1,21 @@
 #!/usr/bin/env node
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import fs3 from 'fs';
-import path3 from 'path';
+import fs4 from 'fs';
+import path4 from 'path';
 import os from 'os';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
 import { EventEmitter } from 'events';
-import { WebSocket, WebSocketServer } from 'ws';
+import { WebSocket } from 'ws';
 import { nanoid } from 'nanoid';
 import { z } from 'zod';
 import * as crypto from 'crypto';
-import { randomUUID } from 'crypto';
 
-var DOMINUS_DIR = path3.join(os.homedir(), ".dominus");
-var CONFIG_PATH = path3.join(DOMINUS_DIR, "config.json");
-path3.join(DOMINUS_DIR, "dominus.db");
-path3.join(DOMINUS_DIR, "rules.json");
+var DOMINUS_DIR = path4.join(os.homedir(), ".dominus");
+var CONFIG_PATH = path4.join(DOMINUS_DIR, "config.json");
+path4.join(DOMINUS_DIR, "dominus.db");
+path4.join(DOMINUS_DIR, "rules.json");
 var DEFAULTS = {
   provider: "openai",
   apiBaseUrl: "",
@@ -28,14 +29,14 @@ var DEFAULTS = {
   userName: "Developer"
 };
 function ensureDir() {
-  if (!fs3.existsSync(DOMINUS_DIR)) {
-    fs3.mkdirSync(DOMINUS_DIR, { recursive: true });
+  if (!fs4.existsSync(DOMINUS_DIR)) {
+    fs4.mkdirSync(DOMINUS_DIR, { recursive: true });
   }
 }
 function readJson(filePath, defaults) {
   try {
-    if (fs3.existsSync(filePath)) {
-      const raw = fs3.readFileSync(filePath, "utf-8");
+    if (fs4.existsSync(filePath)) {
+      const raw = fs4.readFileSync(filePath, "utf-8");
       return { ...defaults, ...JSON.parse(raw) };
     }
   } catch {
@@ -144,27 +145,21 @@ var wsMessageSchema = z.object({
 }).strict();
 var TOKEN_FILE = "bridge-token";
 function loadOrCreateBridgeToken() {
-  const tokenPath = path3.join(getDominusDir(), TOKEN_FILE);
+  const tokenPath = path4.join(getDominusDir(), TOKEN_FILE);
   try {
-    const existing = fs3.readFileSync(tokenPath, "utf8").trim();
+    const existing = fs4.readFileSync(tokenPath, "utf8").trim();
     if (existing.length >= 32) return existing;
   } catch {
   }
   const token = crypto.randomBytes(32).toString("base64url");
-  fs3.writeFileSync(tokenPath, `${token}
+  fs4.writeFileSync(tokenPath, `${token}
 `, { encoding: "utf8", mode: 384 });
   try {
-    fs3.chmodSync(tokenPath, 384);
+    fs4.chmodSync(tokenPath, 384);
   } catch {
   }
   return token;
 }
-function tokensEqual(actual, expected) {
-  if (typeof actual !== "string") return false;
-  const actualBuffer = Buffer.from(actual);
-  const expectedBuffer = Buffer.from(expected);
-  return actualBuffer.length === expectedBuffer.length && crypto.timingSafeEqual(actualBuffer, expectedBuffer);
-}
 
 // src/transport/ws-client.ts
 var DominusClient = class extends EventEmitter {
@@ -197,10 +192,14 @@ var DominusClient = class extends EventEmitter {
       }, this.connectTimeoutMs);
       ws.on("open", () => {
         this.ws = ws;
-        ws.send(serializeMessage(createMessage(ControllerMsg.HELLO, {
-          protocolVersion: DOMINUS_PROTOCOL_VERSION,
-          token: this.token
-        })));
+        ws.send(
+          serializeMessage(
+            createMessage(ControllerMsg.HELLO, {
+              protocolVersion: DOMINUS_PROTOCOL_VERSION,
+              token: this.token
+            })
+          )
+        );
       });
       ws.on("message", (raw) => {
         try {
@@ -341,7 +340,11 @@ var DominusClient = class extends EventEmitter {
   sendRequest(type, payload, timeoutMs = 15e3) {
     const target = this.resolveTargetInfo();
     if (!target || !this.activeConnectionId) {
-      return Promise.reject(new Error(this.connections.size > 1 ? "Multiple Studio sessions are connected. Call dominus_select_studio first." : "No authenticated Roblox Studio connection"));
+      return Promise.reject(
+        new Error(
+          this.connections.size > 1 ? "Multiple Studio sessions are connected. Call dominus_select_studio first." : "No authenticated Roblox Studio connection"
+        )
+      );
     }
     const request = createMessage(type, payload);
     const relay = createMessage(ControllerMsg.RELAY, {
@@ -370,10 +373,12 @@ var DominusClient = class extends EventEmitter {
   sendNotification(type, payload) {
     if (!this.activeConnectionId) return;
     const request = createMessage(type, payload);
-    this.sendMessage(createMessage(ControllerMsg.RELAY, {
-      connectionId: this.activeConnectionId,
-      request
-    }));
+    this.sendMessage(
+      createMessage(ControllerMsg.RELAY, {
+        connectionId: this.activeConnectionId,
+        request
+      })
+    );
   }
   isConnected() {
     return this.resolveTargetInfo() !== null;
@@ -412,9 +417,13 @@ var DominusClient = class extends EventEmitter {
       void this.setActiveConnectionId(null);
       return;
     }
-    const matches = [...this.connections.values()].filter((connection) => connection.placeId === placeId);
+    const matches = [...this.connections.values()].filter(
+      (connection) => connection.placeId === placeId
+    );
     if (matches.length !== 1) {
-      throw new Error(matches.length === 0 ? `Place ${placeId} is not connected` : `Place ${placeId} has multiple Studio sessions; select a connectionId instead`);
+      throw new Error(
+        matches.length === 0 ? `Place ${placeId} is not connected` : `Place ${placeId} has multiple Studio sessions; select a connectionId instead`
+      );
     }
     void this.setActiveConnectionId(matches[0].connectionId);
   }
@@ -475,413 +484,74 @@ async function isPortInUse(port) {
     });
   });
 }
-var HANDSHAKE_TIMEOUT_MS = 8e3;
-var RATE_WINDOW_MS = 1e4;
-var RATE_LIMIT = 250;
-var DominusServer = class extends EventEmitter {
-  wss = null;
-  studioClients = /* @__PURE__ */ new Map();
-  wsToConnectionId = /* @__PURE__ */ new Map();
-  controllers = /* @__PURE__ */ new Set();
-  socketRoles = /* @__PURE__ */ new Map();
-  pendingRequests = /* @__PURE__ */ new Map();
-  relayRequests = /* @__PURE__ */ new Map();
-  rateState = /* @__PURE__ */ new Map();
-  token;
-  host;
-  maxPayloadBytes;
-  handshakeTimeoutMs;
-  activeConnectionId = null;
-  port;
-  constructor(port = 18088, options = {}) {
-    super();
-    this.port = port;
-    this.token = options.token ?? loadOrCreateBridgeToken();
-    this.host = options.host ?? "127.0.0.1";
-    this.maxPayloadBytes = options.maxPayloadBytes ?? MAX_MESSAGE_BYTES;
-    this.handshakeTimeoutMs = options.handshakeTimeoutMs ?? HANDSHAKE_TIMEOUT_MS;
-  }
-  start(maxRetries = 0) {
-    return new Promise((resolve, reject) => {
-      const tryPort = (port, attempt) => {
-        const wss = new WebSocketServer({
-          port,
-          host: this.host,
-          maxPayload: this.maxPayloadBytes,
-          perMessageDeflate: false
-        });
-        wss.on("listening", () => {
-          this.wss = wss;
-          this.port = port;
-          wss.on("connection", (ws) => this.handleConnection(ws));
-          this.emit("server:started", { port, host: this.host });
-          resolve();
-        });
-        wss.on("error", (err) => {
-          if (err.code === "EADDRINUSE" && attempt < maxRetries) {
-            wss.close();
-            tryPort(port + 1, attempt + 1);
-            return;
-          }
-          this.emit("server:error", err);
-          reject(err);
-        });
-      };
-      tryPort(this.port, 0);
-    });
-  }
-  handleConnection(ws) {
-    this.socketRoles.set(ws, "unknown");
-    this.rateState.set(ws, { startedAt: Date.now(), count: 0 });
-    const handshakeTimer = setTimeout(() => {
-      if (this.socketRoles.get(ws) === "unknown") {
-        ws.close(1008, "Dominus handshake timed out");
-      }
-    }, this.handshakeTimeoutMs);
-    ws.on("message", (raw) => {
-      try {
-        if (!this.consumeRateBudget(ws) || rawByteLength(raw) > this.maxPayloadBytes) {
-          ws.close(1009, "Dominus message limit exceeded");
-          return;
-        }
-        const msg = parseMessage(raw.toString());
-        const role = this.socketRoles.get(ws) ?? "unknown";
-        if (role === "unknown") {
-          clearTimeout(handshakeTimer);
-          this.handleHandshake(ws, msg);
-        } else if (role === "controller") {
-          this.handleControllerMessage(ws, msg);
-        } else if (role === "studio") {
-          this.handleStudioMessage(ws, msg);
-        }
-      } catch (err) {
-        this.emit("server:error", err);
-        this.sendSafe(ws, createMessage(StudioMsg.AUTH_REJECTED, {
-          error: err instanceof Error ? err.message : String(err)
-        }));
-      }
-    });
-    ws.on("close", () => {
-      clearTimeout(handshakeTimer);
-      this.cleanupSocket(ws);
-    });
-    ws.on("error", (err) => this.emit("server:error", err));
-  }
-  consumeRateBudget(ws) {
-    const now = Date.now();
-    const state = this.rateState.get(ws) ?? { startedAt: now, count: 0 };
-    if (now - state.startedAt >= RATE_WINDOW_MS) {
-      state.startedAt = now;
-      state.count = 0;
-    }
-    state.count += 1;
-    this.rateState.set(ws, state);
-    return state.count <= RATE_LIMIT;
-  }
-  handleHandshake(ws, msg) {
-    if (msg.type === StudioMsg.HELLO) {
-      const hello = validateStudioHello(msg.payload);
-      if (tokensEqual(hello.token, this.token)) {
-        this.authorizeStudio(ws, hello, randomUUID());
-      } else {
-        this.sendSafe(ws, createMessage(StudioMsg.AUTH_REJECTED, {
-          error: "Studio plugin credentials are missing or stale. Run dominus-install-plugin and restart Studio."
-        }));
-        ws.close(1008, "Unauthorized Studio plugin");
-      }
-      return;
-    }
-    if (msg.type === ControllerMsg.HELLO) {
-      const payload = msg.payload;
-      if (payload.protocolVersion !== DOMINUS_PROTOCOL_VERSION || !tokensEqual(payload.token, this.token)) {
-        this.sendSafe(ws, createMessage(StudioMsg.AUTH_REJECTED, { error: "Invalid Dominus controller credentials" }));
-        ws.close(1008, "Unauthorized controller");
-        return;
-      }
-      this.socketRoles.set(ws, "controller");
-      this.controllers.add(ws);
-      this.sendSafe(ws, createMessage(ControllerMsg.WELCOME, {
-        protocolVersion: DOMINUS_PROTOCOL_VERSION,
-        port: this.port,
-        connections: this.listConnections(),
-        activeConnectionId: this.activeConnectionId
-      }));
-      return;
-    }
-    this.sendSafe(ws, createMessage(StudioMsg.AUTH_REJECTED, {
-      error: `Expected ${StudioMsg.HELLO} or ${ControllerMsg.HELLO}`
-    }));
-    ws.close(1008, "Invalid Dominus handshake");
-  }
-  authorizeStudio(ws, hello, connectionId) {
-    const connection = {
-      ws,
-      connectionId,
-      clientId: hello.clientId,
-      connectedAt: Date.now(),
-      studioVersion: hello.studioVersion,
-      placeId: hello.placeId ?? 0,
-      placeName: hello.placeName
-    };
-    this.studioClients.set(connectionId, connection);
-    this.wsToConnectionId.set(ws, connectionId);
-    this.socketRoles.set(ws, "studio");
-    if (!this.activeConnectionId || !this.studioClients.has(this.activeConnectionId)) {
-      this.activeConnectionId = connectionId;
-    }
-    this.sendSafe(ws, createMessage(StudioMsg.AUTHENTICATED, {
-      protocolVersion: DOMINUS_PROTOCOL_VERSION,
-      connectionId,
-      token: this.token
-    }));
-    const info = this.toPlaceInfo(connection);
-    this.emit("studio:connected", info);
-    this.broadcastToControllers(StudioMsg.CONNECTED, info);
-    this.broadcastTargetState();
-    return connection;
-  }
-  handleControllerMessage(controllerWs, msg) {
-    if (msg.type === ControllerMsg.RELAY) {
-      const payload = msg.payload;
-      const request = parseMessage(JSON.stringify(payload.request));
-      const target = this.resolveConnection(typeof payload.connectionId === "string" ? payload.connectionId : null);
-      if (!target) {
-        this.sendResponse(controllerWs, request.id, { error: this.getTargetError() });
-        return;
-      }
-      this.relayRequests.set(request.id, { controllerWs, targetWs: target.ws });
-      this.sendSafe(target.ws, request);
-      return;
-    }
-    if (msg.type === ControllerMsg.SET_ACTIVE_CONNECTION) {
-      const payload = msg.payload;
-      const connectionId = typeof payload.connectionId === "string" ? payload.connectionId : null;
-      if (connectionId && !this.studioClients.has(connectionId)) {
-        this.sendResponse(controllerWs, msg.id, { success: false, error: `Studio connection ${connectionId} is not connected` });
-        return;
-      }
-      this.sendResponse(controllerWs, msg.id, { success: true, connectionId });
-      return;
-    }
-    this.sendResponse(controllerWs, msg.id, { error: `Unsupported controller message: ${msg.type}` });
-  }
-  handleStudioMessage(ws, msg) {
-    if (msg.type === StudioMsg.RESPONSE) {
-      const relay = this.relayRequests.get(msg.id);
-      if (relay) {
-        if (relay.targetWs !== ws) {
-          this.emit("server:error", new Error(`Ignored relayed response ${msg.id} from the wrong Studio session`));
-          return;
-        }
-        this.sendSafe(relay.controllerWs, msg);
-        this.relayRequests.delete(msg.id);
-        return;
-      }
-      const pending = this.pendingRequests.get(msg.id);
-      if (pending) {
-        if (pending.targetWs !== ws) {
-          this.emit("server:error", new Error(`Ignored response ${msg.id} from the wrong Studio session`));
-          return;
-        }
-        clearTimeout(pending.timer);
-        this.pendingRequests.delete(msg.id);
-        pending.resolve(msg);
-      }
-      return;
-    }
-    this.emit(msg.type, msg.payload);
-    this.emit("message", msg);
+
+// src/transport/daemon-launcher.ts
+function resolveDaemonPath() {
+  const besideEntry = fileURLToPath(new URL("./bridge-daemon.js", import.meta.url));
+  if (fs4.existsSync(besideEntry)) return besideEntry;
+  const projectBuild = path4.resolve(
+    path4.dirname(fileURLToPath(import.meta.url)),
+    "../../dist/bridge-daemon.js"
+  );
+  if (fs4.existsSync(projectBuild)) return projectBuild;
+  throw new Error("Dominus bridge daemon is missing. Reinstall or rebuild dominus-cli.");
+}
+function launchBridgeDaemon(port, daemonPath = resolveDaemonPath()) {
+  const child = spawn(process.execPath, [daemonPath], {
+    detached: true,
+    env: { ...process.env, DOMINUS_BRIDGE_PORT: String(port) },
+    stdio: "ignore",
+    windowsHide: true
+  });
+  child.unref();
+}
+async function connectController(port, timeoutMs, token) {
+  const client = new DominusClient(port, { connectTimeoutMs: timeoutMs, token });
+  try {
+    await client.connect();
+    return client;
+  } catch (error) {
+    await client.stop().catch(() => void 0);
+    throw error;
   }
-  cleanupSocket(ws) {
-    const role = this.socketRoles.get(ws);
-    this.socketRoles.delete(ws);
-    this.rateState.delete(ws);
-    if (role === "controller") {
-      this.controllers.delete(ws);
-      for (const [id, relay] of this.relayRequests) {
-        if (relay.controllerWs === ws) this.relayRequests.delete(id);
-      }
-      return;
-    }
-    const connectionId = this.wsToConnectionId.get(ws);
-    if (!connectionId) return;
-    const connection = this.studioClients.get(connectionId);
-    this.wsToConnectionId.delete(ws);
-    this.studioClients.delete(connectionId);
-    for (const [id, pending] of this.pendingRequests) {
-      if (pending.targetWs === ws) {
-        clearTimeout(pending.timer);
-        pending.reject(new Error(`Studio disconnected (${connectionId})`));
-        this.pendingRequests.delete(id);
-      }
-    }
-    for (const [id, relay] of this.relayRequests) {
-      if (relay.targetWs === ws) {
-        this.sendResponse(relay.controllerWs, id, { error: `Studio disconnected (${connectionId})` });
-        this.relayRequests.delete(id);
-      }
-    }
-    if (this.activeConnectionId === connectionId) {
-      this.activeConnectionId = this.studioClients.size === 1 ? this.studioClients.keys().next().value ?? null : null;
-    }
-    const info = connection ? this.toPlaceInfo(connection) : { connectionId };
-    this.emit("studio:disconnected", info);
-    this.broadcastToControllers(StudioMsg.DISCONNECTED, info);
-    this.broadcastTargetState();
-  }
-  resolveConnection(connectionId = this.activeConnectionId) {
-    if (connectionId) {
-      const connection = this.studioClients.get(connectionId);
-      return connection?.ws.readyState === WebSocket.OPEN ? connection : null;
-    }
-    if (this.studioClients.size === 1) {
-      const connection = this.studioClients.values().next().value;
-      return connection?.ws.readyState === WebSocket.OPEN ? connection : null;
+}
+async function ensureBridgeDaemon(port, options = {}) {
+  const attempts = options.attempts ?? 30;
+  const connectTimeoutMs = options.connectTimeoutMs ?? 750;
+  const retryDelayMs = options.retryDelayMs ?? 100;
+  try {
+    return await connectController(port, connectTimeoutMs, options.token);
+  } catch (initialError) {
+    if (await isPortInUse(port)) {
+      throw new Error(
+        `Port ${port} is occupied by a process that is not this Dominus bridge: ${formatError(initialError)}`
+      );
     }
-    return null;
-  }
-  getTargetError() {
-    if (this.studioClients.size === 0) return "No authenticated Roblox Studio connection";
-    if (this.activeConnectionId) return `Studio connection ${this.activeConnectionId} is unavailable`;
-    return "Multiple Studio sessions are connected. Call dominus_select_studio with a connectionId.";
   }
-  toPlaceInfo(connection) {
-    return {
-      placeId: connection.placeId ?? 0,
-      connectionId: connection.connectionId,
-      clientId: connection.clientId,
-      placeName: connection.placeName,
-      studioVersion: connection.studioVersion,
-      connectedAt: connection.connectedAt,
-      active: connection.connectionId === this.activeConnectionId
-    };
-  }
-  broadcastToControllers(type, payload) {
-    const message = createMessage(type, payload);
-    for (const controller of this.controllers) this.sendSafe(controller, message);
-  }
-  broadcastTargetState() {
-    this.broadcastToControllers(ControllerMsg.TARGET_STATE, {
-      connections: this.listConnections(),
-      defaultActiveConnectionId: this.activeConnectionId
-    });
-  }
-  sendResponse(ws, id, payload) {
-    this.sendSafe(ws, { id, type: StudioMsg.RESPONSE, payload, ts: Date.now() });
-  }
-  sendSafe(ws, message) {
-    if (ws.readyState !== WebSocket.OPEN) return;
+  const launch = options.launch ?? ((targetPort) => launchBridgeDaemon(targetPort, options.daemonPath));
+  launch(port);
+  let lastError;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
     try {
-      ws.send(serializeMessage(message));
-    } catch (err) {
-      this.emit("server:error", err);
+      return await connectController(port, connectTimeoutMs, options.token);
+    } catch (error) {
+      lastError = error;
     }
   }
-  sendRequest(type, payload, timeoutMs = 15e3) {
-    return new Promise((resolve, reject) => {
-      const target = this.resolveConnection();
-      if (!target) {
-        reject(new Error(this.getTargetError()));
-        return;
-      }
-      const message = createMessage(type, payload);
-      const timer = setTimeout(() => {
-        this.pendingRequests.delete(message.id);
-        reject(new Error(`Studio request timed out: ${type}`));
-      }, timeoutMs);
-      this.pendingRequests.set(message.id, {
-        resolve,
-        reject,
-        timer,
-        targetWs: target.ws
-      });
-      this.sendSafe(target.ws, message);
-    });
-  }
-  sendNotification(type, payload) {
-    const target = this.resolveConnection();
-    if (target) this.sendSafe(target.ws, createMessage(type, payload));
-  }
-  isConnected() {
-    return this.resolveConnection() !== null;
-  }
-  getConnectionInfo() {
-    return this.resolveConnection();
-  }
-  listConnections() {
-    return [...this.studioClients.values()].filter(({ ws }) => ws.readyState === WebSocket.OPEN).map((connection) => this.toPlaceInfo(connection));
-  }
-  getActiveConnectionId() {
-    return this.activeConnectionId;
-  }
-  async setActiveConnectionId(connectionId) {
-    if (connectionId && !this.studioClients.has(connectionId)) {
-      throw new Error(`Studio connection ${connectionId} is not connected`);
-    }
-    this.activeConnectionId = connectionId;
-    this.broadcastTargetState();
-  }
-  getActivePlaceId() {
-    return this.resolveConnection()?.placeId ?? 0;
-  }
-  setActivePlaceId(placeId) {
-    if (placeId === 0) {
-      this.activeConnectionId = null;
-      return;
-    }
-    const matches = [...this.studioClients.values()].filter((connection) => connection.placeId === placeId);
-    if (matches.length !== 1) {
-      throw new Error(matches.length === 0 ? `Place ${placeId} is not connected` : `Place ${placeId} has multiple Studio sessions; select a connectionId instead`);
-    }
-    this.activeConnectionId = matches[0].connectionId;
-  }
-  getPort() {
-    return this.port;
-  }
-  stop() {
-    return new Promise((resolve) => {
-      for (const pending of this.pendingRequests.values()) {
-        clearTimeout(pending.timer);
-        pending.reject(new Error("Dominus bridge is shutting down"));
-      }
-      this.pendingRequests.clear();
-      this.relayRequests.clear();
-      for (const ws of this.socketRoles.keys()) ws.close(1001, "Dominus bridge shutdown");
-      this.studioClients.clear();
-      this.controllers.clear();
-      this.socketRoles.clear();
-      this.wsToConnectionId.clear();
-      if (this.wss) this.wss.close(() => resolve());
-      else resolve();
-    });
-  }
-};
-function validateStudioHello(payload) {
-  if (!payload || typeof payload !== "object") throw new Error("Invalid Studio hello payload");
-  const hello = payload;
-  if (hello.protocolVersion !== DOMINUS_PROTOCOL_VERSION) {
-    throw new Error(`Studio plugin protocol ${hello.protocolVersion ?? "unknown"} is incompatible; expected ${DOMINUS_PROTOCOL_VERSION}`);
-  }
-  if (typeof hello.clientId !== "string" || hello.clientId.length < 8 || hello.clientId.length > 128) {
-    throw new Error("Studio hello is missing a valid clientId");
-  }
-  if (typeof hello.studioVersion !== "string" || hello.studioVersion.length > 128) {
-    throw new Error("Studio hello is missing studioVersion");
-  }
-  if (hello.placeName && hello.placeName.length > 256) throw new Error("Studio placeName is too long");
-  return hello;
+  throw new Error(
+    `Dominus could not start its local Studio bridge on port ${port}: ${formatError(lastError)}`
+  );
 }
-function rawByteLength(raw) {
-  if (typeof raw === "string") return Buffer.byteLength(raw);
-  if (Array.isArray(raw)) return raw.reduce((total, item) => total + item.byteLength, 0);
-  return raw.byteLength;
+function formatError(error) {
+  return error instanceof Error ? error.message : String(error ?? "unknown error");
 }
 
 // src/mcp/instructions.ts
 var DOMINUS_MCP_INSTRUCTIONS = `Dominus 2 is a Roblox Studio engineering MCP server.
 
 Required workflow for Studio changes:
-1. Call dominus_status and select the intended Studio connection when more than one is open.
+1. Call dominus_status. If Studio is disconnected, ask the user to run dominus-install-plugin only when the Studio Output reports an authentication failure. Select the intended authenticated Studio connection when more than one window is open.
 2. Inspect the relevant tree, selection, instances, scripts, and Roblox API references before editing.
 3. Form a short plan with explicit acceptance checks.
 4. Use stable instance refs returned by Dominus. Prefer instanceId; retain pathSegments as fallback context.
@@ -1164,10 +834,10 @@ async function readReferenceYaml(name, kind, opts) {
   const folder = KIND_FOLDERS[kind];
   const fileName = `${name}.yaml`;
   if (localRoot) {
-    const localPath = path3.join(localRoot, folder, fileName);
-    if (fs3.existsSync(localPath)) {
+    const localPath = path4.join(localRoot, folder, fileName);
+    if (fs4.existsSync(localPath)) {
       return {
-        content: fs3.readFileSync(localPath, "utf-8"),
+        content: fs4.readFileSync(localPath, "utf-8"),
         sourceUrl: toCreatorDocsUrl(kind, name)
       };
     }
@@ -1187,11 +857,11 @@ async function listReferenceEntries(opts) {
   if (localRoot) {
     const entries = [];
     for (const [kind, folder] of Object.entries(KIND_FOLDERS)) {
-      const dir = path3.join(localRoot, folder);
-      if (!fs3.existsSync(dir)) continue;
-      for (const file of fs3.readdirSync(dir)) {
+      const dir = path4.join(localRoot, folder);
+      if (!fs4.existsSync(dir)) continue;
+      for (const file of fs4.readdirSync(dir)) {
         if (!file.endsWith(".yaml")) continue;
-        const name = path3.basename(file, ".yaml");
+        const name = path4.basename(file, ".yaml");
         entries.push({ name, kind, score: 0, sourceUrl: toCreatorDocsUrl(kind, name) });
       }
     }
@@ -1204,7 +874,7 @@ async function listReferenceEntries(opts) {
     const [folder, file] = rest.split("/");
     const kind = folderToKind(folder);
     if (!kind || !file) return [];
-    const name = path3.basename(file, ".yaml");
+    const name = path4.basename(file, ".yaml");
     return [{ name, kind, score: 0, sourceUrl: toCreatorDocsUrl(kind, name) }];
   });
 }
@@ -1224,19 +894,19 @@ function resolveDocsRoot(explicitRoot) {
   const candidates = [
     explicitRoot,
     process.env.ROBLOX_CREATOR_DOCS_PATH,
-    path3.join(process.cwd(), ".tmp", "creator-docs")
+    path4.join(process.cwd(), ".tmp", "creator-docs")
   ].filter(Boolean);
   for (const candidate of candidates) {
     const normalized = normalizeDocsRoot(candidate);
-    if (normalized && fs3.existsSync(normalized)) return normalized;
+    if (normalized && fs4.existsSync(normalized)) return normalized;
   }
   return null;
 }
 function normalizeDocsRoot(root) {
-  const engineRoot = path3.join(root, "content", "en-us", "reference", "engine");
-  if (fs3.existsSync(engineRoot)) return engineRoot;
-  const directClasses = path3.join(root, "classes");
-  if (fs3.existsSync(directClasses)) return root;
+  const engineRoot = path4.join(root, "content", "en-us", "reference", "engine");
+  if (fs4.existsSync(engineRoot)) return engineRoot;
+  const directClasses = path4.join(root, "classes");
+  if (fs4.existsSync(directClasses)) return root;
   return null;
 }
 function normalizeLookupName(name) {
@@ -1905,7 +1575,7 @@ function rejectProposalConflicts(accepted) {
     const targets = item.proposal.operations.map(operationTarget);
     const conflict = claims.find(
       (claim) => targets.some(
-        (target) => target.path && claim.paths.some((path4) => parallelPathsOverlap(target.path, path4)) || claim.refKeys.includes(target.key)
+        (target) => target.path && claim.paths.some((path5) => parallelPathsOverlap(target.path, path5)) || claim.refKeys.includes(target.key)
       )
     );
     if (conflict) {
@@ -2036,7 +1706,7 @@ async function verifyPlan(bridge, rootRef, originalRoot, operations) {
     const parentPath = resolveRefPath(operation.parent, knownPaths);
     return parentPath ? [pathKey([...parentPath, operation.name])] : [];
   });
-  const missingCreates = expectedCreates.filter((path4) => !paths.has(path4));
+  const missingCreates = expectedCreates.filter((path5) => !paths.has(path5));
   const inspectOperations = operations.filter((operation) => operation.op !== "create");
   const inspectFailures = [];
   const propertyMismatches = [];
@@ -2204,8 +1874,8 @@ function resolveRefPath(ref2, known) {
   if (ref2.pathSegments) return ref2.pathSegments;
   return ref2.instanceId ? known.get(`id:${ref2.instanceId}`) : void 0;
 }
-function pathKey(path4) {
-  return path4.join("\0");
+function pathKey(path5) {
+  return path5.join("\0");
 }
 function parallelPathIsWithin(target, scope) {
   return target.length >= scope.length && scope.every((segment, index) => target[index] === segment);
@@ -2218,8 +1888,8 @@ function samePath(left, right) {
     left && right && left.length === right.length && left.every((part, index) => part === right[index])
   );
 }
-function parallelRootPathToSegments(path4) {
-  const trimmed = path4.trim();
+function parallelRootPathToSegments(path5) {
+  const trimmed = path5.trim();
   const bracketSegments = [...trimmed.matchAll(/\["((?:\\.|[^"])*)"\]/g)].map(
     (match) => JSON.parse(`"${match[1]}"`)
   );
@@ -2556,7 +2226,7 @@ function registerStudioTools(server, bridge) {
 }
 
 // src/mcp/server.ts
-var VERSION = "2.2.0";
+var VERSION = "2.2.1";
 function createDominusMcpServer(bridge) {
   const server = new McpServer(
     {
@@ -2575,22 +2245,7 @@ function createDominusMcpServer(bridge) {
   return server;
 }
 async function createStudioBridge(port) {
-  if (await isPortInUse(port)) {
-    const client = new DominusClient(port);
-    await client.connect();
-    return client;
-  }
-  const server = new DominusServer(port);
-  try {
-    await server.start();
-    return server;
-  } catch (err) {
-    const error = err;
-    if (error.code !== "EADDRINUSE") throw err;
-    const client = new DominusClient(port);
-    await client.connect();
-    return client;
-  }
+  return ensureBridgeDaemon(port);
 }
 async function startMcpServer() {
   const config = loadConfig();