goldsync 0.1.31 → 0.1.34

package/README.md

@@ -82,6 +82,16 @@ When changing a Folder to another class, Push the changed parent. GoldSync verif
 
 ## Daily use
 
+To make local files authoritative and replace the configured Studio roots completely, run:
+
+```powershell
+npx --yes goldsync@latest restore-studio --yes
+```
+
+Update GoldSync, restart Studio, and connect Rojo first. This command discards unsaved Studio changes inside the configured roots, removes extra instances, and resets their sync state. Other Studio roots and local files are unchanged. It validates every snapshot before replacing the roots and reports completion in the terminal. It requires version 2 tree roots.
+
+The command uses the files currently on disk. It does not fetch Git or remove old local `.rbxm` files. Restore the local assets from your intended Git revision first if that is the copy you want in Studio.
+
 Matching assets synchronize automatically. When an entry needs attention, choose the copy you want to keep:
 
 | Control | Direction |

package/assets/GoldSync.rbxmx

@@ -20,15 +20,17 @@ local SESSION_MARKER_NAME = "__GoldSyncSession"
 local CLIENT_HEADERS = {
 	["X-GoldSync-Client"] = "studio-plugin",
 	["X-GoldSync-Tree-Roots"] = "4",
+	["X-GoldSync-Restore"] = "1",
 }
 local SETTINGS_PREFIX = "GoldSync:v2:"
 local UI_SETTINGS_PREFIX = "GoldSync:ui:v1:"
-local VERSION = "0.1.31"
+local VERSION = "0.1.34"
 local startupProfile = { settings = 0, watchers = 0, reconcile = 0, downloads = 0 }
 local savedHashes = {}
 local savedHashesKey
 local hashesDirty = false
 local TreeRoots = require(script.Parent.TreeRoots)
+local StudioRestore = require(script.Parent.StudioRestore)
 local REQUEST_INTERVAL_SECONDS = 0.15
 local REQUEST_RETRY_DELAYS = { 1, 2, 4 }
 
@@ -393,6 +395,7 @@ rootsLayout.Parent = rootsContainer
 
 local running = true
 local bulkRunning = false
+local refreshing = false
 local requestLocked = false
 local requestWaiters = {}
 local lastRequestAt = 0
@@ -420,27 +423,41 @@ local resolveGitConflict
 local applyTreeFilter
 local resetInstanceTrees
 
+local function pullStates(affected)
+	table.sort(affected, function(left, right)
+		local leftDepth, rightDepth = #left.manifest.studioPath, #right.manifest.studioPath
+		if leftDepth ~= rightDepth then return leftDepth < rightDepth end
+		return left.manifest.id < right.manifest.id
+	end)
+	for _, state in affected do
+		if states[state.manifest.id] == state and not state.manifest.gitConflict then
+			pull(state)
+		end
+	end
+end
+
 for index, button in attentionBulkButtons do
 	button.Activated:Connect(function()
 		if bulkRunning or not serverConfig or not serverConfig.rojoConnected then
 			return
 		end
+		bulkRunning = true
+		while refreshing do task.wait() end
 		local affected = {}
 		for _, state in states do
 			if state.statusKind == "issue" and not state.manifest.gitConflict then
 				table.insert(affected, state)
 			end
 		end
-		bulkRunning = true
 		refreshStatusSummary()
-		for _, state in affected do
-			if states[state.manifest.id] ~= state or state.manifest.gitConflict then
-				continue
-			end
-			if index == 1 then
+		if index == 2 then
+			pullStates(affected)
+		else
+			for _, state in affected do
+				if states[state.manifest.id] ~= state or state.manifest.gitConflict then
+					continue
+				end
 				upload(state, true)
-			else
-				pull(state)
 			end
 		end
 		bulkRunning = false
@@ -1324,7 +1341,7 @@ deleteSnapshot = function(state, explicit)
 end
 
 upload = function(state, overwrite)
-	if state.coveredByBoundary then return end
+	if state.coveredByBoundary or state.suppress then return end
 	if state.uploading or state.pulling or state.deleting then
 		return
 	end
@@ -1422,6 +1439,7 @@ upload = function(state, overwrite)
 			setStatus(state, "Conversion failed: " .. tostring(packet), Color3.fromRGB(245, 106, 106))
 			return
 		end
+		if state.suppress then state.uploading = false return end
 		local response, failure = request("PUT", "/v1/roots/" .. state.manifest.id .. "/boundary", packet, { ["Content-Type"] = "application/octet-stream" })
 		state.uploading = false
 		if not response or not response.Success then
@@ -1474,6 +1492,7 @@ upload = function(state, overwrite)
 	end
 
 	local expectedHash = "*"
+	if state.suppress then state.uploading = false return end
 	if overwrite then
 		expectedHash = state.manifest.exists and state.manifest.hash or "*"
 	elseif state.lastHash then
@@ -2092,6 +2111,7 @@ local function createGroup(path, order, instanceIds, attention)
 			return
 		end
 		bulkRunning = true
+		while refreshing do task.wait() end
 		for _, state in states do
 			if group.attention and state.statusKind ~= "issue" then continue end
 			if pathStartsWith(group.path, state.manifest.studioPath, group.instanceIds, state.manifest.instanceIds) and not state.manifest.gitConflict then
@@ -2105,12 +2125,15 @@ local function createGroup(path, order, instanceIds, attention)
 			return
 		end
 		bulkRunning = true
+		while refreshing do task.wait() end
+		local affected = {}
 		for _, state in states do
 			if group.attention and state.statusKind ~= "issue" then continue end
 			if pathStartsWith(group.path, state.manifest.studioPath, group.instanceIds, state.manifest.instanceIds) and not state.manifest.gitConflict then
-				pull(state)
+				table.insert(affected, state)
 			end
 		end
+		pullStates(affected)
 		bulkRunning = false
 	end)
 	return group
