@el4cteo/rbx-studio-mcp 0.7.1 → 0.7.5

package/scripts/test-bridge.mjs

@@ -322,6 +322,46 @@ function twoStudios() {
   second.destroy();
   await settle();
   assert.equal(await count(), 0, "a stream that dies without a goodbye is dropped");
+
+  // A command far bigger than one socket read goes down the stream as ONE
+  // event, and its answer comes back. The plugin half of this -- joining the
+  // reads back together -- is covered by the frameReader cases in
+  // tests/sseframes.luau; this pins the bridge half over real sockets.
+  const source = "local x = 1\n".repeat(100_000);
+  const events = [];
+  const plugin = await new Promise((resolve) => {
+    const req = request(
+      { host: "127.0.0.1", port, path: "/events", method: "POST", headers: { "x-roblox-studio-mcp": "test" } },
+      (res) => {
+        let pending = "";
+        res.setEncoding("utf8");
+        res.on("data", (chunk) => {
+          pending += chunk;
+          let cut;
+          while ((cut = pending.indexOf("\n\n")) !== -1) {
+            const block = pending.slice(0, cut);
+            pending = pending.slice(cut + 2);
+            if (!block.startsWith("data: ")) continue;
+            const frame = JSON.parse(block.slice(6));
+            if (typeof frame.id !== "string") continue;
+            events.push(frame);
+            void fetch(`http://127.0.0.1:${port}/result?studioId=big`, {
+              method: "POST",
+              headers: { "x-roblox-studio-mcp": "test" },
+              body: JSON.stringify({ id: frame.id, ok: true, data: { length: frame.params.source.length } }),
+            });
+          }
+        });
+        resolve(req);
+      },
+    );
+    req.end(JSON.stringify({ studioId: "big", placeName: "p", placeId: 1 }));
+  });
+  const answer = await server.bridge.call("script.create", { source }, { studioId: "big" });
+  assert.equal(answer.length, source.length, "a 1.2MB command arrives whole and is answered");
+  assert.equal(events.length, 1, "as exactly one event");
+  plugin.destroy();
+
   await server.close();
 }
 

package/scripts/test-console.mjs

@@ -590,3 +590,28 @@ if (process.platform === "win32") {
 }
 
 process.stdout.write(`console: ${checks} checks pass\n`);
+
+// OFF stops all detected test contexts through the existing control operation.
+{
+ const sessions = ["edit", "server", "run", "idle"].map(studioId => ({studioId,placeName:studioId}));
+ const calls = [];
+ const bridge = {
+  list: () => sessions,
+  call: async (op, params, options) => {
+   assert.equal(op, "playtest.control");
+   calls.push({params, options});
+   const id = options.studioId;
+   return {state:{isEdit:id === "edit" || id === "idle",isRunning:id === "server" || id === "run",isRunMode:id === "run",testPending:id === "edit",editModeActive:id !== "edit"}};
+  },
+ };
+ const request = {studioId:"edit",command:"playtests",args:["off"],line:"playtests off"};
+ const rows = await handleConsole(bridge,44755,request);
+ assert.deepEqual(rows, []);
+ const stops = calls.filter(call => call.params.op !== "state");
+ assert.deepEqual(stops.map(call => [call.options.studioId,call.params.op]), [["edit","stop"],["server","endTest"],["run","stop"]]);
+ const before = calls.length;
+ const refused = await handleConsole(bridge,44755,{...request,args:["on"]});
+ assert.equal(refused[0].level, "error");
+ assert.equal(calls.length,before,"bridge panel endpoint cannot enable or start playtests");
+}
+process.stdout.write("panel playtest stop routing: ok\n");

package/scripts/test-failover.mjs

@@ -20,7 +20,15 @@ import { startBridgeServer } from "../dist/bridge/server.js";
 import { CLIENT_HEADER } from "../dist/lib/protocol.js";
 import { PEER_HEADER } from "../dist/bridge/remote.js";
 
