@chrrxs/robloxstudio-mcp 3.1.4 → 3.1.6

package/studio-plugin/MCPPlugin.rbxmx

@@ -607,6 +607,7 @@ local HttpService = _services.HttpService
 local Players = _services.Players
 local ReplicatedStorage = _services.ReplicatedStorage
 local RunService = _services.RunService
+local Workspace = _services.Workspace
 local RuntimeLogBuffer = TS.import(script, script.Parent, "RuntimeLogBuffer")
 local MemoryHandlers = TS.import(script, script.Parent, "handlers", "MemoryHandlers")
 local SceneAnalysisHandlers = TS.import(script, script.Parent, "handlers", "SceneAnalysisHandlers")
@@ -633,6 +634,11 @@ local mcpUrl = DEFAULT_MCP_URL
 local BROKER_NAME = "__MCPClientBroker"
 local BROKER_OWNER_ATTRIBUTE = "__MCPBrokerOwner"
 local CLIENT_IDENTITY_KIND = "identity"
+-- A normal capture needs at most 15s sampling + 5s waiting for profiler data.
+-- Leave room for processing, then return a diagnostic before the outer 30s wait.
+local CLIENT_PROFILER_MAX_WAIT_SECONDS = 25
+local CLIENT_PROFILER_RESPONSE_RESERVE_SECONDS = 5
+local CLIENT_PROFILER_POLL_SECONDS = 0.05
 -- Endpoints the server-peer broker is allowed to forward to the client peer.
 -- Each requires the client peer's plugin VM (because the buffer / require
 -- cache / etc. lives there) so the server peer alone can't satisfy them.
@@ -649,6 +655,7 @@ local CLIENT_BROKER_ALLOWED_ENDPOINTS = {
 	["/api/multiplayer-test-leave-client"] = true,
 	["/api/capture-begin"] = true,
 	["/api/capture-studio"] = true,
+	["/api/capture-markers"] = true,
 	["/api/simulate-mouse-input"] = true,
 	["/api/simulate-keyboard-input"] = true,
 	["/api/focus-viewport"] = true,
@@ -836,6 +843,32 @@ local function setupClientBroker(attempt)
 			return BreakpointHandlers.breakpoints(payload.data or {})
 		end
 		if payload and payload.endpoint == "/api/capture-script-profiler" then
+			-- os.clock is VM-local. Only the engine-synchronized server clock can
+			-- reject an envelope that expired while travelling to this client.
+			local _remainingMs = payload.remainingMs
+			local _condition_1 = type(_remainingMs) == "number"
+			if _condition_1 then
+				_condition_1 = payload.remainingMs <= 0
+			end
+			local _condition_2 = _condition_1
+			if not _condition_2 then
+				local _expiresAtServerTime = payload.expiresAtServerTime
+				local _condition_3 = type(_expiresAtServerTime) == "number"
+				if _condition_3 then
+					_condition_3 = Workspace:GetServerTimeNow() >= payload.expiresAtServerTime
+				end
+				_condition_2 = _condition_3
+			end
+			if _condition_2 then
+				return {
+					success = false,
+					error = "client_broker_expired",
+					stage = "client_broker_pre_start",
+					requestId = payload.requestId,
+					executionOutcome = "not_executed",
+					message = "Client profiler request expired before capture started.",
+				}
+			end
 			return ScriptProfilerHandlers.captureScriptProfiler(payload.data or {})
 		end
 		if payload and payload.endpoint == "/api/capture-micro-profiler" then
@@ -855,6 +888,9 @@ local function setupClientBroker(attempt)
 				return CaptureHandlers.captureStudio(payload.data or {})
 			end)
 		end
+		if payload and payload.endpoint == "/api/capture-markers" then
+			return CaptureHandlers.captureMarkers(payload.data or {})
+		end
 		if payload and payload.endpoint == CaptureTransfer.READ_ENDPOINT then
 			return CaptureTransfer.read(payload.data or {})
 		end
@@ -1133,7 +1169,112 @@ local function refreshAllProxyRegistrations()
 		task.spawn(registerProxyEntry, entry)
 	end
 end
-local function dispatchClientRequest(peerId, target, endpoint, data)
+local function invokeClientProfiler(entry, target, data, context)
+	local startedAt = os.clock()
+	local deadlineAt = math.min(context.deadlineAt - CLIENT_PROFILER_RESPONSE_RESERVE_SECONDS, startedAt + CLIENT_PROFILER_MAX_WAIT_SECONDS)
+	local failure = function(code, stage, outcome, detail)
+		context.executionOutcome = outcome
+		return {
+			success = false,
+			error = code,
+			stage = stage,
+			requestId = context.requestId,
+			peerId = entry.peerId,
+			target = target,
+			elapsedMs = math.floor(math.max(0, os.clock() - startedAt) * 1000),
+			executionOutcome = outcome,
+			message = if outcome == "unknown" then `{detail} Only the broker's local wait ended; remote execution may still be running. No retry was started.` else `{detail} Client profiler execution was not started.`,
+		}
+	end
+	if context.isCancelled() then
+		return failure("client_broker_cancelled", "client_broker_admission", "not_executed", "Request cancelled before client invocation.")
+	end
+	if startedAt >= deadlineAt then
+		return failure("client_broker_timeout", "client_broker_admission", "not_executed", "Insufficient request budget for client invocation and response delivery.")
+	end
+	local interrupted = function()
+		if context.isCancelled() then
+			return failure("client_broker_cancelled", "client_broker_wait", "unknown", "Request cancelled while awaiting the client profiler response.")
+		end
+		local _peerId = entry.peerId
+		local _condition = proxyByPeerId[_peerId] ~= entry
+		if not _condition then
+			local _player = entry.player
+			_condition = proxyByPlayer[_player] ~= entry
+			if not _condition then
+				_condition = entry.player.Parent == nil or entry.remote.Parent == nil or not RunService:IsRunning()
+			end
+		end
+		if _condition then
+			return failure("client_broker_disconnected", "client_broker_wait", "unknown", "Client proxy disconnected while awaiting the profiler response.")
+		end
+		if os.clock() >= deadlineAt then
+			return failure("client_broker_timeout", "client_broker_wait", "unknown", "Client profiler round-trip exceeded its response deadline.")
+		end
+		return nil
+	end
+	local remainingMs = math.max(0, math.floor((deadlineAt - os.clock()) * 1000))
+	local envelope = {
+		endpoint = "/api/capture-script-profiler",
+		data = data,
+		requestId = context.requestId,
+		remainingMs = remainingMs,
+		expiresAtServerTime = Workspace:GetServerTimeNow() + remainingMs / 1000,
+	}
+	local settled = false
+	local response
+	context.executionOutcome = "unknown"
+	local invocation = task.spawn(function()
+		local ok, result = pcall(function()
+			return entry.remote:InvokeClient(entry.player, envelope)
+		end)
+		-- Cancelling a suspended engine wait is best effort. A late return must
+		-- never replace the chosen outcome, even if task.cancel was unavailable.
+		if settled then
+			return nil
+		end
+		local interruption = interrupted()
+		if interruption ~= nil then
+			response = interruption
+		elseif not ok then
+			response = failure("client_broker_invoke_failed", "client_broker_wait", "unknown", `InvokeClient failed: {tostring(result)}`)
+		elseif result == nil then
+			response = failure("client_broker_nil_response", "client_broker_wait", "unknown", "Client profiler returned no response.")
+		else
+			response = result
+			-- Only this endpoint's broker pre-start refusal establishes that no
+			-- remote capture ran. Other responses retain normal handler outcome
+			-- classification; arbitrary payload fields cannot override transport.
+			context.executionOutcome = nil
+			if type(result) == "table" then
+				local reply = result
+				if reply.error == "client_broker_expired" and reply.stage == "client_broker_pre_start" then
+					context.executionOutcome = "not_executed"
+				end
+			end
+		end
+		settled = true
+	end)
+	while not settled do
+		local interruption = interrupted()
+		if interruption ~= nil then
+			response = interruption
+			settled = true
+			-- This only releases the local coroutine; it cannot stop the remote
+			-- OnClientInvoke callback or roll back an already-started capture.
+			pcall(function()
+				return task.cancel(invocation)
+			end)
+			break
+		end
+		task.wait(math.min(CLIENT_PROFILER_POLL_SECONDS, deadlineAt - os.clock()))
+	end
+	return response
+end
+local function dispatchClientRequest(peerId, target, endpoint, data, context)
+	if endpoint == "/api/capture-script-profiler" then
+		context.executionOutcome = "not_executed"
+	end
 	local _peerId = peerId
 	local entry = proxyByPeerId[_peerId]
 	local _condition = not entry
@@ -1173,6 +1314,9 @@ local function dispatchClientRequest(peerId, target, endpoint, data)
 			error = `Client-proxy does not forward {endpoint}. Allowed: {table.concat(allowed, ", ")}.`,
 		}
 	end