@@ -3084,7 +3107,7 @@ local function manifestChanged(previous, current)
 		or TreeRoots.pathKey(previous.studioPath, previous.instanceIds) ~= TreeRoots.pathKey(current.studioPath, current.instanceIds)
 end
 
-refreshConfig = function()
+local function refreshConfigNow()
 	local refreshStarted = os.clock()
 	local response, requestError = request("GET", "/v1/config", nil, if configETag then { ["If-None-Match"] = configETag } else nil)
 	if not response or (not response.Success and response.StatusCode ~= 304) then
@@ -3130,6 +3153,56 @@ refreshConfig = function()
 		table.clear(groups)
 	end
 	serverConfig = decoded
+	if decoded.restore and decoded.restore.status == "pending" then
+		bulkRunning = true
+		for _, state in states do
+			state.generation += 1
+			state.suppress = true
+		end
+		local prepared
+		local success, failure = pcall(function()
+			local base = "/v1/restore/" .. decoded.restore.id
+			local response, failure = request("POST", base .. "/claim")
+			assert(response and response.Success, failure or (response and responseError(response)) or "Restore download failed")
+			connectionStatus.Text = "Restoring Studio from local files..."
+			prepared = StudioRestore.prepare(response.Body)
+			local authorized = request("POST", base .. "/commit")
+			assert(authorized and authorized.Success, "Restore expired or Rojo disconnected; Studio was not replaced")
+			for _, state in states do disconnectRoot(state) end
+			disconnectSplitRoots()
+			ChangeHistoryService:SetWaypoint("GoldSync before authoritative restore")
+			StudioRestore.commit(prepared)
+			ChangeHistoryService:SetWaypoint("GoldSync restore from local files")
+			for _, state in states do
+				destroyConflictWorkspace(state)
+				destroyRootRow(state)
+			end
+			table.clear(states)
+			table.clear(treeDiscovery)
+			table.clear(savedHashes)
+			for _, manifest in prepared.manifests do savedHashes[manifest.id] = manifest.hash end
+			hashesDirty = true
+			saveHashes()
+		end)
+		if not success and prepared then prepared.staging:Destroy() end
+		local acknowledged = request("POST", "/v1/restore/" .. decoded.restore.id .. "/result", HttpService:JSONEncode({ success = success, error = if success then nil else tostring(failure) }), { ["Content-Type"] = "application/json" })
+		bulkRunning = false
+		configETag = nil
+		if not success then
+			for _, state in states do
+				state.suppress = false
+				state.root = nil
+				state.observedRoot = nil
+			end
+			connectionStatus.Text = "Restore failed: " .. tostring(failure)
+		elseif not acknowledged or not acknowledged.Success then
+			connectionStatus.Text = "Studio restored, but the service did not acknowledge completion."
+		else
+			connectionStatus.Text = "Restored Studio from local files"
+		end
+		return success
+	end
+	if decoded.restore and (decoded.restore.status == "preparing" or decoded.restore.status == "running") then return true end
 	if decoded.rojoConnected then
 		connectionStatus.Text = "Connected · " .. decoded.name
 		connectionStatus.TextColor3 = Color3.fromRGB(102, 214, 139)
