@chrrxs/robloxstudio-mcp-inspector 2.22.0 → 2.22.2

package/dist/index.js

@@ -32,7 +32,7 @@ function publishedInstanceId(placeId) {
     return void 0;
   return `place:${Math.trunc(placeId)}`;
 }
-var RoutingFailure, STALE_INSTANCE_MS, INSTANCE_ALIAS_TTL_MS, BridgeService;
+var RoutingFailure, STALE_INSTANCE_MS, DUPLICATE_TAKEOVER_MS, INSTANCE_ALIAS_TTL_MS, BridgeService;
 var init_bridge_service = __esm({
   "../core/dist/bridge-service.js"() {
     "use strict";
@@ -45,6 +45,7 @@ var init_bridge_service = __esm({
       }
     };
     STALE_INSTANCE_MS = 3e4;
+    DUPLICATE_TAKEOVER_MS = 3e3;
     INSTANCE_ALIAS_TTL_MS = 5 * 60 * 1e3;
     BridgeService = class {
       pendingRequests = /* @__PURE__ */ new Map();
@@ -167,14 +168,18 @@ var init_bridge_service = __esm({
         }
         const existing = Array.from(this.instances.values()).find((i) => i.instanceId === instanceId && i.role === assignedRole && i.pluginSessionId !== pluginSessionId);
         if (existing) {
-          return {
-            ok: false,
-            error: {
-              code: "duplicate_instance_role",
-              message: `Another plugin is already registered as (${instanceId}, ${assignedRole}).`,
-              existing: toPublic(existing)
-            }
-          };
+          if (Date.now() - existing.lastActivity > DUPLICATE_TAKEOVER_MS) {
+            this.unregisterInstance(existing.pluginSessionId);
+          } else {
+            return {
+              ok: false,
+              error: {
+                code: "duplicate_instance_role",
+                message: `Another plugin is already registered as (${instanceId}, ${assignedRole}).`,
+                existing: toPublic(existing)
+              }
+            };
+          }
         }
         const registered = {
           pluginSessionId,
@@ -501,6 +506,93 @@ function cacheSet(key, entry) {
 function docUrl(category, name) {
   return `${DOCS_BASE_URL}/${category}/${encodeURIComponent(name)}.md`;
 }
+function normalizeDocName(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function queryNameVariants(value) {
+  const parts = value.split(/[./:#\s]+/).filter(Boolean);
+  const variants = /* @__PURE__ */ new Set([normalizeDocName(value)]);
+  for (const part of parts) {
+    const normalized = normalizeDocName(part);
+    if (normalized && normalized !== "enum")
+      variants.add(normalized);
+  }
+  return Array.from(variants).filter(Boolean);
+}
+function editDistance(left, right) {
+  const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= left.length; i++) {
+    let diagonal = previous[0];
+    previous[0] = i;
+    for (let j = 1; j <= right.length; j++) {
+      const above = previous[j];
+      previous[j] = Math.min(previous[j] + 1, previous[j - 1] + 1, diagonal + (left[i - 1] === right[j - 1] ? 0 : 1));
+      diagonal = above;
+    }
+  }
+  return previous[right.length];
+}
+async function fetchDocCatalog() {
+  if (catalogCache && Date.now() - catalogCache.fetchedAt <= CACHE_TTL_MS) {
+    return catalogCache.pages;
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  let response;
+  try {
+    response = await fetch(DOCS_INDEX_URL, {
+      signal: controller.signal,
+      headers: { Accept: "text/html" }
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+  if (!response.ok) {
+    throw new Error(`Failed to fetch Roblox docs index: HTTP ${response.status}`);
+  }
+  const html = await response.text();
+  const pages = /* @__PURE__ */ new Map();
+  const routePattern = /reference\/engine\/(classes|enums|datatypes|libraries|globals)\/([A-Za-z0-9_]+)/g;
+  for (const match of html.matchAll(routePattern)) {
+    const category = match[1];
+    const name = match[2];
+    const key = `${category}/${name}`;
+    pages.set(key, { category, name, url: docUrl(category, name) });
+  }
+  const result = Array.from(pages.values());
+  if (result.length === 0) {
+    throw new Error("Roblox docs index did not contain any engine reference pages");
+  }
+  catalogCache = { fetchedAt: Date.now(), pages: result };
+  return result;
+}
+async function recommendRobloxDocs(category, name, limit = 5) {
+  const variants = queryNameVariants(name);
+  const catalog = await fetchDocCatalog();
+  return catalog.map((page) => {
+    const candidate = normalizeDocName(page.name);
+    const similarity = Math.max(...variants.map((variant) => {
+      if (variant === candidate)
+        return 2;
+      const distance = editDistance(variant, candidate);
+      const ratio = 1 - distance / Math.max(variant.length, candidate.length, 1);
+      const prefixBonus = variant.startsWith(candidate) || candidate.startsWith(variant) ? 0.15 : 0;
+      const containsBonus = variant.includes(candidate) || candidate.includes(variant) ? 0.05 : 0;
+      return ratio + prefixBonus + containsBonus;
+    }));
+    return { page, score: similarity + (page.category === category ? 0.08 : 0) };
+  }).sort((a, b) => b.score - a.score || a.page.name.localeCompare(b.page.name)).slice(0, Math.max(1, limit)).map(({ page }) => page);
+}
+function recommendationsMarkdown(requestedCategory, requestedName, recommendations) {
+  const lines = recommendations.map((page) => `- [${page.category}/${page.name}](${page.url}) \u2014 retry with \`name="${page.name}", doc_type="${page.category}"\``);
+  return [
+    `# No exact Roblox documentation page found`,
+    "",
+    `The lookup \`${requestedCategory}/${requestedName}\` did not resolve. Recommended pages:`,
+    "",
+    ...lines
+  ].join("\n");
+}
 async function fetchRobloxDoc(category, name) {
   const key = `${category}/${name}`;
   const cached = cacheGet(key);
@@ -565,7 +657,24 @@ function extractSection(markdown, section) {
   return lines.slice(start, end).join("\n").trimEnd();
 }
 async function getRobloxDoc(category, name, section) {
-  const markdown = await fetchRobloxDoc(category, name);
+  let markdown;
+  try {
+    markdown = await fetchRobloxDoc(category, name);
+  } catch (error) {
+    if (!(error instanceof DocNotFoundError))
+      throw error;
+    try {
+      const recommendations = await recommendRobloxDocs(category, name);
+      return {
+        content: recommendationsMarkdown(category, name, recommendations),
+        truncated: false,
+        sections: [],
+        recommendations
+      };
+    } catch {
+      throw error;
+    }
+  }
   const sections = listSections(markdown);
   if (section) {
     const extracted = extractSection(markdown, section);
@@ -584,12 +693,13 @@ async function getRobloxDoc(category, name, section) {
   }
   return { content: markdown, truncated: false, sections };
 }
-var DOC_CATEGORIES, DOCS_BASE_URL, FETCH_TIMEOUT_MS, CACHE_TTL_MS, NEGATIVE_CACHE_TTL_MS, MAX_CACHE_ENTRIES, MAX_DOC_CHARS, cache, DocNotFoundError;
+var DOC_CATEGORIES, DOCS_BASE_URL, DOCS_INDEX_URL, FETCH_TIMEOUT_MS, CACHE_TTL_MS, NEGATIVE_CACHE_TTL_MS, MAX_CACHE_ENTRIES, MAX_DOC_CHARS, cache, catalogCache, DocNotFoundError;
 var init_roblox_docs = __esm({
   "../core/dist/roblox-docs.js"() {
     "use strict";
     DOC_CATEGORIES = ["classes", "enums", "datatypes", "libraries", "globals"];
     DOCS_BASE_URL = "https://create.roblox.com/docs/reference/engine";
+    DOCS_INDEX_URL = DOCS_BASE_URL;
     FETCH_TIMEOUT_MS = 15e3;
     CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
     NEGATIVE_CACHE_TTL_MS = 5 * 60 * 1e3;
@@ -13381,7 +13491,7 @@ part(0,2,0,2,1,1,"b")`,
       {
         name: "get_roblox_docs",
         category: "read",
-        description: 'Fetch official Roblox engine API documentation as markdown from create.roblox.com. Call this BEFORE writing or editing code that uses an engine class, enum, datatype, or Luau library you are not fully certain about (e.g. ProximityPrompt, Enum.KeyCode, CFrame, TweenService) \u2014 the page includes the description, properties, methods, events, and code samples. Results are cached, so repeat lookups are cheap. Very large pages are truncated with a section index; pass section (e.g. "Properties", "Methods", "Events") to read one section in full.',
+        description: 'Fetch official Roblox engine API documentation as markdown from create.roblox.com. Call this BEFORE writing or editing code that uses an engine class, enum, datatype, or Luau library you are not fully certain about (e.g. ProximityPrompt, Enum.KeyCode, CFrame, TweenService) \u2014 the page includes the description, properties, methods, events, and code samples. Unresolved names return ranked recommendations from the official engine index, including pages in other doc categories. Results are cached, so repeat lookups are cheap. Very large pages are truncated with a section index; pass section (e.g. "Properties", "Methods", "Events") to read one section in full.',
         inputSchema: {
           type: "object",
           properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrrxs/robloxstudio-mcp-inspector",
-  "version": "2.22.0",
+  "version": "2.22.2",
   "description": "Read-only MCP server for inspecting and debugging Roblox Studio from AI coding tools",
   "main": "dist/index.js",
   "type": "module",

package/studio-plugin/MCPInspectorPlugin.rbxmx

@@ -712,11 +712,11 @@ local function computeInstanceId()
 	return `anon:{fresh}`
 end
 local assignedRole
-local duplicateInstanceRole = false
 local hasVersionMismatch = false
 local lastVersionMismatchWarningKey
 local lastReadyInstanceId
 local readyFailureLogKeys = {}
+local retryingDuplicateReady = false
 -- Cache the published place name from MarketplaceService:GetProductInfo so
 -- /ready can carry a friendly identifier (e.g. "Natural Disasters") distinct
 -- from game.Name (the DataModel name, often "Place1" in edit). We only fetch
@@ -843,19 +843,33 @@ local function processRequest(request)
 	end
 end
 local function sendResponse(conn, requestId, responseData)
-	pcall(function()
-		HttpService:RequestAsync({
-			Url = `{conn.serverUrl}/response`,
+	local responseUrl = `{conn.serverUrl}/response`
+	local encodeOk, encoded = pcall(function()
+		return HttpService:JSONEncode({
+			requestId = requestId,
+			response = responseData,
+		})
+	end)
+	local body = if encodeOk then encoded else HttpService:JSONEncode({
+		requestId = requestId,
+		error = `Plugin response serialization failed: {tostring(encoded)}`,
+	})
+	if not encodeOk then
+		warn(`[robloxstudio-mcp] Failed to serialize response {requestId}: {tostring(encoded)}`)
+	end
+	local requestOk, requestResult = pcall(function()
+		return HttpService:RequestAsync({
+			Url = responseUrl,
 			Method = "POST",
 			Headers = {
 				["Content-Type"] = "application/json",
 			},
-			Body = HttpService:JSONEncode({
-				requestId = requestId,
-				response = responseData,
-			}),
+			Body = body,
 		})
 	end)
+	if not requestOk or not requestResult.Success then
+		warn(`[robloxstudio-mcp] Failed to deliver response {requestId}: {HttpDiagnostics.formatRequestFailure(responseUrl, requestOk, requestResult)}`)
+	end
 end
 local function getConnectionStatus()
 	local conn = State.getActiveConnection()
@@ -906,11 +920,12 @@ local function ensureIdentityWatcher(conn)
 	end
 end
 function sendReady(conn)
-	if duplicateInstanceRole then
-		return nil
-	end
 	local now = tick()
-	if now - lastReadyPostAt < 2 then
+	-- Normal identity refreshes stay conservatively throttled. Once a stale
+	-- predecessor causes 409, retry once per second so takeover follows the
+	-- server's short inactivity lease without another two seconds of jitter.
+	local readyInterval = if retryingDuplicateReady then 1 else 2
+	if now - lastReadyPostAt < readyInterval then
 		return nil
 	end
 	lastReadyPostAt = now
@@ -942,28 +957,39 @@ function sendReady(conn)
 		local readyRole = detectRole()
 		local readyLogKey = `{conn.serverUrl}|{instanceId}|{readyRole}`
 		if not readyOk then
+			local shouldLog = not (readyFailureLogKeys[readyLogKey] ~= nil)
 			readyFailureLogKeys[readyLogKey] = true
-			warn(`[robloxstudio-mcp] /ready failed for {instanceId}/{readyRole}: {HttpDiagnostics.formatRequestFailure(readyUrl, readyOk, readyResult)}`)
+			if shouldLog then
+				warn(`[robloxstudio-mcp] /ready failed for {instanceId}/{readyRole}: {HttpDiagnostics.formatRequestFailure(readyUrl, readyOk, readyResult)}`)
+			end
 			return nil
 		end
 		if not readyResult.Success then
 			local reason = HttpDiagnostics.formatRequestFailure(readyUrl, true, readyResult)
+			local shouldLog = not (readyFailureLogKeys[readyLogKey] ~= nil)
 			readyFailureLogKeys[readyLogKey] = true
-			-- 409 = duplicate_instance_role. Surface in UI and stop polling.
+			-- A predecessor can remain registered briefly when Studio exits before
+			-- its asynchronous /disconnect completes. Keep polling and retrying
+			-- /ready: the server will take us over once the predecessor has stopped
+			-- polling, while a genuinely active duplicate continues to hold routing.
 			if readyResult.StatusCode == 409 then
-				duplicateInstanceRole = true
-				conn.isActive = false
+				retryingDuplicateReady = true
 				local ui = UI.getElements()
-				ui.statusLabel.Text = "Duplicate instance"
-				ui.statusLabel.TextColor3 = Color3.fromRGB(239, 68, 68)
+				ui.statusLabel.Text = "Waiting for previous instance"
+				ui.statusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
 				ui.detailStatusLabel.Text = reason
-				ui.detailStatusLabel.TextColor3 = Color3.fromRGB(239, 68, 68)
-				warn(`[robloxstudio-mcp] /ready rejected for {instanceId}/{readyRole}: {reason}`)
+				ui.detailStatusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
+				if shouldLog then
+					warn(`[robloxstudio-mcp] /ready rejected for {instanceId}/{readyRole}: {reason}`)
+				end
 				return nil
 			end
-			warn(`[robloxstudio-mcp] /ready rejected for {instanceId}/{readyRole}: {reason}`)
+			if shouldLog then
+				warn(`[robloxstudio-mcp] /ready rejected for {instanceId}/{readyRole}: {reason}`)
+			end
 			return nil
 		end
+		retryingDuplicateReady = false
 		local parseOk, readyData = pcall(function()
 			return HttpService:JSONDecode(readyResult.Body)
 		end)
@@ -1413,9 +1439,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "2.22.0" is replaced with the package version at package time
+	-- "2.22.2" is replaced with the package version at package time
 	-- (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
-	return `{tostring(h)}-2.22.0`
+	return `{tostring(h)}-2.22.2`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -10425,6 +10451,41 @@ end
 local function nowSec()
 	return DateTime.now().UnixTimestampMillis / 1000
 end
+-- Studio occasionally exposes binary-bearing Output messages through
+-- LogService (for example, plugin hydration diagnostics containing raw CSG
+-- data). HttpService:JSONEncode rejects those strings outright. Preserve all
+-- valid UTF-8 verbatim and make only malformed bytes JSON-safe and visible.
+local function escapeInvalidUtf8(msg)
+	local valid = utf8.len(msg)
+	-- Roblox currently returns nil (not the false declared by @rbxts/types)
+	-- when it encounters a malformed sequence. A numeric result is the only
+	-- portable success discriminator across both representations.
+	if type(valid) == "number" then
+		return msg
+	end
+	local parts = {}
+	local cursor = 1
+	while cursor <= #msg do
+		local suffixValid, invalidPosition = utf8.len(msg, cursor)
+		if type(suffixValid) == "number" then
+			local _arg0 = string.sub(msg, cursor)
+			table.insert(parts, _arg0)
+			break
+		end
+		if not (type(invalidPosition) == "number") then
+			break
+		end
+		if invalidPosition > cursor then
+			local _arg0 = string.sub(msg, cursor, invalidPosition - 1)
+			table.insert(parts, _arg0)
+		end
+		local invalidByte = string.byte(msg, invalidPosition)
+		local _arg0 = string.format("\\x%02X", invalidByte)
+		table.insert(parts, _arg0)
+		cursor = invalidPosition + 1
+	end
+	return table.concat(parts, "")
+end
 local function dropOldestUntilFits(incomingBytes)
 	while #entries > 0 and (totalBytes + incomingBytes > MAX_BYTES or #entries >= HARD_ENTRY_CAP) do
 		local dropped = table.remove(entries, 1)
@@ -10436,37 +10497,44 @@ local function pushEntry(msg, t, ts)
 	if ts == nil then
 		ts = nowSec()
 	end
-	local bytes = #msg
+	local safeMessage = escapeInvalidUtf8(msg)
+	local bytes = #safeMessage
 	dropOldestUntilFits(bytes)
 	local _arg0 = {
 		seq = nextSeq,
 		ts = ts,
 		level = levelTag(t),
-		message = msg,
+		message = safeMessage,
 	}
 	table.insert(entries, _arg0)
 	nextSeq += 1
 	totalBytes += bytes
 end
 local function seedRuntimeHistory()
-	if not RunService:IsRunning() then
-		return nil
-	end
 	local ok, history = pcall(function()
 		return LogService:GetLogHistory()
 	end)
 	if not ok then
 		return nil
 	end
+	local isEdit = not RunService:IsRunning()
+	-- GetLogHistory timestamps and DateTime.now() share Unix time, while
+	-- os.clock() is elapsed time for this Studio process. Their difference is
+	-- therefore the process launch boundary. Edit-mode history is filtered to
+	-- that boundary so startup errors from this launch are recovered without
+	-- importing history left by an earlier Studio process.
+	local processStartedAt = nowSec() - os.clock()
 	for _, entry in history do
 		local _message = entry.message
 		if not (type(_message) == "string") then
 			continue
 		end
-		local _exp = entry.message
-		local _exp_1 = entry.messageType
 		local _timestamp = entry.timestamp
-		pushEntry(_exp, _exp_1, if type(_timestamp) == "number" then entry.timestamp else nil)
+		local timestamp = if type(_timestamp) == "number" then entry.timestamp else nil
+		if isEdit and (timestamp == nil or timestamp < processStartedAt - 1) then
+			continue
+		end
+		pushEntry(entry.message, entry.messageType, timestamp)
 	end
 end
 local function install()
@@ -10477,9 +10545,9 @@ local function install()
 		return nil
 	end
 	installed = true
-	-- Play peers can emit startup logs before the plugin finishes loading.
-	-- Seed from per-DataModel LogHistory so get_runtime_logs can still see
-	-- those early messages; skip edit mode to avoid stale prior-session logs.
+	-- Every peer can emit startup logs before the plugin finishes loading.
+	-- Seed from per-DataModel LogHistory so get_runtime_logs can still see them;
+	-- edit history is bounded to the current Studio process above.
 	seedRuntimeHistory()
 	LogService.MessageOut:Connect(function(msg, t)
 		pushEntry(msg, t)
@@ -10745,7 +10813,7 @@ return {
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "2.22.0"
+local CURRENT_VERSION = "2.22.2"
 local PLUGIN_VARIANT = "inspector"
 local BASE_PORT = 58741
 local function createConnection(port)

package/studio-plugin/MCPPlugin.rbxmx

@@ -712,11 +712,11 @@ local function computeInstanceId()
 	return `anon:{fresh}`
 end
 local assignedRole
-local duplicateInstanceRole = false
 local hasVersionMismatch = false
 local lastVersionMismatchWarningKey
 local lastReadyInstanceId
 local readyFailureLogKeys = {}
+local retryingDuplicateReady = false
 -- Cache the published place name from MarketplaceService:GetProductInfo so
 -- /ready can carry a friendly identifier (e.g. "Natural Disasters") distinct
 -- from game.Name (the DataModel name, often "Place1" in edit). We only fetch
@@ -843,19 +843,33 @@ local function processRequest(request)
 	end
 end
 local function sendResponse(conn, requestId, responseData)
-	pcall(function()
-		HttpService:RequestAsync({
-			Url = `{conn.serverUrl}/response`,
+	local responseUrl = `{conn.serverUrl}/response`
+	local encodeOk, encoded = pcall(function()
+		return HttpService:JSONEncode({
+			requestId = requestId,
+			response = responseData,
+		})
+	end)
+	local body = if encodeOk then encoded else HttpService:JSONEncode({
+		requestId = requestId,
+		error = `Plugin response serialization failed: {tostring(encoded)}`,
+	})
+	if not encodeOk then
+		warn(`[robloxstudio-mcp] Failed to serialize response {requestId}: {tostring(encoded)}`)
+	end
+	local requestOk, requestResult = pcall(function()
+		return HttpService:RequestAsync({
+			Url = responseUrl,
 			Method = "POST",
 			Headers = {
 				["Content-Type"] = "application/json",
 			},
-			Body = HttpService:JSONEncode({
-				requestId = requestId,
-				response = responseData,
-			}),
+			Body = body,
 		})
 	end)
+	if not requestOk or not requestResult.Success then
+		warn(`[robloxstudio-mcp] Failed to deliver response {requestId}: {HttpDiagnostics.formatRequestFailure(responseUrl, requestOk, requestResult)}`)
+	end
 end
 local function getConnectionStatus()
 	local conn = State.getActiveConnection()
@@ -906,11 +920,12 @@ local function ensureIdentityWatcher(conn)
 	end
 end
 function sendReady(conn)
-	if duplicateInstanceRole then
-		return nil
-	end
 	local now = tick()
-	if now - lastReadyPostAt < 2 then
+	-- Normal identity refreshes stay conservatively throttled. Once a stale
+	-- predecessor causes 409, retry once per second so takeover follows the
+	-- server's short inactivity lease without another two seconds of jitter.
+	local readyInterval = if retryingDuplicateReady then 1 else 2
+	if now - lastReadyPostAt < readyInterval then
 		return nil
 	end
 	lastReadyPostAt = now
@@ -942,28 +957,39 @@ function sendReady(conn)
 		local readyRole = detectRole()
 		local readyLogKey = `{conn.serverUrl}|{instanceId}|{readyRole}`
 		if not readyOk then
+			local shouldLog = not (readyFailureLogKeys[readyLogKey] ~= nil)
 			readyFailureLogKeys[readyLogKey] = true
-			warn(`[robloxstudio-mcp] /ready failed for {instanceId}/{readyRole}: {HttpDiagnostics.formatRequestFailure(readyUrl, readyOk, readyResult)}`)
+			if shouldLog then
+				warn(`[robloxstudio-mcp] /ready failed for {instanceId}/{readyRole}: {HttpDiagnostics.formatRequestFailure(readyUrl, readyOk, readyResult)}`)
+			end
 			return nil
 		end
 		if not readyResult.Success then
 			local reason = HttpDiagnostics.formatRequestFailure(readyUrl, true, readyResult)
+			local shouldLog = not (readyFailureLogKeys[readyLogKey] ~= nil)
 			readyFailureLogKeys[readyLogKey] = true
-			-- 409 = duplicate_instance_role. Surface in UI and stop polling.
+			-- A predecessor can remain registered briefly when Studio exits before
+			-- its asynchronous /disconnect completes. Keep polling and retrying
+			-- /ready: the server will take us over once the predecessor has stopped
+			-- polling, while a genuinely active duplicate continues to hold routing.
 			if readyResult.StatusCode == 409 then
-				duplicateInstanceRole = true
-				conn.isActive = false
+				retryingDuplicateReady = true
 				local ui = UI.getElements()
-				ui.statusLabel.Text = "Duplicate instance"
-				ui.statusLabel.TextColor3 = Color3.fromRGB(239, 68, 68)
+				ui.statusLabel.Text = "Waiting for previous instance"
+				ui.statusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
 				ui.detailStatusLabel.Text = reason
-				ui.detailStatusLabel.TextColor3 = Color3.fromRGB(239, 68, 68)
-				warn(`[robloxstudio-mcp] /ready rejected for {instanceId}/{readyRole}: {reason}`)
+				ui.detailStatusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
+				if shouldLog then
+					warn(`[robloxstudio-mcp] /ready rejected for {instanceId}/{readyRole}: {reason}`)
+				end
 				return nil
 			end
-			warn(`[robloxstudio-mcp] /ready rejected for {instanceId}/{readyRole}: {reason}`)
+			if shouldLog then
+				warn(`[robloxstudio-mcp] /ready rejected for {instanceId}/{readyRole}: {reason}`)
+			end
 			return nil
 		end
+		retryingDuplicateReady = false
 		local parseOk, readyData = pcall(function()
 			return HttpService:JSONDecode(readyResult.Body)
 		end)
@@ -1413,9 +1439,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "2.22.0" is replaced with the package version at package time
+	-- "2.22.2" is replaced with the package version at package time
 	-- (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
-	return `{tostring(h)}-2.22.0`
+	return `{tostring(h)}-2.22.2`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -10425,6 +10451,41 @@ end
 local function nowSec()
 	return DateTime.now().UnixTimestampMillis / 1000
 end
+-- Studio occasionally exposes binary-bearing Output messages through
+-- LogService (for example, plugin hydration diagnostics containing raw CSG
+-- data). HttpService:JSONEncode rejects those strings outright. Preserve all
+-- valid UTF-8 verbatim and make only malformed bytes JSON-safe and visible.
+local function escapeInvalidUtf8(msg)
+	local valid = utf8.len(msg)
+	-- Roblox currently returns nil (not the false declared by @rbxts/types)
+	-- when it encounters a malformed sequence. A numeric result is the only
+	-- portable success discriminator across both representations.
+	if type(valid) == "number" then
+		return msg
+	end
+	local parts = {}
+	local cursor = 1
+	while cursor <= #msg do
+		local suffixValid, invalidPosition = utf8.len(msg, cursor)
+		if type(suffixValid) == "number" then
+			local _arg0 = string.sub(msg, cursor)
+			table.insert(parts, _arg0)
+			break
+		end
+		if not (type(invalidPosition) == "number") then
+			break
+		end
+		if invalidPosition > cursor then
+			local _arg0 = string.sub(msg, cursor, invalidPosition - 1)
+			table.insert(parts, _arg0)
+		end
+		local invalidByte = string.byte(msg, invalidPosition)
+		local _arg0 = string.format("\\x%02X", invalidByte)
+		table.insert(parts, _arg0)
+		cursor = invalidPosition + 1
+	end
+	return table.concat(parts, "")
+end
 local function dropOldestUntilFits(incomingBytes)
 	while #entries > 0 and (totalBytes + incomingBytes > MAX_BYTES or #entries >= HARD_ENTRY_CAP) do
 		local dropped = table.remove(entries, 1)
@@ -10436,37 +10497,44 @@ local function pushEntry(msg, t, ts)
 	if ts == nil then
 		ts = nowSec()
 	end
-	local bytes = #msg
+	local safeMessage = escapeInvalidUtf8(msg)
+	local bytes = #safeMessage
 	dropOldestUntilFits(bytes)
 	local _arg0 = {
 		seq = nextSeq,
 		ts = ts,
 		level = levelTag(t),
-		message = msg,
+		message = safeMessage,
 	}
 	table.insert(entries, _arg0)
 	nextSeq += 1
 	totalBytes += bytes
 end
 local function seedRuntimeHistory()
-	if not RunService:IsRunning() then
-		return nil
-	end
 	local ok, history = pcall(function()
 		return LogService:GetLogHistory()
 	end)
 	if not ok then
 		return nil
 	end
+	local isEdit = not RunService:IsRunning()
+	-- GetLogHistory timestamps and DateTime.now() share Unix time, while
+	-- os.clock() is elapsed time for this Studio process. Their difference is
+	-- therefore the process launch boundary. Edit-mode history is filtered to
+	-- that boundary so startup errors from this launch are recovered without
+	-- importing history left by an earlier Studio process.
+	local processStartedAt = nowSec() - os.clock()
 	for _, entry in history do
 		local _message = entry.message
 		if not (type(_message) == "string") then
 			continue
 		end
-		local _exp = entry.message
-		local _exp_1 = entry.messageType
 		local _timestamp = entry.timestamp
-		pushEntry(_exp, _exp_1, if type(_timestamp) == "number" then entry.timestamp else nil)
+		local timestamp = if type(_timestamp) == "number" then entry.timestamp else nil
+		if isEdit and (timestamp == nil or timestamp < processStartedAt - 1) then
+			continue
+		end
+		pushEntry(entry.message, entry.messageType, timestamp)
 	end
 end
 local function install()
@@ -10477,9 +10545,9 @@ local function install()
 		return nil
 	end
 	installed = true
-	-- Play peers can emit startup logs before the plugin finishes loading.
-	-- Seed from per-DataModel LogHistory so get_runtime_logs can still see
-	-- those early messages; skip edit mode to avoid stale prior-session logs.
+	-- Every peer can emit startup logs before the plugin finishes loading.
+	-- Seed from per-DataModel LogHistory so get_runtime_logs can still see them;
+	-- edit history is bounded to the current Studio process above.
 	seedRuntimeHistory()
 	LogService.MessageOut:Connect(function(msg, t)
 		pushEntry(msg, t)
@@ -10745,7 +10813,7 @@ return {
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "2.22.0"
+local CURRENT_VERSION = "2.22.2"
 local PLUGIN_VARIANT = "main"
 local BASE_PORT = 58741
 local function createConnection(port)

package/studio-plugin/src/modules/Communication.ts

@@ -53,11 +53,11 @@ function computeInstanceId(): string {
 }
 
 let assignedRole: string | undefined;
-let duplicateInstanceRole = false;
 let hasVersionMismatch = false;
 let lastVersionMismatchWarningKey: string | undefined;
 let lastReadyInstanceId: string | undefined;
 const readyFailureLogKeys = new Set<string>();
+let retryingDuplicateReady = false;
 
 // Cache the published place name from MarketplaceService:GetProductInfo so
 // /ready can carry a friendly identifier (e.g. "Natural Disasters") distinct
@@ -197,14 +197,27 @@ function processRequest(request: RequestPayload): unknown {
 }
 
 function sendResponse(conn: Connection, requestId: string, responseData: unknown) {
-	pcall(() => {
-		HttpService.RequestAsync({
-			Url: `${conn.serverUrl}/response`,
-			Method: "POST",
-			Headers: { "Content-Type": "application/json" },
-			Body: HttpService.JSONEncode({ requestId, response: responseData }),
+	const responseUrl = `${conn.serverUrl}/response`;
+	const [encodeOk, encoded] = pcall(() => HttpService.JSONEncode({ requestId, response: responseData }));
+	const body = encodeOk
+		? encoded
+		: HttpService.JSONEncode({
+			requestId,
+			error: `Plugin response serialization failed: ${tostring(encoded)}`,
 		});
-	});
+	if (!encodeOk) {
+		warn(`[robloxstudio-mcp] Failed to serialize response ${requestId}: ${tostring(encoded)}`);
+	}
+
+	const [requestOk, requestResult] = pcall(() => HttpService.RequestAsync({
+		Url: responseUrl,
+		Method: "POST",
+		Headers: { "Content-Type": "application/json" },
+		Body: body,
+	}));
+	if (!requestOk || !requestResult.Success) {
+		warn(`[robloxstudio-mcp] Failed to deliver response ${requestId}: ${HttpDiagnostics.formatRequestFailure(responseUrl, requestOk, requestResult)}`);
+	}
 }
 
 function getConnectionStatus(): string {
@@ -248,9 +261,12 @@ function ensureIdentityWatcher(conn: Connection): void {
 }
 
 function sendReady(conn: Connection): void {
-	if (duplicateInstanceRole) return; // stop retrying once the server has rejected us
 	const now = tick();
-	if (now - lastReadyPostAt < 2) return; // throttle to ≤1 /ready every 2s
+	// Normal identity refreshes stay conservatively throttled. Once a stale
+	// predecessor causes 409, retry once per second so takeover follows the
+	// server's short inactivity lease without another two seconds of jitter.
+	const readyInterval = retryingDuplicateReady ? 1 : 2;
+	if (now - lastReadyPostAt < readyInterval) return;
 	lastReadyPostAt = now;
 	const instanceId = computeInstanceId();
 	task.spawn(() => {
@@ -278,28 +294,39 @@ function sendReady(conn: Connection): void {
 		const readyRole = detectRole();
 		const readyLogKey = `${conn.serverUrl}|${instanceId}|${readyRole}`;
 		if (!readyOk) {
+			const shouldLog = !readyFailureLogKeys.has(readyLogKey);
 			readyFailureLogKeys.add(readyLogKey);
-			warn(`[robloxstudio-mcp] /ready failed for ${instanceId}/${readyRole}: ${HttpDiagnostics.formatRequestFailure(readyUrl, readyOk, readyResult)}`);
+			if (shouldLog) {
+				warn(`[robloxstudio-mcp] /ready failed for ${instanceId}/${readyRole}: ${HttpDiagnostics.formatRequestFailure(readyUrl, readyOk, readyResult)}`);
+			}
 			return;
 		}
 		if (!readyResult.Success) {
 			const reason = HttpDiagnostics.formatRequestFailure(readyUrl, true, readyResult);
+			const shouldLog = !readyFailureLogKeys.has(readyLogKey);
 			readyFailureLogKeys.add(readyLogKey);
-			// 409 = duplicate_instance_role. Surface in UI and stop polling.
+			// A predecessor can remain registered briefly when Studio exits before
+			// its asynchronous /disconnect completes. Keep polling and retrying
+			// /ready: the server will take us over once the predecessor has stopped
+			// polling, while a genuinely active duplicate continues to hold routing.
 			if (readyResult.StatusCode === 409) {
-				duplicateInstanceRole = true;
-				conn.isActive = false;
+				retryingDuplicateReady = true;
 				const ui = UI.getElements();
-				ui.statusLabel.Text = "Duplicate instance";
-				ui.statusLabel.TextColor3 = Color3.fromRGB(239, 68, 68);
+				ui.statusLabel.Text = "Waiting for previous instance";
+				ui.statusLabel.TextColor3 = Color3.fromRGB(245, 158, 11);
 				ui.detailStatusLabel.Text = reason;
-				ui.detailStatusLabel.TextColor3 = Color3.fromRGB(239, 68, 68);
-				warn(`[robloxstudio-mcp] /ready rejected for ${instanceId}/${readyRole}: ${reason}`);
+				ui.detailStatusLabel.TextColor3 = Color3.fromRGB(245, 158, 11);
+				if (shouldLog) {
+					warn(`[robloxstudio-mcp] /ready rejected for ${instanceId}/${readyRole}: ${reason}`);
+				}
 				return;
 			}
-			warn(`[robloxstudio-mcp] /ready rejected for ${instanceId}/${readyRole}: ${reason}`);
+			if (shouldLog) {
+				warn(`[robloxstudio-mcp] /ready rejected for ${instanceId}/${readyRole}: ${reason}`);
+			}
 			return;
 		}
+		retryingDuplicateReady = false;
 		const [parseOk, readyData] = pcall(
 			() => HttpService.JSONDecode(readyResult.Body) as ReadyResponse,
 		);

package/studio-plugin/src/modules/RuntimeLogBuffer.ts

@@ -46,6 +46,37 @@ function nowSec(): number {
 	return DateTime.now().UnixTimestampMillis / 1000;
 }
 
+// Studio occasionally exposes binary-bearing Output messages through
+// LogService (for example, plugin hydration diagnostics containing raw CSG
+// data). HttpService:JSONEncode rejects those strings outright. Preserve all
+// valid UTF-8 verbatim and make only malformed bytes JSON-safe and visible.
+function escapeInvalidUtf8(msg: string): string {
+	const [valid] = utf8.len(msg);
+	// Roblox currently returns nil (not the false declared by @rbxts/types)
+	// when it encounters a malformed sequence. A numeric result is the only
+	// portable success discriminator across both representations.
+	if (typeIs(valid, "number")) return msg;
+
+	const parts: string[] = [];
+	let cursor = 1;
+	while (cursor <= msg.size()) {
+		const [suffixValid, invalidPosition] = utf8.len(msg, cursor);
+		if (typeIs(suffixValid, "number")) {
+			parts.push(string.sub(msg, cursor));
+			break;
+		}
+		if (!typeIs(invalidPosition, "number")) break;
+
+		if (invalidPosition > cursor) {
+			parts.push(string.sub(msg, cursor, invalidPosition - 1));
+		}
+		const [invalidByte] = string.byte(msg, invalidPosition);
+		parts.push(string.format("\\x%02X", invalidByte));
+		cursor = invalidPosition + 1;
+	}
+	return parts.join("");
+}
+
 function dropOldestUntilFits(incomingBytes: number): void {
 	while (
 		entries.size() > 0 &&
@@ -58,13 +89,14 @@ function dropOldestUntilFits(incomingBytes: number): void {
 }
 
 function pushEntry(msg: string, t: Enum.MessageType, ts = nowSec()): void {
-	const bytes = msg.size();
+	const safeMessage = escapeInvalidUtf8(msg);
+	const bytes = safeMessage.size();
 	dropOldestUntilFits(bytes);
 	entries.push({
 		seq: nextSeq,
 		ts,
 		level: levelTag(t),
-		message: msg,
+		message: safeMessage,
 	});
 	nextSeq += 1;
 	totalBytes += bytes;
@@ -77,14 +109,21 @@ interface LogHistoryEntry {
 }
 
 function seedRuntimeHistory(): void {
-	if (!RunService.IsRunning()) return;
-
 	const [ok, history] = pcall(() => LogService.GetLogHistory() as LogHistoryEntry[]);
 	if (!ok) return;
+	const isEdit = !RunService.IsRunning();
+	// GetLogHistory timestamps and DateTime.now() share Unix time, while
+	// os.clock() is elapsed time for this Studio process. Their difference is
+	// therefore the process launch boundary. Edit-mode history is filtered to
+	// that boundary so startup errors from this launch are recovered without
+	// importing history left by an earlier Studio process.
+	const processStartedAt = nowSec() - os.clock();
 
 	for (const entry of history) {
 		if (!typeIs(entry.message, "string")) continue;
-		pushEntry(entry.message, entry.messageType, typeIs(entry.timestamp, "number") ? entry.timestamp : undefined);
+		const timestamp = typeIs(entry.timestamp, "number") ? entry.timestamp : undefined;
+		if (isEdit && (timestamp === undefined || timestamp < processStartedAt - 1)) continue;
+		pushEntry(entry.message, entry.messageType, timestamp);
 	}
 }
 
@@ -92,9 +131,9 @@ function install(): void {
 	if (installed) return;
 	if (!RunService.IsStudio()) return;
 	installed = true;
-	// Play peers can emit startup logs before the plugin finishes loading.
-	// Seed from per-DataModel LogHistory so get_runtime_logs can still see
-	// those early messages; skip edit mode to avoid stale prior-session logs.
+	// Every peer can emit startup logs before the plugin finishes loading.
+	// Seed from per-DataModel LogHistory so get_runtime_logs can still see them;
+	// edit history is bounded to the current Studio process above.
 	seedRuntimeHistory();
 	LogService.MessageOut.Connect((msg, t) => {
 		pushEntry(msg, t);