-const PORT = 44799;
+// A free port, not a fixed one: a fixed port fails the whole suite whenever
+// anything else on the machine happens to hold it.
+const PORT = await new Promise((resolve, reject) => {
+  const probe = createServer().listen(0, "127.0.0.1", () => {
+    const { port } = probe.address();
+    probe.close(() => resolve(port));
+  });
+  probe.once("error", reject);
+});
 
 /** Waits for `check` to hold, or gives up loudly rather than hanging the suite. */
 async function until(check, what, timeoutMs = 20_000) {
@@ -133,102 +141,102 @@ function handshake(port, studioId) {
   await owner.close();
 }
 
-// POST /hello carries the panel's spawned marker all the way to the roster.
-//
-// The shipped bug: every layer marked the agent the panel starts -- the spawn's
-// environment, the MCP config handed to the agent, the hello body -- and this
-// route typed the body with three fields and dropped the fourth. So the panel
-// said "2 MCP clients connected" on every prompt and kept a stopped agent in
-// `clients` until the stale sweep. Tested at the route, because the route is
-// the layer that was wrong while the bridge underneath it was right.
-{
-  const owner = await startBridgeServer({ port: PORT });
-
-  const hello = async (id, body) => {
-    const sent = await fetch(`http://127.0.0.1:${PORT}/hello`, {
-      method: "POST",
-      headers: {
-        [CLIENT_HEADER]: "test",
-        [PEER_HEADER]: id,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify(body),
-    });
-    return (await sent.json()).clients;
-  };
-
-  const alone = await hello("a-stranger", { name: "codex", version: "1", pid: 1 });
-  const withAgent = await hello("panel-agent", {
-    name: "claude-code",
-    version: "1",
-    pid: 2,
-    spawned: true,
-  });
-  assert.equal(withAgent, alone, "an agent the panel started is not another client");
-  // A second stranger does count, or the filter would be hiding everyone.
-  const withStranger = await hello("another-stranger", { name: "opencode", pid: 3 });
-  assert.equal(withStranger, alone + 1, "a client nobody asked for still counts");
-
-  // A keepalive that says nothing must not erase what the first hello said, and
-  // must not re-announce the client as if it had just arrived.
-  assert.equal(
-    await hello("a-stranger", { pid: 1 }),
-    withStranger,
-    "a nameless keepalive is not a new client",
-  );
-
-  await owner.close();
-}
-
-// An owner that dies WHILE answering is still OWNER_GONE, not a raw Node error.
-//
-// The shipped bug: only the fetch was guarded, so a socket cut after the
-// headers threw "TypeError: fetch failed / SocketError: other side closed"
-// straight past the catch. It surfaced right under the takeover notice, which
-// is the exact moment a handover cuts a live response.
-//
-// The fake owner declares a Content-Length it never delivers, then hangs up.
-// That distinction is the whole test: a socket destroyed BEFORE the headers
-// makes Node reject the fetch itself, which the old code already caught -- the
-// bug only shows when the reply has started and stops halfway. Two earlier
-// versions of this test cut the socket too early, passed with the bug present,
-// and proved nothing.
-{
-  const halfDead = createServer((req, res) => {
-    if (req.url === "/identity") {
-      res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ server: "roblox-studio-mcp", protocolVersion: 1, pid: 1 }));
-      return;
-    }
-    res.writeHead(200, { "Content-Type": "application/json", "Content-Length": "5000" });
-    res.write('{"ok":true,"data":"' + "x".repeat(100));
-    setTimeout(() => res.socket.destroy(), 150);
-  });
-  await new Promise((resolve) => halfDead.listen(PORT, "127.0.0.1", resolve));
-
-  const peer = await startBridgeServer({ port: PORT });
-  assert.equal(peer.owner, false, "the peer proxies to whatever holds the port");
-
-  let raised;
-  try {
-    await peer.bridge.call("studio.status", {});
-  } catch (cause) {
-    raised = cause;
-  }
-
-  assert.ok(raised, "a truncated answer must not resolve as success");
-  assert.equal(
-    raised.code,
-    "OWNER_GONE",
-    `a body cut short is the owner going away, not a raw ${raised?.name}`,
-  );
-  assert.ok(
-    /try the call again/.test(raised.hint ?? ""),
-    "and says what to do about it, which a raw socket error never does",
-  );
-
-  await peer.close();
-  await new Promise((resolve) => halfDead.close(resolve));
-}
-
+// POST /hello carries the panel's spawned marker all the way to the roster.
+//
+// The shipped bug: every layer marked the agent the panel starts -- the spawn's
+// environment, the MCP config handed to the agent, the hello body -- and this
+// route typed the body with three fields and dropped the fourth. So the panel
+// said "2 MCP clients connected" on every prompt and kept a stopped agent in
+// `clients` until the stale sweep. Tested at the route, because the route is
+// the layer that was wrong while the bridge underneath it was right.
+{
+  const owner = await startBridgeServer({ port: PORT });
+
+  const hello = async (id, body) => {
+    const sent = await fetch(`http://127.0.0.1:${PORT}/hello`, {
+      method: "POST",
+      headers: {
+        [CLIENT_HEADER]: "test",
+        [PEER_HEADER]: id,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+    return (await sent.json()).clients;
+  };
+
+  const alone = await hello("a-stranger", { name: "codex", version: "1", pid: 1 });
+  const withAgent = await hello("panel-agent", {
+    name: "claude-code",
+    version: "1",
+    pid: 2,
+    spawned: true,
+  });
+  assert.equal(withAgent, alone, "an agent the panel started is not another client");
+  // A second stranger does count, or the filter would be hiding everyone.
+  const withStranger = await hello("another-stranger", { name: "opencode", pid: 3 });
+  assert.equal(withStranger, alone + 1, "a client nobody asked for still counts");
+
+  // A keepalive that says nothing must not erase what the first hello said, and
+  // must not re-announce the client as if it had just arrived.
+  assert.equal(
+    await hello("a-stranger", { pid: 1 }),
+    withStranger,
+    "a nameless keepalive is not a new client",
+  );
+
+  await owner.close();
+}
+
+// An owner that dies WHILE answering is still OWNER_GONE, not a raw Node error.
+//
+// The shipped bug: only the fetch was guarded, so a socket cut after the
+// headers threw "TypeError: fetch failed / SocketError: other side closed"
+// straight past the catch. It surfaced right under the takeover notice, which
+// is the exact moment a handover cuts a live response.
+//
+// The fake owner declares a Content-Length it never delivers, then hangs up.
+// That distinction is the whole test: a socket destroyed BEFORE the headers
+// makes Node reject the fetch itself, which the old code already caught -- the
+// bug only shows when the reply has started and stops halfway. Two earlier
+// versions of this test cut the socket too early, passed with the bug present,
+// and proved nothing.
+{
+  const halfDead = createServer((req, res) => {
+    if (req.url === "/identity") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ server: "roblox-studio-mcp", protocolVersion: 1, pid: 1 }));
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "application/json", "Content-Length": "5000" });
+    res.write('{"ok":true,"data":"' + "x".repeat(100));
+    setTimeout(() => res.socket.destroy(), 150);
+  });
+  await new Promise((resolve) => halfDead.listen(PORT, "127.0.0.1", resolve));
+
+  const peer = await startBridgeServer({ port: PORT });
+  assert.equal(peer.owner, false, "the peer proxies to whatever holds the port");
+
+  let raised;
+  try {
+    await peer.bridge.call("studio.status", {});
+  } catch (cause) {
+    raised = cause;
+  }
+
+  assert.ok(raised, "a truncated answer must not resolve as success");
+  assert.equal(
+    raised.code,
+    "OWNER_GONE",
+    `a body cut short is the owner going away, not a raw ${raised?.name}`,
+  );
+  assert.ok(
+    /try the call again/.test(raised.hint ?? ""),
+    "and says what to do about it, which a raw socket error never does",
+  );
+
+  await peer.close();
+  await new Promise((resolve) => halfDead.close(resolve));
+}
+
 process.stdout.write("failover: ok\n");