@@ -3197,6 +3270,16 @@ refreshConfig = function()
 		disconnectSplitRoot(id)
 	end
 
+	local presentRoots = {}
+	for _, manifest in decoded.roots do
+		if manifest.treeRootId and not manifest.container and not manifest.exists and not manifest.gitConflict
+			and not resolveRoot(manifest.studioPath, manifest.instanceIds) then
+			continue
+		end
+		table.insert(presentRoots, manifest)
+	end
+	decoded.roots = presentRoots
+
 	local boundaryPaths = {}
 	for _, manifest in decoded.roots do
 		local discovery = treeDiscovery[manifest.treeRootId]
@@ -3298,6 +3381,19 @@ refreshConfig = function()
 	return true
 end
 
+refreshConfig = function()
+	if bulkRunning or refreshing then return false end
+	refreshing = true
+	local success, result = pcall(refreshConfigNow)
+	refreshing = false
+	if not success then
+		batchingStatusUpdates = false
+		warn("GoldSync refresh failed: " .. tostring(result))
+		return false
+	end
+	return result
+end
+
 toolbarButton.Click:Connect(function()
 	widget.Enabled = not widget.Enabled
 	if widget.Enabled then
@@ -3328,6 +3424,100 @@ end)
       </Properties>
     </Item>
     <Item class="ModuleScript" referent="2">