+	if endpoint == "/api/capture-script-profiler" then
+		return invokeClientProfiler(entry, target, data, context)
+	end
 	if endpoint == "/api/capture-studio" then
 		return CaptureTransfer.receive(function(captureEndpoint, captureData)
 			return entry.remote:InvokeClient(entry.player, {
@@ -1332,6 +1476,7 @@ local routeMap = {
 	["/api/capture-studio"] = CaptureHandlers.captureStudio,
 	["/api/capture-begin"] = CaptureHandlers.captureBegin,
 	["/api/capture-read"] = CaptureHandlers.captureRead,
+	["/api/capture-markers"] = CaptureHandlers.captureMarkers,
 	["/api/simulate-mouse-input"] = InputHandlers.simulateMouseInput,
 	["/api/simulate-keyboard-input"] = InputHandlers.simulateKeyboardInput,
 	["/api/find-and-replace-in-scripts"] = ScriptHandlers.findAndReplaceInScripts,
@@ -1372,7 +1517,7 @@ local function getConnectionStatus()
 end
 local function dispatchSocketRequest(request, context)
 	if request.peerId ~= PluginSession.peerId then
-		return ClientBroker.dispatchClientRequest(request.peerId, request.target, request.endpoint, request.data)
+		return ClientBroker.dispatchClientRequest(request.peerId, request.target, request.endpoint, request.data, context)
 	end
 	local _condition = assignedRole
 	if _condition == nil then
@@ -1427,34 +1572,9 @@ local function handleTransportUpdate(update)
 	if not conn.isActive then
 		return nil
 	end
-	if update.state == "open" then
-		conn.lastHttpOk = true
-		conn.lastMcpOk = false
-		conn.consecutiveFailures = 0
-		conn.currentRetryDelay = 0.5
-		conn.mcpWaitStartTime = tick()
-	else
-		conn.lastHttpOk = false
-		conn.lastMcpOk = false
-		conn.consecutiveFailures = update.attempt
-		if update.retryDelay > 0 then
-			conn.currentRetryDelay = update.retryDelay
-		end
-		conn.mcpWaitStartTime = nil
-	end
+	State.applyTransportUpdate(update, tick())
 	UI.updateUIState()
 	UI.updateToolbarIcon()
-	if update.state == "waiting-duplicate" then
-		local ui = UI.getElements()
-		ui.statusLabel.Text = "Waiting for previous instance"
-		ui.statusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
-		local _condition = update.detail
-		if _condition == nil then
-			_condition = "The previous plugin instance is still active."
-		end
-		ui.detailStatusLabel.Text = _condition
-		ui.detailStatusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
-	end
 end
 local nameChangeConn
 local placeIdChangeConn
@@ -1505,6 +1625,7 @@ local function activatePlugin()
 	conn.lastHttpOk = false
 	conn.lastMcpOk = false
 	conn.mcpWaitStartTime = nil
+	State.clearTransportDiagnostics()
 	local normalizedUrl = ServerUrlSettings.normalizeServerUrl(ui.urlInput.Text)
 	conn.serverUrl = if normalizedUrl ~= "" then normalizedUrl else conn.serverUrl
 	if conn.serverUrl == "" then
@@ -1527,6 +1648,7 @@ local function activatePlugin()
 		onTransportUpdate = handleTransportUpdate,
 	})
 	if not conn.heartbeatConnection then
+		local lastDiagnosticUpdate = tick()
 		conn.heartbeatConnection = RunService.Heartbeat:Connect(function()
 			if initialRole == "server" and not RunService:IsRunning() then
 				ClientBroker.disconnectAllProxies()
@@ -1539,6 +1661,11 @@ local function activatePlugin()
 				PluginSession.invalidatePlaceName()
 				StudioWebSocket.refresh()
 			end
+			local now = tick()
+			if conn.nextRetryAt ~= nil and now - lastDiagnosticUpdate >= 0.25 then
+				lastDiagnosticUpdate = now
+				UI.updateUIState()
+			end
 		end)
 	end
 	if initialRole == "edit" then
@@ -1555,6 +1682,7 @@ function deactivatePlugin()
 	conn.lastHttpOk = false
 	conn.lastMcpOk = false
 	conn.mcpWaitStartTime = nil
+	State.clearTransportDiagnostics()
 	StudioWebSocket.stop()
 	disconnectIdentityWatchers()
 	if initialRole == "server" then
@@ -1814,9 +1942,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "3.1.4" is replaced with the package version at package time
+	-- "3.1.6" is replaced with the package version at package time
 	-- (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
-	return `{tostring(h)}-3.1.4`
+	return `{tostring(h)}-3.1.6`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -2930,6 +3058,8 @@ local RenderMonitor = TS.import(script, script.Parent.Parent, "RenderMonitor")
 local CaptureService = game:GetService("CaptureService")
 local AssetService = game:GetService("AssetService")
 local Workspace = game:GetService("Workspace")
+local CoreGui = game:GetService("CoreGui")
+local RunService = game:GetService("RunService")
 local MAX_TILE_SIZE = 1024
 local MAX_RAW_PIXEL_BYTES = 36 * 1024 * 1024
 local MAX_CREATED_IMAGE_DIM = 2048
@@ -2941,10 +3071,16 @@ local PAD_BYTE = (string.byte("="))
 -- ViewportSize, which is exactly the coordinate space simulate_mouse_input
 -- expects. It is gated behind Studio FFlags and is missing from @rbxts/types,
 -- hence the local structural declarations below.
+-- Studio exposes this API at runtime, but the installed @rbxts/types predates it.
 -- Unchecked cast, single reason: these enums exist in Studio but are missing
 -- from @rbxts/types, so the global Enum table has to be read dynamically.
 local ENUM_TABLE = Enum
 local STUDIO_CAPTURE_FORMATS = ENUM_TABLE.StudioCaptureScreenshotFormat
+local _FIT_TO_WINDOW = ENUM_TABLE.DeviceSimulatorScalingMode
+if _FIT_TO_WINDOW ~= nil then
+	_FIT_TO_WINDOW = _FIT_TO_WINDOW.FitToWindow
+end
+local FIT_TO_WINDOW = _FIT_TO_WINDOW
 -- Measured on a 1980x1032 viewport: RGBA8 completes in ~0.16s and PNG in ~1s.
 -- A capture that is still Pending well past that never completes (it happens
 -- while a playtest owns the renderer), so we stop waiting and let the caller
@@ -3059,7 +3195,11 @@ end
 -- pixels back is blocked, but capturing is not). The returned rbxtemp:// id is
 -- a process-scoped handle: it can be dereferenced from a DIFFERENT, more
 -- privileged DM (the edit DM) — see captureRead.
+local withViewportRead, captureScreenshotFrame
 local function doCaptureScreenshot()
+	return withViewportRead(captureScreenshotFrame)
+end
+function captureScreenshotFrame()
 	-- Fast-fail with a clear reason if the window isn't rendering — otherwise
 	-- CaptureScreenshot's callback never fires and we'd block for the full 10s.
 	local notRendering = RenderMonitor.notRenderingReason()
@@ -3095,8 +3235,12 @@ local function readContentToBase64(contentId)
 		return AssetService:CreateEditableImageAsync(Content.fromUri(contentId))
 	end)
 	if not editableOk then
+		-- Lead with Roblox's own message: the Game Settings toggle is only one of
+		-- the reasons this can fail (temporary-texture privilege and multiplayer
+		-- client handles are others), and telling someone who already enabled
+		-- it to enable it again is a dead end.
 		return {
-			error = `Failed to create EditableImage from screenshot. Enable EditableImage API: Game Settings > Security > 'Allow Mesh / Image APIs'. ({tostring(editableResult)})`,
+			error = `Failed to create EditableImage from screenshot: {tostring(editableResult)}. ` .. "If that mentions permissions, check Game Settings > Security > 'Allow Mesh / Image APIs'.",
 		}
 	end
 	local sourceImage = editableResult
@@ -3168,7 +3312,13 @@ end
 -- cannot capture right now (missing FFlag, permission not granted, or this
 -- DataModel is not the active one) so the caller can fall back to the
 -- CaptureService + EditableImage path.
+local captureStudioFrame
 local function doStudioCapture(wantPng)
+	return withViewportRead(function()
+		return captureStudioFrame(wantPng)
+	end)
+end
+function captureStudioFrame(wantPng)
 	if STUDIO_CAPTURE_FORMATS == nil then
 		return nil
 	end
@@ -3290,12 +3440,379 @@ local function captureRead(requestData)
 	end
 	return readContentToBase64(contentId)
 end
+-- Viewport corner markers for the host-side window capture fallback.
+--
+-- Roblox's own capture APIs can be unavailable for the play viewport:
+-- StudioCaptureService reports CanCaptureScreenshot() == false in the play
+-- client (RequestScreenshotPermissionAsync raises "Feature not supported
+-- yet"), and CaptureService:CaptureScreenshot hands back a fully black frame
+-- there on some Studio builds (observed with the Vulkan renderer). When that
+-- happens the MCP server grabs the whole Studio window through the host OS
+-- instead and needs to know where the 3D viewport sits inside that window.
+-- Four small magenta squares pinned to the viewport corners give it an exact,
+-- DPI-independent answer; the server hides them again before the real capture.
+local MARKER_GUI_NAME = "__MCPCaptureMarkers"
+local MARKER_SIZE = 12
+local MARKER_COLOR = Color3.fromRGB(255, 0, 255)
+-- Safety net: the server always hides the markers itself, but if it dies
+-- mid-capture the viewport must not stay decorated.
+local MARKER_AUTO_HIDE_SECONDS = 15
+local MARKER_RENDER_FRAMES = 3
+local MARKER_RENDER_TIMEOUT = 2
+local CAPTURE_AUTO_FINISH_SECONDS = 60
+local VIEWPORT_ACQUIRE_TIMEOUT = 25
+local activeMarkerCapture
+local activeViewportReads = 0
+function withViewportRead(readFrame)
+	local start = os.clock()
+	while activeMarkerCapture ~= nil do
+		if os.clock() - start >= VIEWPORT_ACQUIRE_TIMEOUT then
+			return {
+				error = "Timed out waiting for the active host capture to restore the viewport; retry capture.",
+			}
+		end
+		task.wait(0.03)
+	end
+	-- No yield between observing the writer and acquiring this reader.
+	activeViewportReads += 1
+	local ok, result = pcall(readFrame)
+	activeViewportReads -= 1
+	if not ok then
+		return {
+			error = `Viewport capture failed: {tostring(result)}`,
+		}
+	end
+	return result
+end
+local function markerAccessError(action, captureId)
+	local capture = activeMarkerCapture
+	if captureId ~= nil then
+		local _captureId = captureId
+		local _condition = not (type(_captureId) == "string")
+		if not _condition then
+			_condition = captureId == ""
+		end
+		if _condition then
+			return "A non-empty captureId is required."
+		end
+		if capture == nil or capture.captureId ~= captureId or capture.expired then
+			return "The host capture token is stale or expired; discard this capture and prepare a new transaction."
+		end
+		if capture.busy then
+			return "The host capture is still preparing or restoring; retry after that operation completes."
+		end
+	elseif capture ~= nil and (action == "show" or action == "hide") then
+		return "An active host capture owns the viewport markers; supply its captureId."
+	end
+	return nil
+end
+local function viewportSize()
+	local camera = Workspace.CurrentCamera
+	if camera == nil then
+		return nil
+	end
+	local viewport = camera.ViewportSize
+	return {
+		viewportWidth = math.max(1, math.floor(viewport.X)),
+		viewportHeight = math.max(1, math.floor(viewport.Y)),
+	}
+end
+local function hideMarkers()
+	local existing = CoreGui:FindFirstChild(MARKER_GUI_NAME)
+	if existing ~= nil then
+		existing:Destroy()
+	end
+end
+-- Blocks until the markers have been composited into a few rendered frames
+-- (bounded, so a non-rendering window cannot hang the request).
+local function waitForRenderedFrames()
+	local frames = 0
+	local ok, connection = pcall(function()
+		return RunService.RenderStepped:Connect(function()
+			frames += 1
+		end)
+	end)
+	if not ok then
+		return 0
+	end
+	local start = os.clock()
+	while frames < MARKER_RENDER_FRAMES and os.clock() - start < MARKER_RENDER_TIMEOUT do
+		task.wait(0.03)
+	end
+	connection:Disconnect()
+	return frames
+end
+local function finishMarkerCapture(captureId)
+	local capture = activeMarkerCapture
+	-- A delayed retry or safety callback must never touch another capture's GUI.
+	if capture == nil or capture.captureId ~= captureId then
+		return {
+			success = true,
+			captureId = captureId,
+			stale = true,
+		}
+	end
+	if capture.busy then
+		return {
+			error = "Host capture is still preparing or restoring; retry finish with the same captureId.",
+			captureId = captureId,
+		}
+	end
+	capture.busy = true
+	local ok, failure = pcall(function()
+		hideMarkers()
+		local simulator = capture.simulator
+		local originalMode = capture.scalingMode
+		if capture.restorePending and simulator ~= nil and originalMode ~= nil then
+			-- Never switch devices or overwrite a mode the user changed mid-capture.
+			if simulator:GetDeviceAsync() == capture.deviceId and simulator:GetScalingModeAsync() == FIT_TO_WINDOW and simulator:GetDeviceAsync() == capture.deviceId then
+				simulator:SetScalingModeAsync(originalMode)
+				-- A minimized window may not render; the restored mode still releases
+				-- the transaction so the next capture can proceed when it is visible.
+				waitForRenderedFrames()
+			end
+			capture.restorePending = false
+		end
+	end)
+	capture.busy = false
+	if not ok then
+		return {
+			error = `Could not finish host capture or restore device scaling: {tostring(failure)} Retry finish with captureId {captureId}, or restore the simulator scaling mode manually.`,
+			captureId = captureId,
+		}
+	end
+	activeMarkerCapture = nil
+	return {
+		success = true,
+		captureId = captureId,
+	}
+end
+local function prepareMarkerCapture()
+	local start = os.clock()
+	while activeMarkerCapture ~= nil or activeViewportReads > 0 do
+		if os.clock() - start >= VIEWPORT_ACQUIRE_TIMEOUT then
+			return {
+				error = "Timed out waiting for another viewport capture to finish; retry host capture.",
+			}
+		end
+		task.wait(0.03)
+	end
+	local notRendering = RenderMonitor.notRenderingReason()
+	if notRendering ~= nil then
+		return {
+			error = notRendering,
+		}
+	end
+	local size = viewportSize()
+	if size == nil then
+		return {
+			error = "No CurrentCamera; cannot prepare host capture.",
+		}
+	end
+	local capture = {
+		captureId = game:GetService("HttpService"):GenerateGUID(false),
+		restorePending = false,
+		busy = true,
+		expired = false,
+	}
+	activeMarkerCapture = capture
+	task.delay(CAPTURE_AUTO_FINISH_SECONDS, function()
+		if activeMarkerCapture ~= capture then
+			return nil
+		end
+		capture.expired = true
+		-- A yielding prepare owns the state until it resumes and rolls back.
+		if capture.busy then
+			return nil
+		end
+		local result = finishMarkerCapture(capture.captureId)
+		if result.error ~= nil then
+			warn(result.error)
+		end
+	end)
+	local ok, failure = pcall(function()
+		-- Unchecked cast: the live simulator service is missing from this SDK's
+		-- GetService overloads; the structural return type describes only APIs used here.
+		local dynamicGame = game
+		local simulator = dynamicGame:GetService("StudioDeviceSimulatorService")
+		capture.simulator = simulator
+		capture.deviceId = simulator:GetDeviceAsync()
+		if capture.deviceId == "default" then
+			return nil
+		end
+		if FIT_TO_WINDOW == nil then
+			error("Studio does not expose DeviceSimulatorScalingMode.FitToWindow; update Studio before capturing a simulated viewport.")
+		end
+		local scalingMode = simulator:GetScalingModeAsync()
+		capture.scalingMode = scalingMode
+		if scalingMode == FIT_TO_WINDOW then
+			return nil
+		end
+		if simulator:GetScalingModeAsync() ~= scalingMode or simulator:GetDeviceAsync() ~= capture.deviceId then
+			error("The simulated device or scaling mode changed while preparing host capture; retry after the device settles.")
+		end
+		if capture.expired then
+			error("Host capture preparation expired.")
+		end
+		-- Set before the yielding setter: a setter failure can still have changed Studio.
+		capture.restorePending = true
+		simulator:SetScalingModeAsync(FIT_TO_WINDOW)
+		if waitForRenderedFrames() < MARKER_RENDER_FRAMES then
+			local _condition = RenderMonitor.notRenderingReason()
+			if _condition == nil then
+				_condition = "The fitted viewport did not render in time; restore the Studio window and retry."
+			end
+			error(_condition)
+		end
+		if simulator:GetDeviceAsync() ~= capture.deviceId or simulator:GetScalingModeAsync() ~= FIT_TO_WINDOW then
+			error("The simulated device or scaling mode changed while fitting the viewport; retry after the device settles.")
+		end
+	end)
+	capture.busy = false
+	if not ok or capture.expired then
+		local restored = finishMarkerCapture(capture.captureId)
+		local detail = if ok then "Host capture preparation expired." else tostring(failure)
+		return {
+			error = `Could not prepare host capture: {detail}{if restored.error ~= nil then ` {restored.error}` else ""}`,
+			captureId = capture.captureId,
+		}
+	end
+	-- Fitting can round 1200 logical pixels to 1199: keep the pre-fit dimensions
+	-- for the server's final image, while show/query report the actual fitted camera.
+	local _object = {
+		success = true,
+		captureId = capture.captureId,
+		viewportChanged = capture.restorePending,
+	}
+	for _k, _v in size do
+		_object[_k] = _v
+	end
+	return _object
+end
+local function showMarkers(captureId)
+	hideMarkers()
+	local size = viewportSize()
+	if size == nil then
+		return {
+			error = "No CurrentCamera; cannot place viewport markers.",
+		}
+	end
+	local gui = Instance.new("ScreenGui")
+	gui.Name = MARKER_GUI_NAME
+	gui.IgnoreGuiInset = true
+	-- Camera.ViewportSize reports the device safe area, so markers must bound it too.
+	gui.ScreenInsets = Enum.ScreenInsets.DeviceSafeInsets
+	gui.SafeAreaCompatibility = Enum.SafeAreaCompatibility.None
+	gui.DisplayOrder = 2147483647
+	gui.ResetOnSpawn = false
+	gui.ZIndexBehavior = Enum.ZIndexBehavior.Global
+	local corners = { { 0, 0 }, { 1, 0 }, { 0, 1 }, { 1, 1 } }
+	for _, _binding in corners do
+		local x = _binding[1]
+		local y = _binding[2]
+		local frame = Instance.new("Frame")
+		frame.Name = `Corner{x}{y}`
+		frame.AnchorPoint = Vector2.new(x, y)
+		frame.Position = UDim2.fromScale(x, y)
+		frame.Size = UDim2.fromOffset(MARKER_SIZE, MARKER_SIZE)
+		frame.BackgroundColor3 = MARKER_COLOR
+		frame.BackgroundTransparency = 0
+		frame.BorderSizePixel = 0
+		frame.ZIndex = 2147483647
+		frame.Parent = gui
+	end
+	gui.Parent = CoreGui
+	task.delay(MARKER_AUTO_HIDE_SECONDS, function()
+		if gui.Parent ~= nil then
+			gui:Destroy()
+		end
+	end)
+	local framesRendered = waitForRenderedFrames()
+	local accessError = markerAccessError("show", captureId)
+	if accessError ~= nil then
+		gui:Destroy()
+		return {
+			error = accessError,
+		}
+	end
+	local renderedSize = viewportSize()
+	if renderedSize == nil then
+		gui:Destroy()
+		return {
+			error = "No CurrentCamera after rendering viewport markers.",
+		}
+	end
+	local _object = {
+		success = true,
+	}
+	for _k, _v in renderedSize do
+		_object[_k] = _v
+	end
+	_object.markerSize = MARKER_SIZE
+	_object.framesRendered = framesRendered
+	return _object
+end
+-- prepare temporarily fits a simulated viewport; finish restores it after the
+-- clean host grab. hide only removes markers: restoring here would clip that grab.
+-- show/query report the current camera dimensions, not prepare's original size.
+local function captureMarkers(requestData)
+	local action = requestData.action
+	if action == "prepare" then
+		return prepareMarkerCapture()
+	end
+	if action == "finish" then
+		local captureId = requestData.captureId
+		if not (type(captureId) == "string") or captureId == "" then
+			return {
+				error = 'capture-markers action "finish" requires a non-empty captureId.',
+			}
+		end
+		return finishMarkerCapture(captureId)
+	end
+	if action == "show" or action == "hide" or action == "query" then
+		local accessError = markerAccessError(action, requestData.captureId)
+		if accessError ~= nil then
+			return {
+				error = accessError,
+			}
+		end
+	end
+	if action == "show" then
+		return showMarkers(requestData.captureId)
+	end
+	if action == "hide" then
+		hideMarkers()
+		return {
+			success = true,
+		}
+	end
+	if action == "query" then
+		local size = viewportSize()
+		if size == nil then
+			return {
+				error = "No CurrentCamera; cannot read viewport size.",
+			}
+		end
+		local _object = {
+			success = true,
+		}
+		for _k, _v in size do
+			_object[_k] = _v
+		end
+		_object.markerSize = MARKER_SIZE
+		return _object
+	end
+	return {
+		error = `capture-markers action must be "prepare", "finish", "show", "hide" or "query" (got {tostring(action)})`,
+	}
+end
 return {
 	captureScreenshotData = captureScreenshotData,
 	captureScreenshot = captureScreenshot,
 	captureStudio = captureStudio,
 	captureBegin = captureBegin,
 	captureRead = captureRead,
+	captureMarkers = captureMarkers,
 }
 ]]></string>
           </Properties>