package/scripts/test-live.mjs

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+/**
+ * Drives a real, connected Studio through the running bridge and checks the
+ * paths no fake can: big payloads over the actual stream, and scripts that
+ * survive a create -> read -> edit -> delete round trip.
+ *
+ * Not part of `npm test`, because it needs Studio open with the plugin. It
+ * exists because the worst transport bug this project had -- any command the
+ * stream delivered in more than one piece was dropped, so a big `script_create`
+ * timed out -- passed every offline test and only showed up against Studio.
+ *
+ * Everything it makes is named `__mcp_live_*` under ServerScriptService and is
+ * deleted before it exits, pass or fail.
+ *
+ * Usage: node scripts/test-live.mjs [--port 44755] [--sizes 1000,16000,64000,256000] [--client] [--remotes] [--playtests-off] [--studio-id ID] [--player NAME]
+ */
+import { expectedPluginBuildId } from "../dist/lib/pluginbuild.js";
+
+const args = process.argv.slice(2);
+const flag = (name, fallback) => {
+  const at = args.indexOf(`--${name}`);
+  return at === -1 ? fallback : args[at + 1];
+};
+const port = Number.parseInt(flag("port", "44755"), 10);
+const sizes = flag("sizes", "1000,16000,64000,256000").split(",").map(Number);
+const base = `http://127.0.0.1:${port}`;
+const HEADERS = {
+  "x-roblox-studio-mcp": "test-live",
+  "x-roblox-studio-mcp-peer": `test-live-${process.pid}`,
+  "content-type": "application/json",
+};
+const PREFIX = "__mcp_live_";
+
+async function call(op, params, timeoutMs = 20_000) {
+  const response = await fetch(`${base}/call`, {
+    method: "POST",
+    headers: HEADERS,
+    body: JSON.stringify({ op, params, timeoutMs, studioId: flag("studio-id", undefined) }),
+  });
+  const body = await response.json();
+  if (!body.ok) throw new Error(`${op}: [${body.error?.code}] ${body.error?.message}`);
+  return body.data;
+}
+
+/** Luau source of about `size` bytes, with quotes and non-ASCII so escaping is exercised. */
+function sourceOf(size) {
+  const lines = [];
+  let length = 0;
+  for (let index = 0; length < size; index += 1) {
+    const line = `local value${index} = "line ${index}: \\"quoted\\" ünïcode ✓"`;
+    lines.push(line);
+    length += line.length + 1;
+  }
+  return lines.join("\n");
+}
+
+let sessions;
+try {
+  sessions = await (await fetch(`${base}/sessions`, { headers: HEADERS })).json();
+} catch {
+  process.stderr.write(`Nothing is listening on port ${port}. Start the MCP server and open Studio.\n`);
+  process.exit(1);
+}
+const studio = flag("studio-id", undefined)
+  ? sessions.list.find((entry) => entry.studioId === flag("studio-id"))
+  : sessions.list[0];
+if (studio === undefined) {
+  process.stderr.write("The bridge is up but no Studio is connected.\n");
+  process.exit(1);
+}
+if (studio.buildId !== expectedPluginBuildId()) {
+  process.stderr.write(
+    `warning: Studio runs plugin build ${studio.buildId}, this checkout is ` +
+      `${expectedPluginBuildId()}. Results describe the plugin Studio has loaded.\n`,
+  );
+}
+process.stdout.write(`Studio: ${studio.placeName} (${studio.transport})\n`);
+
+const created = [];
+let failures = 0;
+const check = (ok, what) => {
+  process.stdout.write(`${ok ? "ok  " : "FAIL"}  ${what}\n`);
+  if (!ok) failures += 1;
+};
+
+try {
+  for (const size of sizes) {
+    const name = `${PREFIX}${size}`;
+    const source = sourceOf(size);
+    const started = Date.now();
+    try {
+      await call("script.create", {
+        scripts: [{ parent: "ServerScriptService", name, className: "ModuleScript", source }],
+      });
+      created.push(`ServerScriptService.${name}`);
+      const read = await call("script.read", { paths: [`ServerScriptService.${name}`] });
+      const item = read.items[0];
+      check(item?.source === source, `${size} bytes: create + read back identical (${Date.now() - started}ms)`);
+
+      const edited = await call("script.edit", {
+        edits: [{ path: `ServerScriptService.${name}`, find: "local value0 =", replace: "local first =", revision: item.revision }],
+      });
+      check(edited.items[0]?.edits === 1, `${size} bytes: conditional edit applied`);
+    } catch (cause) {
+      check(false, `${size} bytes: ${cause.message}`);
+    }
+  }
+} finally {
+  if (created.length > 0) {
+    await call("instances.delete", { paths: created }).catch((cause) => {
+      process.stderr.write(`cleanup failed, delete ${created.join(", ")} by hand: ${cause.message}\n`);
+    });
+  }
+}
+
+// --client requires a running playtest with this checkout's plugin loaded.
+// --studio-id selects its server session; --player supports multiplayer tests.
+if (args.includes("--client")) {
+  if (studio.buildId !== expectedPluginBuildId()) {
+    check(false, "client checks require the current plugin build; reload the plugin first");
+  } else {
+    const client = (source, timeoutSeconds = 5) => call("exec.run", {
+      target: "client", player: flag("player", undefined), source, timeoutSeconds,
+    }, (timeoutSeconds + 10) * 1000);
+    try {
+      const identity = await client('return game:GetService("RunService"):IsClient(), game:GetService("Players").LocalPlayer.Name');
+      check(identity.ok && identity.returned[0] === true && typeof identity.returned[1] === "string", "exec runs in the actual client VM");
+      const values = await client('print("client print"); warn("client warning"); local t = {}; t.self = t; return 1, nil, t, Vector3.new(1,2,3)');
+      check(values.ok && values.returned[1] === "nil" && values.returned[2].self === "<circular reference>", "client structured values preserve nil and cycles");
+      check(values.output.some(v => v.message.includes("client print")) && values.output.some(v => v.level === "warning"), "client prints and warnings captured");
+      const bounds = await client('for i=1,220 do print(i) end; local t = {}; for i=1,60 do t[i]=i end; return t,2,3,4,5,6,7,8,9,10,11');
+      check(bounds.ok && bounds.output.length === 200 && bounds.returned.length === 10 && bounds.returned[0].length === 51, "client output limits match Studio execution");
+      const failed = await client('print("before error"); error("client failure")');
+      check(!failed.ok && failed.error.includes("client failure") && failed.output.length > 0, "runtime failures retain output");
+      const syntax = await client('local =');
+      check(!syntax.ok && typeof syntax.error === "string", "client syntax errors are reported");
+      const timeout = await client('task.wait(30)', 1);
+      check(!timeout.ok && timeout.error.includes("CLIENT_TIMEOUT"), "yielding client execution times out cleanly");
+      await call("script.create", { scripts: [{ parent: "ReplicatedStorage", name: "__mcp_live_cache", className: "ModuleScript", source: "return {count = 0}" }] });
+      await client('local t = require(game.ReplicatedStorage.__mcp_live_cache); t.count = 42');
+      const cached = await client('return require(game.ReplicatedStorage.__mcp_live_cache).count');
+      check(cached.ok && cached.returned[0] === 42, "separate client calls share the client module cache");
+      const gui = await client(`
+local gui = Instance.new("ScreenGui"); gui.Name = "__mcp_live_gui"; gui.ResetOnSpawn = false
+local button = Instance.new("TextButton"); button.Name = "BuyButton"; button.Size = UDim2.fromOffset(160,60); button.Position = UDim2.fromOffset(100,100); button.Parent = gui
+local box = Instance.new("TextBox"); box.Name = "NameBox"; box.Size = UDim2.fromOffset(160,60); box.Position = UDim2.fromOffset(100,200); box.Text = ""; box.Parent = gui
+gui.Parent = game.Players.LocalPlayer.PlayerGui
+return true`);
+      check(gui.ok, "client-only GUI fixture created");
+      const typed = await call("input.send", { player: flag("player", undefined), cursor: false, steps: [{kind: "text", target: "PlayerGui.__mcp_live_gui.NameBox", text: "bridge"}] });
+      const text = await client('return game.Players.LocalPlayer.PlayerGui.__mcp_live_gui.NameBox.Text');
+      check(typed.delivered && text.returned[0] === "bridge", "GUI target focuses and types into the client TextBox");
+      const clicked = await call("input.send", { player: flag("player", undefined), cursor: false, steps: [{kind: "click", target: "PlayerGui.__mcp_live_gui.BuyButton"}] });
+      const centre = await client('local b=game.Players.LocalPlayer.PlayerGui.__mcp_live_gui.BuyButton; return b.AbsolutePosition.X+b.AbsoluteSize.X/2, b.AbsolutePosition.Y+b.AbsoluteSize.Y/2');
+      check(clicked.landed && Math.abs(clicked.landed.seen.x-centre.returned[0]) < 2 && Math.abs(clicked.landed.seen.y-centre.returned[1]) < 2, "GUI click lands at the actual client centre");
+      const missing = await call("input.send", { player: flag("player", undefined), cursor: false, steps: [{kind:"click",target:"PlayerGui.__missing"}] });
+      check(missing.notes?.some(note => note.includes("not found")), "missing GUI path reports a failure");
+      const clean = await call("exec.run", { source: 'local n=0; for _,p in game.Players:GetPlayers() do for _,v in p.PlayerGui:GetChildren() do if v.Name == "MCPExecRelay" or v.Name == "MCPInputRelay" then n+=1 end end end; return n' });
+      check(clean.returned[0] === 0, "temporary relay instances are removed after success, failure and timeout");
+    } catch (cause) {
+      check(false, `client: ${cause.message}`);
+    } finally {
+      await client('local g=game.Players.LocalPlayer.PlayerGui:FindFirstChild("__mcp_live_gui"); if g then g:Destroy() end').catch(() => {});
+      await call("instances.delete", {paths:["ReplicatedStorage.__mcp_live_cache"]}).catch(() => {});
+    }
+  }
+}
+
+// --remotes can run independently of GUI/input checks. The fixture's normal
+// server Script and LocalScript remain connected before, during and after tracing.
+if (args.includes("--remotes")) {
+  if (studio.buildId !== expectedPluginBuildId()) {
+    check(false, "remote tracing checks require the current plugin build");
+  } else {
+    const client = (source) => call("exec.run", {target:"client",player:flag("player",undefined),source,timeoutSeconds:10}, 20000);
+    const root = "ReplicatedStorage.__mcp_live_remotes";
+    const serverPath = "ServerScriptService.__mcp_live_remote_server";
+    let clientPath;
+    let capture;
+    const fixturePaths = [];
+    try {
+      const identity = await client('return game.Players.LocalPlayer.Name');
+      if (!identity.ok) throw new Error(identity.error);
+      const player = identity.returned[0];
+      clientPath = `Players.${player}.PlayerGui.__mcp_live_remote_client`;
+      const setup = await call("exec.run", {source:`
+assert(not game.ReplicatedStorage:FindFirstChild("__mcp_live_remotes"), "fixture already exists")
+assert(not game.ServerScriptService:FindFirstChild("__mcp_live_remote_server"), "server fixture already exists")
+assert(not game.Players[${JSON.stringify(player)}].PlayerGui:FindFirstChild("__mcp_live_remote_client"), "client fixture already exists")
+local folder = Instance.new("Folder"); folder.Name = "__mcp_live_remotes"; folder.Parent = game.ReplicatedStorage
+for _, name in {"Request", "Reply"} do local r=Instance.new("RemoteEvent"); r.Name=name; r.Parent=folder end
+return true`});
+      if (!setup.ok) throw new Error(setup.error);
+      fixturePaths.push(root, serverPath, clientPath);
+      await call("script.create", {scripts:[{parent:"ServerScriptService",name:"__mcp_live_remote_server",className:"Script",source:`
+local root = game.ReplicatedStorage:WaitForChild("__mcp_live_remotes")
+root:WaitForChild("Request").OnServerEvent:Connect(function(player, ...)
+ local args = table.pack(...)
+ root:SetAttribute("ServerCount", (root:GetAttribute("ServerCount") or 0) + 1)
+ root:SetAttribute("ServerValid", args.n == 3 and args[2] == nil and args[3].level == 37)
+ root.Reply:FireClient(player, args[1], nil, args[3].level)
+end)
+root:SetAttribute("Ready", true)`}, {parent:`Players.${player}.PlayerGui`,name:"__mcp_live_remote_client",className:"LocalScript",source:`
+local root = game.ReplicatedStorage:WaitForChild("__mcp_live_remotes")
+root:WaitForChild("Reply").OnClientEvent:Connect(function(...)
+ local args = table.pack(...)
+ script:SetAttribute("ClientCount", (script:GetAttribute("ClientCount") or 0) + 1)
+ script:SetAttribute("ClientValid", args.n == 3 and args[2] == nil and args[3] == 37)
+end)
+script:SetAttribute("Ready", true)`}]});
+      const send = (phase, count, expected, waitForTrace = false) => client(`
+local root = game.ReplicatedStorage:WaitForChild("__mcp_live_remotes")
+local gui = game.Players.LocalPlayer.PlayerGui
+local handler = gui:WaitForChild("__mcp_live_remote_client")
+local deadline = os.clock()+8
+repeat task.wait() until (root:GetAttribute("Ready") and handler:GetAttribute("Ready")) or os.clock()>deadline
+assert(root:GetAttribute("Ready") and handler:GetAttribute("Ready"), "fixture startup timed out")
+${waitForTrace ? `repeat task.wait() until (gui:FindFirstChild("MCPRemoteTraceRelay") and gui.MCPRemoteTraceRelay:GetAttribute("Capturing")) or os.clock()>deadline
+assert(gui:FindFirstChild("MCPRemoteTraceRelay") and gui.MCPRemoteTraceRelay:GetAttribute("Capturing"), "trace startup timed out")` : ""}
+for i=1,${count} do root.Request:FireServer("${phase}", nil, {level=37, nested={more={hidden=true}}}); task.wait(0.05) end
+repeat task.wait() until (handler:GetAttribute("ClientCount") or 0)>=${expected} or os.clock()>deadline
+return handler:GetAttribute("ClientCount"), handler:GetAttribute("ClientValid")`);
+      const before = await send("before", 1, 1);
+      check(before.ok && before.returned[0] === 1 && before.returned[1] === true, "fixture delivers normal traffic before tracing");
+      capture = call("debug.remotes", {path:root,player,seconds:4}, 20000);
+      // Attach a rejection handler immediately while the traffic call is running.
+      capture.catch(() => {});
+      const during = await send("during", 3, 4, true);
+      const trace = await capture;
+      check(during.ok && during.returned[0] === 4 && during.returned[1] === true, "client handlers receive unchanged arguments during tracing");
+      const upstream = trace.items.find(row => row.path.endsWith(".Request") && row.direction === "client -> server");
+      const downstream = trace.items.find(row => row.path.endsWith(".Reply") && row.direction === "server -> client");
+      check(upstream?.count === 3 && downstream?.count === 3 && trace.events === 6, "trace counts both directions without counting relay traffic");
+      check(upstream?.player === player && downstream?.player === player && upstream.callsPerSecond > 0 && downstream.callsPerSecond > 0, "trace identifies the player and reports rates");
+      check(upstream?.samples.some(sample => sample.includes("nil:nil") && sample.includes("table")), "trace summarizes argument shapes and nil positions");
+      check(Buffer.byteLength(JSON.stringify(trace)) <= 12000, "trace response obeys the hard size cap");
+      const after = await send("after", 1, 5);
+      check(after.ok && after.returned[0] === 5 && after.returned[1] === true, "client handlers still work after tracing cleanup");
+      const server = await call("exec.run", {source:'local f=game.ReplicatedStorage.__mcp_live_remotes; return f:GetAttribute("ServerCount"), f:GetAttribute("ServerValid")'});
+      check(server.ok && server.returned[0] === 5 && server.returned[1] === true, "server handler received every call exactly once with unchanged arguments");
+      const clean = await call("exec.run", {source:'for _,p in game.Players:GetPlayers() do if p.PlayerGui:FindFirstChild("MCPRemoteTraceRelay") then return false end end; return true'});
+      check(clean.ok && clean.returned[0] === true, "tracing removes temporary client relay instances");
+      const again = await call("debug.remotes", {path:root,player,seconds:1}, 16000);
+      check(again.events === 0, "a later capture starts empty and stops without traffic");
+    } catch (cause) {
+      check(false, `remotes: ${cause.message}`);
+    } finally {
+      if (capture) await capture.catch(() => {});
+      if (fixturePaths.length) await call("instances.delete", {paths:fixturePaths}).catch(cause => {
+        check(false, `remote fixture cleanup: ${cause.message}`);
+      });
+    }
+  }
+}
+
+// Set `playtests off` in the panel first. This opt-in check never attempts a
+// start unless Studio has confirmed OFF, and can be rerun after a Studio restart.
+if (args.includes("--playtests-off")) {
+  try {
+    const before = await call("playtest.control", {op:"state"});
+    if (before.state.playtestsAllowed !== false) {
+      check(false, "Set playtests off in the Studio MCP panel before running --playtests-off");
+    } else {
+      for (const op of ["play", "run", "multiplayer"]) {
+        try {
+          await call("playtest.control", {op,players:2});
+          check(false, `${op} must be refused while playtests are OFF`);
+        } catch (cause) {
+          check(cause.message.includes("PLAYTEST_DISABLED") && cause.message.includes("disabled by the user"), `${op} is blocked by the saved panel setting`);
+        }
+      }
+      const stopped = await call("playtest.control", {op:"stop"});
+      check(stopped.state.playtestsAllowed === false, "stop remains available while OFF");
+      const state = await call("playtest.control", {op:"state"});
+      check(state.state.playtestsAllowed === false, "state remains available and preserves OFF");
+    }
+  } catch (cause) {
+    check(false, `playtest lock: ${cause.message}`);
+  }
+}
+
+process.stdout.write(failures === 0 ? "live: ok\n" : `live: ${failures} failure(s)\n`);
+process.exit(failures === 0 ? 0 : 1);