+      <Properties>
+        <string name="Name">StudioRestore</string>
+        <string name="Source"><![CDATA[local HttpService = game:GetService("HttpService")
+local SerializationService = game:GetService("SerializationService")
+local TreeRoots = require(script.Parent.TreeRoots)
+
+local StudioRestore = {}
+
+function StudioRestore.prepare(body)
+	local staging = Instance.new("Folder")
+	local success, result = pcall(function()
+		local bytes = buffer.fromstring(body)
+		local headerLength = buffer.readu32(bytes, 0)
+		local packet = HttpService:JSONDecode(buffer.readstring(bytes, 4, headerLength))
+		local offset = 4 + headerLength
+		local instances, roots = {}, {}
+		local trees = {}
+		for _, tree in packet.trees do
+			trees[tree.id] = TreeRoots.pathKey(tree.studioPath)
+		end
+		for _, manifest in packet.roots do
+			local key = TreeRoots.pathKey(manifest.studioPath, manifest.instanceIds)
+			assert(not instances[key], "Duplicate restore path")
+			local isRoot = trees[manifest.treeRootId] == key
+			local instance
+			if manifest.exists then
+				local restored = SerializationService:DeserializeInstancesAsync(buffer.fromstring(buffer.readstring(bytes, offset, manifest.size)))
+				for _, candidate in restored do candidate.Parent = staging end
+				assert(#restored == 1, "Snapshot must contain one root: " .. manifest.file)
+				instance = restored[1]
+			else
+				assert(manifest.container and manifest.size == 0, "Missing asset snapshot: " .. manifest.file)
+				instance = Instance.new("Folder")
+				instance.Name = manifest.studioPath[#manifest.studioPath]
+				local id = manifest.instanceIds[#manifest.studioPath]
+				if id ~= "" then instance:SetAttribute("GoldSyncId", id) end
+				instance.Parent = staging
+			end
+			offset += manifest.size
+			assert(instance.Name == manifest.studioPath[#manifest.studioPath], "Snapshot name does not match " .. manifest.file)
+			assert((instance:GetAttribute("GoldSyncId") or "") == manifest.instanceIds[#manifest.studioPath], "Snapshot identity does not match " .. manifest.file)
+			assert(TreeRoots.isContainer(instance, isRoot) == manifest.container, "Snapshot class does not match " .. manifest.file)
+			assert(not manifest.container or #instance:GetChildren() == 0, "Container snapshot contains children: " .. manifest.file)
+			if isRoot then
+				table.insert(roots, { instance = instance, path = manifest.studioPath })
+			else
+				local parentKey = TreeRoots.pathKey(manifest.studioPath, manifest.instanceIds, #manifest.studioPath - 1)
+				assert(instances[parentKey], "Restore parent is missing: " .. manifest.file)
+				instance.Parent = instances[parentKey]
+			end
+			instances[key] = instance
+		end
+		assert(offset == buffer.len(bytes), "Unexpected restore packet data")
+		assert(#roots == #packet.trees, "Restore is missing a configured root")
+		return { staging = staging, roots = roots, manifests = packet.roots }
+	end)
+	if not success then
+		staging:Destroy()
+		error(result)
+	end
+	return result
+end
+
+function StudioRestore.commit(prepared)
+	local previous = {}
+	for _, root in prepared.roots do
+		local parent = game
+		for depth = 1, #root.path - 1 do
+			parent = parent:FindFirstChild(root.path[depth])
+			assert(parent, "Configured Studio parent is missing: " .. table.concat(root.path, "."))
+		end
+		root.parent = parent
+		for _, child in parent:GetChildren() do
+			if child.Name == root.instance.Name then table.insert(previous, { instance = child, parent = parent }) end
+		end
+	end
+	local success, failure = pcall(function()
+		for _, root in previous do root.instance.Parent = nil end
+		for _, root in prepared.roots do root.instance.Parent = root.parent end
+	end)
+	if not success then
+		for _, root in prepared.roots do root.instance.Parent = prepared.staging end
+		for _, root in previous do root.instance.Parent = root.parent end
+		error(failure)
+	end
+	for _, root in previous do root.instance:Destroy() end
+	prepared.staging:Destroy()
+end
+
+return StudioRestore
+]]></string>
+      </Properties>
+    </Item>
+    <Item class="ModuleScript" referent="3">
       <Properties>
         <string name="Name">TreeRoots</string>
         <string name="Source"><![CDATA[local TreeRoots = {}

package/bin/install-companion.mjs

@@ -5,11 +5,11 @@ import { access, copyFile, cp, mkdir, readFile, rm, writeFile } from "node:fs/pr
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
-import { findProjectConfig, registerProject } from "../src/companion.mjs";
+import { findProjectConfig, registerProject, restoreStudio } from "../src/companion.mjs";
 
 const command = process.argv[2];
 if (command === "--help" || command === "-h") {
-  console.log("Run 'goldsync install' from a repository containing goldsync.project.json.");
+  console.log("goldsync install\ngoldsync restore-studio --yes\nRun from your project folder. restore-studio replaces configured Studio roots with local files and discards their unsaved Studio changes.");
   process.exit(0);
 }
 if (command === "--version" || command === "-v") {
@@ -17,7 +17,7 @@ if (command === "--version" || command === "-v") {
   console.log(packageJson.version);
   process.exit(0);
 }
-if (command && command !== "install" && !command.startsWith("--")) {
+if (command && command !== "install" && command !== "restore-studio" && !command.startsWith("--")) {
   throw new Error(`Unknown GoldSync command: ${command}`);
 }
 
@@ -36,6 +36,12 @@ const configPath = configIndex === -1
   ? await findProjectConfig(projectDirectory)
   : path.resolve(process.argv[configIndex + 1]);
 
+if (command === "restore-studio") {
+  if (!process.argv.includes("--yes")) throw new Error("This replaces configured Studio roots and discards their unsaved changes. Run restore-studio --yes to proceed.");
+  await restoreStudio(configPath);
+  process.exit(0);
+}
+
 const dataDirectory = path.join(process.env.LOCALAPPDATA, "GoldSync");
 const runtimeDirectory = path.join(dataDirectory, "runtime");
 const installedAgent = path.join(runtimeDirectory, "bin", "goldsync-agent.mjs");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goldsync",
-  "version": "0.1.31",
+  "version": "0.1.34",
   "description": "Automatic native Roblox asset synchronization for Rojo projects.",
   "author": "tay",
   "license": "SEE LICENSE IN LICENSE.txt",

package/src/broker.mjs

@@ -237,7 +237,23 @@ export class GoldSyncBroker {
 
   async handle(request, response) {
     const url = new URL(request.url, `http://${this.host}:${this.port}`);
-    const managementRequest = MANAGEMENT_CLIENTS.has(request.headers["x-goldsync-client"]);
+    const managementRequest = request.headers.origin === undefined && MANAGEMENT_CLIENTS.has(request.headers["x-goldsync-client"]);
+    if (managementRequest && url.pathname === "/v1/workspaces/restore-studio") {
+      const body = request.method === "POST" ? await readJson(request) : null;
+      const runtime = this.workspaces.get(body?.workspaceId ?? url.searchParams.get("workspaceId"));
+      if (!runtime) { sendJson(response, 404, { error: "GoldSync project is not registered" }); return; }
+      if (request.method === "POST") {
+        if (body.confirm !== true) { sendJson(response, 400, { error: "restore-studio requires --yes" }); return; }
+        sendJson(response, 200, await runtime.server.beginRestore());
+      } else if (request.method === "GET") {
+        const status = runtime.server.restoreStatus();
+        if (!status || status.id !== url.searchParams.get("id")) { sendJson(response, 404, { error: "Restore operation no longer exists" }); return; }
+        sendJson(response, 200, status);
+      } else {
+        sendJson(response, 405, { error: "Method not allowed" });
+      }
+      return;
+    }
     if (managementRequest && request.method === "GET" && url.pathname === "/v1/health") {
       sendJson(response, 200, {
         version: 1,

package/src/companion.mjs

@@ -4,6 +4,7 @@ import http from "node:http";
 import path from "node:path";
 import { GoldSyncBroker } from "./broker.mjs";
 import { loadConfig } from "./config.mjs";
+import { setTimeout as delay } from "node:timers/promises";
 
 export const BROKER_PORT = 34873;
 export const HEARTBEAT_MS = 5000;
@@ -26,7 +27,7 @@ function request(method, requestPath, body, port = BROKER_PORT) {
               }
             : {}),
         },
-        timeout: requestPath === "/v1/workspaces/register" ? 120000 : 2000,
+        timeout: requestPath === "/v1/workspaces/register" || (method === "POST" && requestPath === "/v1/workspaces/restore-studio") ? 120000 : 2000,
       },
       (response) => {
         const chunks = [];
@@ -59,6 +60,20 @@ function request(method, requestPath, body, port = BROKER_PORT) {
   });
 }
 
+export async function restoreStudio(configPath) {
+  const workspace = await request("POST", "/v1/workspaces/register", { configPath, clientId: randomUUID() });
+  let job = await request("POST", "/v1/workspaces/restore-studio", { workspaceId: workspace.workspaceId, confirm: true });
+  console.log("Replacing configured Studio roots with local assets. Unsaved Studio changes in those roots will be removed.");
+  const deadline = Date.now() + 330000;
+  while (["pending", "running", "preparing"].includes(job.status)) {
+    if (Date.now() > deadline) throw new Error("Restore did not finish. Check Studio before retrying.");
+    await delay(500);
+    job = await request("GET", `/v1/workspaces/restore-studio?workspaceId=${encodeURIComponent(workspace.workspaceId)}&id=${encodeURIComponent(job.id)}`);
+  }
+  if (job.status !== "completed") throw new Error(job.error ?? "Studio restore failed");
+  console.log("Studio now matches the local asset files. Stale instances and previous sync state were removed.");
+}
+
 async function fileExists(file) {
   try {
     await access(file);

package/src/restore.mjs

@@ -0,0 +1,34 @@
+import { stat } from "node:fs/promises";
+import { SnapshotStore } from "./store.mjs";
+import { GitConflictStore } from "./git-conflicts.mjs";
+
+export async function prepareRestore(config) {
+  if (config.version !== 2 || !config.treeRoots?.length || config.roots.length || config.splitRoots?.length) {
+    throw new Error("restore-studio requires a project containing only version 2 tree roots");
+  }
+  for (const tree of config.treeRoots) {
+    if (!(await stat(tree.absoluteDirectory)).isDirectory()) throw new Error(`Missing asset directory: ${tree.directory}`);
+  }
+  const store = new SnapshotStore(config);
+  await store.initialize();
+  const conflicts = new GitConflictStore(config);
+  await conflicts.initialize();
+  conflicts.syncRoots(store.getRoots());
+  if ((await conflicts.list()).size) throw new Error("Resolve asset Git conflicts before restoring Studio");
+  const roots = store.getManifests();
+  roots.sort((left, right) => left.studioPath.length - right.studioPath.length || left.id.localeCompare(right.id));
+  const chunks = [];
+  let size = 0;
+  for (const root of roots) {
+    const snapshot = await store.get(root.id);
+    if (root.exists && (!snapshot || snapshot.hash !== root.hash)) throw new Error(`File changed during restore preparation: ${root.file}`);
+    root.size = snapshot?.bytes.length ?? 0;
+    if (snapshot) chunks.push(snapshot.bytes);
+    size += root.size;
+    if (size > 128 * 1024 * 1024) throw new Error("Restore exceeds the 128 MiB limit");
+  }
+  const header = Buffer.from(JSON.stringify({ roots, trees: config.treeRoots.map(({ id, studioPath }) => ({ id, studioPath })) }));
+  const length = Buffer.alloc(4);
+  length.writeUInt32LE(header.length);
+  return { store, packet: Buffer.concat([length, header, ...chunks]) };
+}

package/src/server.mjs

@@ -1,8 +1,9 @@
 import { watch } from "node:fs";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { createServer } from "node:http";
 import path from "node:path";
 import { ConflictError } from "./store.mjs";
+import { prepareRestore } from "./restore.mjs";
 
 const MAX_SNAPSHOT_BYTES = 128 * 1024 * 1024;
 
@@ -66,9 +67,50 @@ export class GoldSyncServer {
   }
 
   setSessionToken(token) {
+    if (token !== this.sessionToken && this.restoreJob) {
+      this.restoreJob.status = "failed";
+      this.restoreJob.error = "Rojo session changed; run restore-studio again";
+      this.restoreJob.packet = null;
+      this.restoreJob.store = null;
+    }
+    if (token !== this.sessionToken) this.lastRestoreClient = null;
     this.sessionToken = token;
   }
 
+  restoreStatus() {
+    const job = this.restoreJob;
+    if (!job) return null;
+    if ((job.status === "pending" && Date.now() - job.createdAt > 15000)
+      || (job.status === "running" && Date.now() - job.createdAt > 300000)) {
+      job.status = "failed";
+      job.error = "Studio restore timed out. Check Studio, update the plugin and reconnect before retrying.";
+      job.packet = null;
+      job.store = null;
+    }
+    return { id: job.id, status: job.status, error: job.error };
+  }
+
+  async beginRestore() {
+    if (!this.syncEnabled || !this.sessionToken) throw new Error("Connect Studio through Rojo before restoring");
+    if (!this.lastRestoreClient || Date.now() - this.lastRestoreClient > 10000) throw new Error("Open Studio with GoldSync 0.1.34 or newer and connect Rojo first");
+    if (this.store.boundaryChange || ["preparing", "pending", "running"].includes(this.restoreStatus()?.status)) throw new Error("A sync operation is already running");
+    const job = { id: randomUUID(), status: "preparing", createdAt: Date.now() };
+    this.restoreJob = job;
+    try {
+      Object.assign(job, await prepareRestore(this.config));
+      if (job.status !== "preparing") throw new Error("Rojo session changed while preparing restore");
+      job.status = "pending";
+      job.createdAt = Date.now();
+    } catch (error) {
+      job.status = "failed";
+      job.error = error.message;
+      job.packet = null;
+      job.store = null;
+      throw error;
+    }
+    return this.restoreStatus();
+  }
+
   async start(options = {}) {
     if (options.listen !== false) {
       await new Promise((resolve, reject) => {
@@ -157,6 +199,46 @@ export class GoldSyncServer {
       return;
     }
     const url = new URL(request.url, `http://${this.config.host}:${this.config.port}`);
+    if (request.headers["x-goldsync-restore"] === "1") this.lastRestoreClient = Date.now();
+    const restoreMatch = /^\/v1\/restore\/([a-f0-9-]+)\/(claim|commit|result)$/.exec(url.pathname);
+    if (request.method === "POST" && restoreMatch) {
+      const job = this.restoreJob;
+      const status = this.restoreStatus();
+      if (job?.id === restoreMatch[1] && restoreMatch[2] === "result" && ["completed", "failed"].includes(status.status)) {
+        sendJson(response, 200, status); return;
+      }
+      if (!this.syncEnabled || !job || job.id !== restoreMatch[1] || !["pending", "running"].includes(status.status)) {
+        sendJson(response, 409, { error: "Restore is no longer active" }); return;
+      }
+      if (restoreMatch[2] === "claim") {
+        if (job.status !== "pending") { sendJson(response, 409, { error: "Restore was already claimed" }); return; }
+        job.status = "running";
+        job.createdAt = Date.now();
+        response.writeHead(200, { "Content-Type": "application/octet-stream", "Content-Length": job.packet.length });
+        response.end(job.packet);
+        return;
+      }
+      if (job.status !== "running") { sendJson(response, 409, { error: "Claim the restore first" }); return; }
+      if (restoreMatch[2] === "result") {
+        const result = JSON.parse((await readBody(request)).toString("utf8"));
+        if (typeof result.success !== "boolean") { sendJson(response, 400, { error: "Expected restore result" }); return; }
+        job.status = result.success ? "completed" : "failed";
+        job.error = result.success ? undefined : String(result.error ?? "Studio restore failed").slice(0, 2000);
+        if (result.success) {
+          this.store = job.store;
+          this.store.treeScanNeeded = true;
+          this.gitConflicts?.syncRoots(this.store.getRoots());
+        }
+        job.packet = null;
+        job.store = null;
+      }
+      sendJson(response, 200, this.restoreStatus());
+      return;
+    }
+    const restore = this.restoreStatus();
+    if (["preparing", "pending", "running"].includes(restore?.status) && url.pathname !== "/v1/config") {
+      sendJson(response, 409, { error: "Authoritative Studio restore in progress" }); return;
+    }
     if (this.store.boundaryChange) {
       sendJson(response, 409, { error: "Boundary conversion in progress; retry after it finishes" });
       return;
@@ -204,6 +286,7 @@ export class GoldSyncServer {
         pollIntervalMs: this.config.pollIntervalMs,
         debounceMs: this.config.debounceMs,
         rojoConnected: this.syncEnabled,
+        restore,
         treeRoots: (this.config.treeRoots ?? []).map((root) => ({ id: root.id, studioPath: root.studioPath })),
         splitRoots: (this.config.splitRoots ?? []).map((root) => ({
           id: root.id,

package/src/store.mjs

@@ -363,20 +363,35 @@ export class SnapshotStore {
       const entries = [];
       const visit = async (directory, relativePath, instanceIds) => {
         if (tree.studioPath.length + relativePath.length > this.config.maxPathDepth) throw new Error(`tree root ${tree.id} exceeds maxPathDepth`);
-        entries.push({ path: relativePath, instanceIds, container: true });
+        const start = entries.length;
+        let metadata = false;
         for (const entry of await readdir(directory, { withFileTypes: true })) {
           if (entry.isSymbolicLink()) throw new Error(`tree roots cannot contain symbolic links: ${entry.name}`);
           if (entry.isDirectory()) {
             const segment = decodeTreeSegment(entry.name);
             await visit(path.join(directory, entry.name), [...relativePath, segment.name], [...instanceIds, segment.id]);
-          } else if (entry.isFile() && entry.name.toLowerCase().endsWith(".rbxm") && entry.name !== "_root.rbxm") {
+          } else if (entry.isFile() && entry.name === "_root.rbxm") {
+            metadata = true;
+          } else if (entry.isFile() && entry.name.toLowerCase().endsWith(".rbxm")) {
             const segment = decodeTreeSegment(entry.name.slice(0, -5));
             entries.push({ path: [...relativePath, segment.name], instanceIds: [...instanceIds, segment.id], container: false });
           }
         }
+        if (relativePath.length === 0 || metadata || entries.length > start) {
+          entries.push({ path: relativePath, instanceIds, container: true });
+        }
       };
       await visit(tree.absoluteDirectory, [], []);
+      const containers = new Set(entries.filter(entry => entry.container)
+        .map(entry => this.makeTreeRoot(tree, entry.path, true, entry.instanceIds).id));
+      for (const [id, root] of this.roots) {
+        if (root.treeRootId !== tree.id || !root.diskContainer || containers.has(id)) continue;
+        this.roots.delete(id);
+        this.rootsByFile.delete(root.absoluteFile.toLowerCase());
+        this.manifestRoots = null;
+      }
       await this.discoverTreePaths(tree.id, entries);
+      for (const id of containers) this.roots.get(id).diskContainer = true;
     }
   }