@@ -4879,6 +5396,16 @@ local function captureMicroProfiler(requestData)
 			backend = backend,
 		}
 	end
+	local frameLimitOk, frameLimitResult = safeCall(function()
+		return LibMP.Control:SetFrameLimit(math.min(frameWindow, 256))
+	end)
+	if not frameLimitOk then
+		return {
+			error = "micro_profiler_frame_limit_failed",
+			message = tostring(frameLimitResult),
+			backend = backend,
+		}
+	end
 	local profilerOk, profilerResult = safeCall(function()
 		return LibMP.Control:EnableProfiler(true)
 	end)
@@ -4900,6 +5427,11 @@ local function captureMicroProfiler(requestData)
 		}
 	end
 	task.wait(durationMs / 1000)
+	-- Active reads synchronize the engine's data; paused reads can return an
+	-- empty or stale cache. Export first, then pause, including on export failure.
+	local bufferOk, snapshotOrErr = safeCall(function()
+		return LibMP.Control:CaptureToBufferSync()
+	end)
 	local captureStopOk, captureStopResult = safeCall(function()
 		return LibMP.Control:EnableCapture(false)
 	end)
@@ -4910,9 +5442,6 @@ local function captureMicroProfiler(requestData)
 			backend = backend,
 		}
 	end
-	local bufferOk, snapshotOrErr = safeCall(function()
-		return LibMP.Control:CaptureToBufferSync()
-	end)
 	if not bufferOk then
 		return {
 			error = "micro_profiler_snapshot_failed",
@@ -6069,6 +6598,7 @@ local Recording = TS.import(script, script.Parent.Parent, "Recording")
 local _binding = Utils
 local getInstanceByPath = _binding.getInstanceByPath
 local convertPropertyValue = _binding.convertPropertyValue
+local applyScriptSource = _binding.applyScriptSource
 local _binding_1 = Recording
 local beginRecording = _binding_1.beginRecording
 local finishRecording = _binding_1.finishRecording
@@ -6096,7 +6626,12 @@ local function setProperties(requestData)
 	for propName, propValue in pairs(properties) do
 		local success, err = pcall(function()
 			if propName == "Parent" or propName == "PrimaryPart" then
-				if type(propValue) == "string" then
+				if not (type(propValue) == "string") then
+					error(`{propName} must be an instance path string (or an empty string to clear)`)
+				end
+				if propValue == "" then
+					inst[propName] = nil
+				else
 					local refInstance = getInstanceByPath(propValue)
 					if not refInstance then
 						error(`{propName} reference not found: {propValue}`)
@@ -6106,7 +6641,17 @@ local function setProperties(requestData)
 			elseif propName == "Name" then
 				instance.Name = tostring(propValue)
 			elseif propName == "Source" and instance:IsA("LuaSourceContainer") then
-				instance.Source = tostring(propValue)
+				if not (type(propValue) == "string") then
+					error("Source must be a string")
+				end
+				local result = applyScriptSource(instance, propValue)
+				if not result.success then
+					local _condition = result.error
+					if _condition == nil then
+						_condition = "Script source update failed"
+					end
+					error(_condition)
+				end
 			else
 				local converted = convertPropertyValue(instance, propName, propValue)
 				inst[propName] = if converted ~= nil then converted else propValue
@@ -8512,6 +9057,7 @@ local function stopPlaytest(_requestData)
 	-- Signal the play-server DM's StopPlayMonitor via plugin:SetSetting.
 	-- The monitor acknowledges with the matching request id only after its
 	-- StudioTestService:EndTest call returns from pcall.
+	local hadActivePlaytest = testRunning or not StudioTestService.EditModeActive
 	local stopRequest = StopPlayMonitor.requestStop()
 	if not stopRequest.ok or stopRequest.requestId == nil then
 		return {
@@ -8534,6 +9080,15 @@ local function stopPlaytest(_requestData)
 		-- Either way clean up the pending request so a future playtest's monitor
 		-- doesn't fire EndTest on startup against a stale signal.
 		StopPlayMonitor.clearPending(stopRequest.requestId)
+		-- Settings acknowledgement can be lost as the server VM exits. Reconcile
+		-- only a playtest observed at entry, and only after both native teardown
+		-- and the tracked execution have finished. Never mask an EndTest error.
+		if not consumption.consumed and hadActivePlaytest and not testRunning and StudioTestService.EditModeActive then
+			return {
+				success = true,
+				message = "Playtest stopped.",
+			}
+		end
 		if testRunning then
 			return {
 				error = "Playtest stop signal failed or was not acknowledged. " .. "The playtest may have ended anyway; check get_connected_instances.",
@@ -10305,9 +10860,10 @@ return {
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "3.1.4"
+local CURRENT_VERSION = "3.1.6"
 local PLUGIN_VARIANT = "main"
 local BASE_PORT = 58741
+local SENSITIVE_DIAGNOSTIC_TERMS = { "token", "authorization", "bearer", "password", "cookie", "secret" }
 local function createConnection(port)
 	return {
 		port = port,
@@ -10326,11 +10882,118 @@ local connection = createConnection(BASE_PORT)
 local function getActiveConnection()
 	return connection
 end
+local function clearTransportDiagnostics()
+	connection.transportState = nil
+	connection.transportAttempt = nil
+	connection.transportDetail = nil
+	connection.lastTransportFailure = nil
+	connection.nextRetryAt = nil
+end
+local function sanitizeTransportDetail(detail)
+	-- Transport emits credential-free stage descriptions; also defend the UI
+	-- against accidental raw errors, URLs, markup, and multiline responses.
+	local lower = string.lower(detail)
+	for _, sensitive in SENSITIVE_DIAGNOSTIC_TERMS do
+		if (string.find(lower, sensitive, 1, true)) ~= nil then
+			return "Connection failed (sensitive details hidden)."
+		end
+	end
+	local plain = string.gsub(detail, "%w+://%S+", "[address hidden]")
+	plain = string.gsub(plain, "%c", " ")
+	plain = string.gsub(plain, "<[^>]*>", "")
+	plain = string.gsub(plain, "%s+", " ")
+	return if #plain > 180 then `{string.sub(plain, 1, 177)}...` else plain
+end
+local function applyTransportUpdate(update, now)
+	if not connection.isActive then
+		return nil
+	end
+	if update.state == "open" then
+		clearTransportDiagnostics()
+		connection.lastHttpOk = true
+		connection.lastMcpOk = false
+		connection.consecutiveFailures = 0
+		connection.currentRetryDelay = 0.5
+		connection.mcpWaitStartTime = now
+		return nil
+	end
+	connection.lastHttpOk = false
+	connection.lastMcpOk = false
+	connection.consecutiveFailures = update.attempt
+	connection.mcpWaitStartTime = nil
+	local previousState = connection.transportState
+	connection.transportState = update.state
+	connection.transportAttempt = update.attempt
+	if update.detail ~= nil then
+		connection.transportDetail = sanitizeTransportDetail(update.detail)
+	elseif update.state ~= "connecting" or previousState ~= "connecting" then
+		connection.transportDetail = nil
+	end
+	if update.state == "retrying" or update.state == "waiting-duplicate" then
+		local _condition = connection.transportDetail
+		if _condition == nil then
+			_condition = "Connection attempt failed."
+		end
+		connection.lastTransportFailure = _condition
+		connection.currentRetryDelay = update.retryDelay
+		connection.nextRetryAt = now + update.retryDelay
+	else
+		connection.nextRetryAt = nil
+	end
+end
+local function getTransportDiagnostics(now)
+	if not connection.isActive then
+		return {
+			status = "Disconnected",
+			detail = "",
+		}
+	end
+	if connection.lastHttpOk then
+		return if connection.lastMcpOk then {
+			status = "Connected",
+			detail = "Listener: connected  MCP client: connected",
+		} else {
+			status = "Waiting for MCP client",
+			detail = "Listener: connected  MCP client: not connected",
+		}
+	end
+	local _condition = connection.transportAttempt
+	if _condition == nil then
+		_condition = 0
+	end
+	local attempt = _condition + 1
+	local failure = connection.lastTransportFailure
+	if connection.nextRetryAt ~= nil then
+		local remaining = math.max(0, math.ceil((connection.nextRetryAt - now) * 10) / 10)
+		local _object = {
+			status = if connection.transportState == "waiting-duplicate" then "Waiting for previous instance" else "Listener disconnected",
+		}
+		local _left = "detail"
+		local _condition_1 = failure
+		if _condition_1 == nil then
+			_condition_1 = "Connection attempt failed."
+		end
+		_object[_left] = `Retry attempt {attempt} in {remaining}s\n{_condition_1}`
+		return _object
+	end
+	local _condition_1 = connection.transportDetail
+	if _condition_1 == nil then
+		_condition_1 = "Starting listener connection"
+	end
+	local stage = _condition_1
+	return {
+		status = `Connecting (attempt {attempt})`,
+		detail = if failure ~= nil then `{stage}\nLast failure: {failure}` else stage,
+	}
+end
 return {
 	CURRENT_VERSION = CURRENT_VERSION,
 	PLUGIN_VARIANT = PLUGIN_VARIANT,
 	BASE_PORT = BASE_PORT,
 	getActiveConnection = getActiveConnection,
+	clearTransportDiagnostics = clearTransportDiagnostics,
+	applyTransportUpdate = applyTransportUpdate,
+	getTransportDiagnostics = getTransportDiagnostics,
 }
 ]]></string>
         </Properties>
@@ -10349,6 +11012,10 @@ local RunService = _services.RunService
 local PluginSession = TS.import(script, script.Parent, "PluginSession")
 local StudioTestService = game:GetService("StudioTestService")
 local SETTING_KEY_PREFIX = "MCP_STOP_PLAY_"
+local RESULT_KEY_SUFFIX = "_RESULT"
+-- Capture before registration yields. Requests from an earlier runtime must
+-- never stop a newly created play session, even if clearing settings was lost.
+local moduleLoadedAt = tick()
 -- Keep this conservative. plugin:GetSetting is backed by Studio's plugin
 -- settings store, and this monitor runs during every play session, including
 -- manually-started Play. The official reference implementation polls at 1s.
@@ -10361,9 +11028,14 @@ local POLL_INTERVAL_SEC = 1
 local WAIT_FOR_CONSUMPTION_TIMEOUT_SEC = 8.0
 local WAIT_POLL_SEC = 0.1
 local REQUEST_TTL_SEC = 12.0
+-- Plugin settings can silently lose writes when other Studio windows use the
+-- same plugin. Redeliver the same request, without extending its deadline/TTL.
+local RETRY_INTERVAL_SEC = 1
 local pluginRef
 local endTestIssued = false
 local transportLifecycle
+local pendingRequest
+local lastResult
 local function init(p)
 	pluginRef = p
 end
@@ -10426,14 +11098,21 @@ local function writePayload(key, payload)
 	return writeSetting(key, encoded)
 end
 local function writeResult(key, request, ok, errText)
-	writePayload(key, {
+	local payload = {
 		kind = "result",
 		id = request.id,
 		requestedAt = request.requestedAt,
 		consumedAt = tick(),
 		ok = ok,
 		error = errText,
-	})
+	}
+	-- Cache before publishing: a lost acknowledgement must not issue EndTest a
+	-- second time or turn a successful duplicate into an "already issued" error.
+	lastResult = {
+		key = key,
+		payload = payload,
+	}
+	writePayload(key .. RESULT_KEY_SUFFIX, payload)
 end
 local function handleStopRequest(key, request)
 	local _condition = request.kind ~= "request"
@@ -10450,10 +11129,14 @@ local function handleStopRequest(key, request)
 		return nil
 	end
 	local age = tick() - request.requestedAt
-	if age < -5 or age > REQUEST_TTL_SEC then
+	if request.requestedAt < moduleLoadedAt or age < -5 or age > REQUEST_TTL_SEC then
 		writeSetting(key, false)
 		return nil
 	end
+	if lastResult ~= nil and lastResult.key == key and lastResult.payload.id == request.id then
+		writePayload(key .. RESULT_KEY_SUFFIX, lastResult.payload)
+		return nil
+	end
 	if endTestIssued then
 		writeResult(key, request, false, "StudioTestService:EndTest was already issued for this play session, but the runtime DataModel is still alive.")
 		return nil
@@ -10514,6 +11197,11 @@ local function requestStop()
 		requestedAt = tick(),
 	}
 	local ok = writePayload(settingKey(), payload)
+	pendingRequest = if ok then {
+		key = settingKey(),
+		payload = payload,
+		lastPublishedAt = tick(),
+	} else nil
 	return {
 		ok = ok,
 		requestId = if ok then requestId else nil,
@@ -10528,8 +11216,12 @@ local function waitForConsumption(requestId)
 		}
 	end
 	local start = tick()
+	local pending = pendingRequest
+	local key = if pending ~= nil and pending.payload.id == requestId then pending.key else settingKey()
 	while tick() - start < WAIT_FOR_CONSUMPTION_TIMEOUT_SEC do
-		local payload = decodePayload(readSetting(settingKey()))
+		-- Separate slots prevent a retry from overwriting a durable acknowledgement
+		-- during a transient nil read after the server VM has already exited.
+		local payload = decodePayload(readSetting(key .. RESULT_KEY_SUFFIX))
 		if payload and payload.kind == "result" and payload.id == requestId then
 			return {
 				ok = payload.ok == true,
@@ -10537,6 +11229,19 @@ local function waitForConsumption(requestId)
 				error = payload.error,
 			}
 		end
+		local _condition = pending ~= nil and pendingRequest == pending and pending.payload.id == requestId and tick() - pending.lastPublishedAt >= RETRY_INTERVAL_SEC
+		if _condition then
+			local _exp = tick()
+			local _condition_1 = pending.payload.requestedAt
+			if _condition_1 == nil then
+				_condition_1 = 0
+			end
+			_condition = _exp - _condition_1 < REQUEST_TTL_SEC
+		end
+		if _condition then
+			writePayload(key, pending.payload)
+			pending.lastPublishedAt = tick()
+		end
 		task.wait(WAIT_POLL_SEC)
 	end
 	return {
@@ -10549,6 +11254,17 @@ local function clearPending(requestId)
 	if not pluginRef then
 		return nil
 	end
+	local _condition = requestId == nil
+	if not _condition then
+		local _result = pendingRequest
+		if _result ~= nil then
+			_result = _result.payload.id
+		end
+		_condition = _result == requestId
+	end
+	if _condition then
+		pendingRequest = nil
+	end
 	local myKey = settingKey()
 	if requestId ~= nil then
 		local payload = decodePayload(readSetting(myKey))
@@ -10580,6 +11296,7 @@ local PROTOCOL_VERSION = 1
 local INITIAL_RETRY_DELAY_SECONDS = 0.5
 local MAX_RETRY_DELAY_SECONDS = 5
 local SOCKET_SILENCE_TIMEOUT_SECONDS = 20
+local CONNECTION_STAGE_TIMEOUT_SECONDS = 20
 local RESPONSE_RETENTION_SECONDS = 5 * 60
 local RESPONSE_ACK_TIMEOUT_SECONDS = 120
 local MAX_TERMINAL_RESPONSES = 32768
@@ -10600,7 +11317,11 @@ local socketOpen = false
 local socketConnections = {}
 local lastValidEventAt = 0
 local cachedReady
-local readyRefreshPending = false
+local connectionWork
+local refreshWork
+local refreshRequested = false
+local reconnectTimer
+local silenceTimer
 local pendingResponseBytes = 0
 local inFlightRequestBytes = 0
 local pendingRejectionCount = 0
@@ -11147,7 +11868,7 @@ local function dispatchRequest(request, requestBytes)
 		local dispatchOk, response = pcall(function()
 			return dispatchOptions.dispatchRequest(request, context)
 		end)
-		local executionOutcome = if dispatchOk then handlerOutcome(response) else "error"
+		local executionOutcome = context.executionOutcome or (if dispatchOk then handlerOutcome(response) else "error")
 		-- Report handler return before JSON encoding or result retention can fail.
 		completeProgress(request.requestId, inFlight.progress, executionOutcome)
 		local body = if dispatchOk then encodeResponse(request.requestId, response, executionOutcome) else encodeError(request.requestId, `Plugin request execution failed: {string.sub(tostring(response), 1, 512)}`, executionOutcome)
@@ -11171,6 +11892,90 @@ local function reportTransport(update)
 		end)
 	end
 end
+local function ownsWork(work)
+	return active and generation == work.generation and options == work.options and (connectionWork == work or refreshWork == work)
+end
+local function cancelThread(worker)
+	-- Cancellation is best-effort for native yielding calls. Identity checks
+	-- remain necessary when an operation returns after its owner was retired.
+	if worker ~= nil and worker ~= coroutine.running() then
+		pcall(function()
+			return task.cancel(worker)
+		end)
+	end
+end
+local function finishWork(work)
+	if connectionWork == work then
+		connectionWork = nil
+	end
+	if refreshWork == work then
+		refreshWork = nil
+	end
+	cancelThread(work.deadline)
+	cancelThread(work.worker)
+	work.deadline = nil
+	work.worker = nil
+end
+local function cancelTransportWork()
+	if connectionWork ~= nil then
+		finishWork(connectionWork)
+	end
+	if refreshWork ~= nil then
+		refreshRequested = true
+		finishWork(refreshWork)
+	end
+	cancelThread(reconnectTimer)
+	cancelThread(silenceTimer)
+	reconnectTimer = nil
+	silenceTimer = nil
+end
+local function runWork(work, callback, failed)
+	local finished = false
+	local worker = task.spawn(function()
+		if not ownsWork(work) then
+			return nil
+		end
+		work.worker = coroutine.running()
+		local ok, workError = pcall(callback)
+		work.worker = nil
+		finished = true
+		if not ok and ownsWork(work) then
+			-- Native upgrade errors can echo credential-bearing request data.
+			local detail = if work.stage == "WebSocket upgrade" then "WebSocket upgrade failed" else `{work.stage} failed: {tostring(workError)}`
+			failed(detail)
+		end
+	end)
+	if not finished and ownsWork(work) then
+		work.worker = worker
+	end
+end
+local flushRefresh
+local function beginStage(work, stage)
+	cancelThread(work.deadline)
+	work.stage = stage
+	work.deadline = task.delay(CONNECTION_STAGE_TIMEOUT_SECONDS, function()
+		if not ownsWork(work) then
+			return nil
+		end
+		work.deadline = nil
+		local detail = `{stage} timed out after {CONNECTION_STAGE_TIMEOUT_SECONDS} seconds`
+		if connectionWork == work then
+			scheduleReconnect(work.generation, detail)
+		else
+			finishWork(work)
+			warn(`[robloxstudio-mcp] {detail}`)
+			flushRefresh()
+		end
+	end)
+	if connectionWork == work then
+		reportTransport({
+			state = "connecting",
+			attempt = reconnectAttempt,
+			retryDelay = 0,
+			detail = `{stage} (timeout {CONNECTION_STAGE_TIMEOUT_SECONDS} seconds)`,
+		})
+	end
+end
 local connect
 function scheduleReconnect(expectedGeneration, detail, duplicate)
 	if duplicate == nil then
@@ -11179,7 +11984,14 @@ function scheduleReconnect(expectedGeneration, detail, duplicate)
 	if not active or generation ~= expectedGeneration then
 		return nil
 	end
+	-- A healthy registration gets one socket-only revalidation, preserving
+	-- recovery under HTTP quota. Any failure before Opened exhausts that path.
+	if not socketOpen then
+		cachedReady = nil
+	end
 	generation += 1
+	local nextGeneration = generation
+	cancelTransportWork()
 	closeCurrentSocket()
 	reconnectAttempt += 1
 	local delay = if duplicate then 1 else retryDelay(reconnectAttempt)
@@ -11189,8 +12001,11 @@ function scheduleReconnect(expectedGeneration, detail, duplicate)
 		retryDelay = delay,
 		detail = detail,
 	})
-	local nextGeneration = generation
-	task.delay(delay, function()
+	if not active or generation ~= nextGeneration then
+		return nil
+	end
+	reconnectTimer = task.delay(delay, function()
+		reconnectTimer = nil
 		if active and generation == nextGeneration then
 			connect(nextGeneration)
 		end
@@ -11198,10 +12013,11 @@ function scheduleReconnect(expectedGeneration, detail, duplicate)
 end
 local function watchForSilence(expectedGeneration, expectedClient)
 	local elapsed = tick() - lastValidEventAt
-	task.delay(math.max(SOCKET_SILENCE_TIMEOUT_SECONDS - elapsed, 0.1), function()
+	silenceTimer = task.delay(math.max(SOCKET_SILENCE_TIMEOUT_SECONDS - elapsed, 0.1), function()
 		if not active or generation ~= expectedGeneration or socketClient ~= expectedClient then
 			return nil
 		end
+		silenceTimer = nil
 		local silentFor = tick() - lastValidEventAt
 		if silentFor >= SOCKET_SILENCE_TIMEOUT_SECONDS then
 			scheduleReconnect(expectedGeneration, `WebSocket silent for {math.floor(silentFor)} seconds`)
@@ -11268,13 +12084,18 @@ local function parseReadyResponse(body)
 		transportToken = value.transportToken,
 	}
 end
-local function registerReady(currentOptions, expectedGeneration, reconnectOnFailure)
+local function registerReady(work, reconnectOnFailure)
+	if not ownsWork(work) then
+		return nil
+	end
+	local currentOptions = work.options
+	local expectedGeneration = work.generation
 	local instanceId = PluginSession.getInstanceId()
 	local multiplayerGroupId = PluginSession.getMultiplayerGroupId()
 	local transportRole = PluginSession.getRole()
 	local readyUrl = `{currentOptions.serverUrl}/ready`
 	local readyPayload = PluginSession.createReadyPayload(PluginSession.peerId, transportRole, instanceId, multiplayerGroupId)
-	if not active or generation ~= expectedGeneration or options ~= currentOptions then
+	if not ownsWork(work) then
 		return nil
 	end
 	local readyOk, readyResult = pcall(function()
@@ -11287,7 +12108,7 @@ local function registerReady(currentOptions, expectedGeneration, reconnectOnFail
 			Body = HttpService:JSONEncode(readyPayload),
 		})
 	end)
-	if not active or generation ~= expectedGeneration or options ~= currentOptions then
+	if not ownsWork(work) then
 		return nil
 	end
 	local readyLogKey = `{currentOptions.serverUrl}|{PluginSession.peerId}`
@@ -11317,7 +12138,7 @@ local function registerReady(currentOptions, expectedGeneration, reconnectOnFail
 	invokeCallback("WebSocket ready", function()
 		return currentOptions.onReady(readyData)
 	end)
-	return readyData
+	return if ownsWork(work) then readyData else nil
 end
 local function credentialsRejected(statusCode)
 	return statusCode == 401 or statusCode == 403 or statusCode == 404
@@ -11327,14 +12148,28 @@ function connect(expectedGeneration)
 	if not active or generation ~= expectedGeneration or currentOptions == nil then
 		return nil
 	end
-	reportTransport({
-		state = "connecting",
-		attempt = reconnectAttempt,
-		retryDelay = 0,
-	})
-	task.spawn(function()
-		local readyData = cachedReady or registerReady(currentOptions, expectedGeneration, true)
-		if readyData == nil or not active or generation ~= expectedGeneration or options ~= currentOptions then
+	if refreshWork ~= nil then
+		finishWork(refreshWork)
+	end
+	local work = {
+		generation = expectedGeneration,
+		options = currentOptions,
+		stage = "",
+	}
+	connectionWork = work
+	beginStage(work, if cachedReady == nil then "/ready registration" else "WebSocket upgrade")
+	if not ownsWork(work) then
+		return nil
+	end
+	runWork(work, function()
+		local readyData = cachedReady or registerReady(work, true)
+		if readyData == nil or not ownsWork(work) then
+			return nil
+		end
+		if work.stage ~= "WebSocket upgrade" then
+			beginStage(work, "WebSocket upgrade")
+		end
+		if not ownsWork(work) then
 			return nil
 		end
 		local socketBaseUrl = string.gsub(currentOptions.serverUrl, "^http", "ws")
@@ -11347,28 +12182,32 @@ function connect(expectedGeneration)
 			})
 		end)
 		if not createOk then
-			scheduleReconnect(expectedGeneration, `Failed to create WebSocket: {tostring(createdClient)}`)
+			scheduleReconnect(expectedGeneration, "Failed to create WebSocket")
 			return nil
 		end
-		if not active or generation ~= expectedGeneration or options ~= currentOptions then
+		if not ownsWork(work) then
 			pcall(function()
 				return createdClient:Close()
 			end)
 			return nil
 		end
 		socketClient = createdClient
-		socketConnections = { createdClient.Opened:Connect(function(statusCode, _headers)
+		-- Attach incrementally so a failed subscription cannot leak earlier ones.
+		local _socketConnections = socketConnections
+		local _arg0 = createdClient.Opened:Connect(function(statusCode, _headers)
 			if not active or generation ~= expectedGeneration or socketClient ~= createdClient then
 				return nil
 			end
+			if socketOpen then
+				return nil
+			end
 			if statusCode ~= 101 and (statusCode < 200 or statusCode >= 300) then
-				if credentialsRejected(statusCode) then
-					cachedReady = nil
-				end
+				cachedReady = nil
 				scheduleReconnect(expectedGeneration, `WebSocket opened with HTTP {statusCode}`)
 				return nil
 			end
 			socketOpen = true
+			finishWork(work)
 			lastValidEventAt = tick()
 			reconnectAttempt = 0
 			reportTransport({
@@ -11376,8 +12215,18 @@ function connect(expectedGeneration)
 				attempt = 0,
 				retryDelay = 0,
 			})
+			if not active or generation ~= expectedGeneration or socketClient ~= createdClient then
+				return nil
+			end
+			watchForSilence(expectedGeneration, createdClient)
 			resumePendingResponses()
-		end), createdClient.MessageReceived:Connect(function(message)
+			if active and generation == expectedGeneration and socketClient == createdClient then
+				flushRefresh()
+			end
+		end)
+		table.insert(_socketConnections, _arg0)
+		local _socketConnections_1 = socketConnections
+		local _arg0_1 = createdClient.MessageReceived:Connect(function(message)
 			if not active or generation ~= expectedGeneration or socketClient ~= createdClient then
 				return nil
 			end
@@ -11415,27 +12264,41 @@ function connect(expectedGeneration)
 				invokeCallback("WebSocket status", function()
 					return currentOptions.onStatus(event)
 				end)
+				if not active or generation ~= expectedGeneration or socketClient ~= createdClient then
+					return nil
+				end
 				if not event.knownPeer then
 					cachedReady = nil
 					scheduleReconnect(expectedGeneration, "WebSocket session is no longer registered")
 				end
 			end
-		end), createdClient.Error:Connect(function(statusCode, message)
+		end)
+		table.insert(_socketConnections_1, _arg0_1)
+		local _socketConnections_2 = socketConnections
+		local _arg0_2 = createdClient.Error:Connect(function(statusCode, _message)
 			if not active or generation ~= expectedGeneration or socketClient ~= createdClient then
 				return nil
 			end
-			if credentialsRejected(statusCode) then
+			if not socketOpen or credentialsRejected(statusCode) then
 				cachedReady = nil
 			end
-			scheduleReconnect(expectedGeneration, `WebSocket error {statusCode}: {message}`)
-		end), createdClient.Closed:Connect(function()
+			-- Native error messages may echo request credentials.
+			scheduleReconnect(expectedGeneration, `WebSocket error {statusCode}`)
+		end)
+		table.insert(_socketConnections_2, _arg0_2)
+		local _socketConnections_3 = socketConnections
+		local _arg0_3 = createdClient.Closed:Connect(function()
 			if not active or generation ~= expectedGeneration or socketClient ~= createdClient then
 				return nil
 			end
+			if not socketOpen then
+				cachedReady = nil
+			end
 			scheduleReconnect(expectedGeneration, "WebSocket closed")
-		end) }
-		lastValidEventAt = tick()
-		watchForSilence(expectedGeneration, createdClient)
+		end)
+		table.insert(_socketConnections_3, _arg0_3)
+	end, function(detail)
+		return scheduleReconnect(expectedGeneration, detail)
 	end)
 end
 local stop
@@ -11450,20 +12313,42 @@ local function start(newOptions)
 	generation += 1
 	connect(generation)
 end
-local function refresh()
+function flushRefresh()
 	local currentOptions = options
-	if not active or currentOptions == nil or readyRefreshPending then
+	if not refreshRequested or not active or currentOptions == nil or refreshWork ~= nil or connectionWork ~= nil or not socketOpen then
 		return nil
 	end
-	-- Metadata changes must not close a healthy socket or make its reconnect
-	-- depend on RequestAsync quota. Proxy registration remains independent.
-	readyRefreshPending = true
-	local expectedGeneration = generation
-	task.spawn(function()
-		registerReady(currentOptions, expectedGeneration, false)
-		readyRefreshPending = false
+	refreshRequested = false
+	-- Only explicit metadata changes are queued. Failure alone never schedules
+	-- more HTTP requests or replaces a healthy transport.
+	local work = {
+		generation = generation,
+		options = currentOptions,
+		stage = "",
+	}
+	refreshWork = work
+	beginStage(work, "/ready metadata refresh")
+	runWork(work, function()
+		-- Consume at worker entry so changes coalesce even before task.spawn runs.
+		refreshRequested = false
+		registerReady(work, false)
+		if ownsWork(work) then
+			finishWork(work)
+			flushRefresh()
+		end
+	end, function(detail)
+		finishWork(work)
+		warn(`[robloxstudio-mcp] {detail}`)
+		flushRefresh()
 	end)
 end
+local function refresh()
+	if not active or options == nil then
+		return nil
+	end
+	refreshRequested = true
+	flushRefresh()
+end
 -- EndTest may tear down this VM without an Unloading callback. Release the
 -- native socket before yielding to unregister; a failed EndTest can resume.
 local function suspendForShutdown()
@@ -11474,6 +12359,8 @@ local function suspendForShutdown()
 	active = false
 	shutdownSuspended = true
 	generation += 1
+	cancelTransportWork()
+	refreshRequested = false
 	reconnectAttempt = 0
 	closeCurrentSocket()
 	cachedReady = nil
@@ -11497,6 +12384,8 @@ function stop()
 	active = false
 	shutdownSuspended = false
 	generation += 1
+	cancelTransportWork()
+	refreshRequested = false
 	for _, inFlight in inFlightRequests do
 		inFlight.cancelled = true
 	end
@@ -11827,12 +12716,13 @@ local function init(pluginRef)
 		end
 	end)
 	local statusRow = Instance.new("Frame")
-	statusRow.Size = UDim2.new(1, 0, 0, 14)
+	statusRow.Size = UDim2.new(1, 0, 0, 0)
+	statusRow.AutomaticSize = Enum.AutomaticSize.Y
 	statusRow.BackgroundTransparency = 1
 	statusRow.LayoutOrder = 2
 	statusRow.Parent = card
 	local statusLabel = Instance.new("TextLabel")
-	statusLabel.Size = UDim2.new(1, 0, 1, 0)
+	statusLabel.Size = UDim2.new(1, 0, 0, 18)
 	statusLabel.BackgroundTransparency = 1
 	statusLabel.Text = "Disconnected"
 	statusLabel.TextColor3 = C.red
@@ -11840,17 +12730,20 @@ local function init(pluginRef)
 	statusLabel.Font = Enum.Font.GothamBold
 	statusLabel.TextXAlignment = Enum.TextXAlignment.Left
 	statusLabel.TextWrapped = true
+	statusLabel.RichText = false
 	statusLabel.Parent = statusRow
 	local detailStatusLabel = Instance.new("TextLabel")
-	detailStatusLabel.Size = UDim2.new(0.5, 0, 1, 0)
-	detailStatusLabel.Position = UDim2.new(0.5, 0, 0, 0)
+	detailStatusLabel.Size = UDim2.new(1, 0, 0, 0)
+	detailStatusLabel.Position = UDim2.new(0, 0, 0, 18)
+	detailStatusLabel.AutomaticSize = Enum.AutomaticSize.Y
 	detailStatusLabel.BackgroundTransparency = 1
 	detailStatusLabel.Text = "HTTP: X  MCP: X"
 	detailStatusLabel.TextColor3 = C.muted
 	detailStatusLabel.TextSize = 9
 	detailStatusLabel.Font = Enum.Font.GothamMedium
-	detailStatusLabel.TextXAlignment = Enum.TextXAlignment.Right
+	detailStatusLabel.TextXAlignment = Enum.TextXAlignment.Left
 	detailStatusLabel.TextWrapped = true
+	detailStatusLabel.RichText = false
 	detailStatusLabel.Parent = statusRow
 	local stepsFrame = Instance.new("Frame")
 	stepsFrame.Size = UDim2.new(1, 0, 0, 0)
@@ -11987,13 +12880,14 @@ local function updateUIState()
 		return nil
 	end
 	local el = elements
+	local diagnostics = State.getTransportDiagnostics(tick())
 	if not conn.isActive then
-		el.statusLabel.Text = "Disconnected"
+		el.statusLabel.Text = diagnostics.status
 		el.statusLabel.TextColor3 = C.muted
 		el.statusIndicator.BackgroundColor3 = C.red
 		el.statusPulse.BackgroundColor3 = C.red
 		el.statusText.Text = "OFFLINE"
-		el.detailStatusLabel.Text = ""
+		el.detailStatusLabel.Text = diagnostics.detail
 		el.detailStatusLabel.TextColor3 = C.muted
 		stopPulseAnimation()
 		el.step1Dot.BackgroundColor3 = C.gray
@@ -12016,12 +12910,12 @@ local function updateUIState()
 	el.urlInput.TextEditable = false
 	el.urlInput.BackgroundColor3 = C.card
 	if conn.lastHttpOk and conn.lastMcpOk then
-		el.statusLabel.Text = "Connected"
+		el.statusLabel.Text = diagnostics.status
 		el.statusLabel.TextColor3 = Color3.fromRGB(34, 197, 94)
 		el.statusIndicator.BackgroundColor3 = Color3.fromRGB(34, 197, 94)
 		el.statusPulse.BackgroundColor3 = Color3.fromRGB(34, 197, 94)
 		el.statusText.Text = "ONLINE"
-		el.detailStatusLabel.Text = "HTTP: OK  MCP: OK"
+		el.detailStatusLabel.Text = diagnostics.detail
 		el.detailStatusLabel.TextColor3 = Color3.fromRGB(34, 197, 94)
 		el.step1Dot.BackgroundColor3 = Color3.fromRGB(34, 197, 94)
 		el.step1Label.Text = "HTTP server (OK)"
@@ -12032,12 +12926,12 @@ local function updateUIState()
 		el.troubleshootLabel.Visible = false
 		stopPulseAnimation()
 	elseif conn.lastHttpOk and not conn.lastMcpOk then
-		el.statusLabel.Text = "Waiting for MCP server"
+		el.statusLabel.Text = diagnostics.status
 		el.statusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
 		el.statusIndicator.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
 		el.statusPulse.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
 		el.statusText.Text = "WAITING"
-		el.detailStatusLabel.Text = "HTTP: OK  MCP: ..."
+		el.detailStatusLabel.Text = diagnostics.detail
 		el.detailStatusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
 		el.step1Dot.BackgroundColor3 = Color3.fromRGB(34, 197, 94)
 		el.step1Label.Text = "HTTP server (OK)"
@@ -12048,53 +12942,21 @@ local function updateUIState()
 		local elapsed = if conn.mcpWaitStartTime ~= nil then tick() - conn.mcpWaitStartTime else 0
 		el.troubleshootLabel.Visible = elapsed > 8
 		startPulseAnimation()
-	elseif conn.consecutiveFailures >= conn.maxFailuresBeforeError then
-		el.statusLabel.Text = "Server unavailable"
-		el.statusLabel.TextColor3 = Color3.fromRGB(239, 68, 68)
-		el.statusIndicator.BackgroundColor3 = Color3.fromRGB(239, 68, 68)
-		el.statusPulse.BackgroundColor3 = Color3.fromRGB(239, 68, 68)
-		el.statusText.Text = "ERROR"
-		el.detailStatusLabel.Text = "HTTP: X  MCP: X"
-		el.detailStatusLabel.TextColor3 = Color3.fromRGB(239, 68, 68)
-		el.step1Dot.BackgroundColor3 = Color3.fromRGB(239, 68, 68)
-		el.step1Label.Text = "HTTP server (error)"
-		el.step2Dot.BackgroundColor3 = Color3.fromRGB(239, 68, 68)
-		el.step2Label.Text = "MCP bridge (error)"
-		el.step3Dot.BackgroundColor3 = Color3.fromRGB(239, 68, 68)
-		el.step3Label.Text = "Commands (error)"
-		el.troubleshootLabel.Visible = false
-		stopPulseAnimation()
-	elseif conn.consecutiveFailures > 5 then
-		local waitTime = math.ceil(conn.currentRetryDelay)
-		el.statusLabel.Text = `Retrying ({waitTime}s)`
-		el.statusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
-		el.statusIndicator.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-		el.statusPulse.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-		el.statusText.Text = "RETRY"
-		el.detailStatusLabel.Text = "HTTP: ...  MCP: ..."
-		el.detailStatusLabel.TextColor3 = Color3.fromRGB(245, 158, 11)
-		el.step1Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-		el.step1Label.Text = "HTTP server (retrying...)"
-		el.step2Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-		el.step2Label.Text = "MCP bridge (retrying...)"
-		el.step3Dot.BackgroundColor3 = Color3.fromRGB(245, 158, 11)
-		el.step3Label.Text = "Commands (retrying...)"
-		el.troubleshootLabel.Visible = false
-		startPulseAnimation()
 	else
-		el.statusLabel.Text = if conn.consecutiveFailures > 1 then `Connecting (attempt {conn.consecutiveFailures})` else "Connecting..."
+		local retrying = conn.nextRetryAt ~= nil
+		el.statusLabel.Text = diagnostics.status
 		el.statusLabel.TextColor3 = C.yellow
 		el.statusIndicator.BackgroundColor3 = C.yellow
 		el.statusPulse.BackgroundColor3 = C.yellow
-		el.statusText.Text = "CONNECTING"
-		el.detailStatusLabel.Text = if conn.consecutiveFailures == 0 then "..." else "HTTP: ...  MCP: ..."
-		el.detailStatusLabel.TextColor3 = C.muted
+		el.statusText.Text = if retrying then "RETRY" else "CONNECTING"
+		el.detailStatusLabel.Text = diagnostics.detail
+		el.detailStatusLabel.TextColor3 = C.yellow
 		el.step1Dot.BackgroundColor3 = C.yellow
-		el.step1Label.Text = "HTTP server (connecting...)"
-		el.step2Dot.BackgroundColor3 = C.yellow
-		el.step2Label.Text = "MCP bridge (connecting...)"
-		el.step3Dot.BackgroundColor3 = C.yellow
-		el.step3Label.Text = "Commands (connecting...)"
+		el.step1Label.Text = if retrying then "Listener (disconnected)" else "Listener (connecting...)"
+		el.step2Dot.BackgroundColor3 = C.gray
+		el.step2Label.Text = "MCP client (waiting for listener)"
+		el.step3Dot.BackgroundColor3 = C.gray
+		el.step3Label.Text = "Commands (waiting for listener)"
 		el.troubleshootLabel.Visible = false
 		startPulseAnimation()
 	end
@@ -12714,11 +13576,13 @@ local function convertPropertyValue(instance, propertyName, propertyValue)
 		if propertyName == "BrickColor" then
 			return BrickColor.new(propertyValue)
 		end
-		if propertyValue == "true" then
-			return true
-		end
-		if propertyValue == "false" then
-			return false
+		if success and typeof(currentVal) == "boolean" then
+			if propertyValue == "true" then
+				return true
+			end
+			if propertyValue == "false" then
+				return false
+			end
 		end
 	end
 	return propertyValue