clay-server 4.0.0-beta.8 → 4.0.0

package/lib/session-provenance.js

@@ -0,0 +1,119 @@
+var crypto = require("crypto");
+
+var PROVENANCE_VERSION = 1;
+var MAX_ORIGIN_LENGTH = 128;
+
+function safeOriginId(value) {
+  if (typeof value !== "string") return null;
+  var trimmed = value.trim();
+  if (!trimmed || trimmed.length > MAX_ORIGIN_LENGTH) return null;
+  return trimmed;
+}
+
+function ensureOrigin(session) {
+  if (!session) return null;
+  var existing = safeOriginId(session.sessionOriginId);
+  if (existing) {
+    session.sessionOriginId = existing;
+    return existing;
+  }
+  session.sessionOriginId = crypto.randomUUID();
+  return session.sessionOriginId;
+}
+
+function isWorker(session) {
+  return !!(session && session.sessionProvenance && session.sessionProvenance.kind === "worker");
+}
+
+function nextWorkerGeneration(parentOriginId, sessions) {
+  var next = 1;
+  sessions.forEach(function (session) {
+    var provenance = session && session.sessionProvenance;
+    if (!provenance || provenance.kind !== "worker" || provenance.parentSessionOriginId !== parentOriginId) return;
+    var generation = Number.isInteger(provenance.generation) && provenance.generation > 0 ? provenance.generation : 0;
+    if (generation >= next) next = generation + 1;
+  });
+  return next;
+}
+
+function markWorker(driver, worker, sessions) {
+  if (!driver || !worker || driver === worker) throw new Error("Split Worker provenance requires distinct sessions");
+  if ((driver.ownerId || null) !== (worker.ownerId || null)) throw new Error("Split Worker provenance requires the same owner");
+  if (isWorker(driver)) throw new Error("A Split Worker cannot become a Driver");
+  var parentOriginId = ensureOrigin(driver);
+  ensureOrigin(worker);
+  worker.sessionProvenance = {
+    version: PROVENANCE_VERSION,
+    kind: "worker",
+    parentSessionOriginId: parentOriginId,
+    generation: nextWorkerGeneration(parentOriginId, sessions),
+    createdVia: "split-worker",
+    createdAt: Date.now(),
+  };
+  return worker.sessionProvenance;
+}
+
+function restore(meta, session) {
+  var storedOriginId = safeOriginId(meta && meta.sessionOriginId);
+  ensureOrigin(session);
+  var stored = meta && meta.sessionProvenance;
+  if (!stored || stored.kind !== "worker") return storedOriginId !== session.sessionOriginId;
+  var parentOriginId = safeOriginId(stored.parentSessionOriginId);
+  // A corrupt Worker record remains a Worker. It is projected as orphaned
+  // instead of silently gaining top-level Driver authority.
+  session.sessionProvenance = {
+    version: PROVENANCE_VERSION,
+    kind: "worker",
+    parentSessionOriginId: parentOriginId,
+    generation: Number.isInteger(stored.generation) && stored.generation > 0 ? stored.generation : null,
+    createdVia: stored.createdVia === "split-worker" ? "split-worker" : null,
+    createdAt: typeof stored.createdAt === "number" && isFinite(stored.createdAt) ? stored.createdAt : null,
+  };
+  return storedOriginId !== session.sessionOriginId || JSON.stringify(stored) !== JSON.stringify(session.sessionProvenance);
+}
+
+function metadata(session) {
+  var result = { sessionOriginId: ensureOrigin(session) };
+  if (isWorker(session)) result.sessionProvenance = Object.assign({}, session.sessionProvenance);
+  return result;
+}
+
+function hierarchyFor(sessions) {
+  var originMap = {};
+  var duplicateOrigins = {};
+  for (var i = 0; i < sessions.length; i++) {
+    var originId = safeOriginId(sessions[i] && sessions[i].sessionOriginId);
+    if (!originId) continue;
+    if (originMap[originId]) duplicateOrigins[originId] = true;
+    else originMap[originId] = sessions[i];
+  }
+  var result = {};
+  for (var j = 0; j < sessions.length; j++) {
+    var session = sessions[j];
+    if (!isWorker(session)) {
+      result[session.localId] = { role: "driver", parentSessionId: null, parentAvailable: false, generation: null };
+      continue;
+    }
+    var provenance = session.sessionProvenance;
+    var parentOriginId = safeOriginId(provenance.parentSessionOriginId);
+    var parent = duplicateOrigins[parentOriginId] ? null : originMap[parentOriginId];
+    var sameOwner = parent && (parent.ownerId || null) === (session.ownerId || null);
+    var validParent = sameOwner && !isWorker(parent) ? parent : null;
+    result[session.localId] = {
+      role: "worker",
+      parentSessionId: validParent ? validParent.localId : null,
+      parentAvailable: !!validParent,
+      generation: Number.isInteger(provenance.generation) && provenance.generation > 0 ? provenance.generation : null,
+    };
+  }
+  return result;
+}
+
+module.exports = {
+  ensureOrigin: ensureOrigin,
+  hierarchyFor: hierarchyFor,
+  isWorker: isWorker,
+  markWorker: markWorker,
+  metadata: metadata,
+  restore: restore,
+};

package/lib/session-spawn-mcp-server.js

@@ -27,7 +27,7 @@ function getToolDefs(handlers) {
   return [
     {
       name: "spawn_sessions",
-      description: "Create sibling work sessions in this project. Set forkFromCurrent to copy this session's full conversation context into every child. Children share the project's working directory, so prefer parallel analysis or other non-conflicting work over concurrent edits. Results can be polled with check_spawned_sessions; spawned children cannot spawn further sessions.",
+      description: "Create ordinary sibling work sessions for background parallel work. This does not create a visible Driver/Split Worker pair and must not be used when the user asks for a Worker, paired pane, or split collaborator; use send_to_partner for that. Set forkFromCurrent to copy this session's full conversation context into every child. Children share the project's working directory, so prefer parallel analysis or other non-conflicting work over concurrent edits. Results can be polled with check_spawned_sessions; spawned children cannot spawn further sessions.",
       inputSchema: buildShape({
         sessions: { type: "string", description: "JSON array of objects: [{\"title\":\"Task title\",\"prompt\":\"Task instructions\"}]" },
         vendor: { type: "string", description: "Optional vendor id. Defaults to the parent session vendor, then the project default." },

package/lib/session-split-groups.js

@@ -280,7 +280,10 @@ function attachSplitGroups(ctx) {
   });
 
   function sendState(ws) {
-    if (!ws || ws._clayPane) return;
+    if (!ws) return;
+    // Pane clients need the same owner-scoped pair roles as the parent shell.
+    // The Worker composer lock resolves its role from this projection; hiding
+    // the projection from panes leaves a configured Worker looking editable.
     ctx.sendTo(ws, { type: "split_groups", groups: store.listFor(ws) });
   }
 

package/lib/session-title-policy.js

@@ -0,0 +1,60 @@
+// Session title policy shared by query startup and completed-turn processing.
+// Initial titles are immediate, provisional UI labels. Model-generated titles
+// replace them after enough conversation exists to describe the actual topic.
+
+var DEFAULT_GENERATION_TURN = 2;
+var HOME_GENERATION_TURN = 1;
+var MAX_PROVISIONAL_CHARS = 60;
+var LEGACY_SEARCH_TITLE = "This conversation began in Clay Studio's global search.";
+
+function cleanText(value) {
+  if (typeof value !== "string") return "";
+  return value.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
+}
+
+function firstRecordedUserMessage(session) {
+  var history = session && Array.isArray(session.history) ? session.history : [];
+  for (var i = 0; i < history.length; i++) {
+    if (history[i] && history[i].type === "user_message") {
+      var text = cleanText(history[i].text);
+      if (text) return text;
+    }
+  }
+  return "";
+}
+
+function selectInitialTitle(session, transportText) {
+  var existing = cleanText(session && session.title);
+  if (existing) return { title: existing, provisional: false };
+
+  // Prefer the visible message recorded in history. Query transports may wrap
+  // it in identical provider instructions, as global Ask Clay does.
+  var source = firstRecordedUserMessage(session) || cleanText(transportText);
+  if (source.length < 10) return { title: null, provisional: false };
+  return {
+    title: source.length > MAX_PROVISIONAL_CHARS ? source.substring(0, MAX_PROVISIONAL_CHARS) : source,
+    provisional: true,
+  };
+}
+
+function generationTurn(isMate) {
+  return isMate === true ? HOME_GENERATION_TURN : DEFAULT_GENERATION_TURN;
+}
+
+function repairLegacySearchTitle(session) {
+  var title = cleanText(session && session.title);
+  if (!session || title.indexOf(LEGACY_SEARCH_TITLE) !== 0) return false;
+  var source = firstRecordedUserMessage(session);
+  if (!source) return false;
+  session.title = source.length > MAX_PROVISIONAL_CHARS ? source.substring(0, MAX_PROVISIONAL_CHARS) : source;
+  session.titleAutoGenerated = false;
+  return true;
+}
+
+module.exports = {
+  DEFAULT_GENERATION_TURN: DEFAULT_GENERATION_TURN,
+  HOME_GENERATION_TURN: HOME_GENERATION_TURN,
+  selectInitialTitle: selectInitialTitle,
+  generationTurn: generationTurn,
+  repairLegacySearchTitle: repairLegacySearchTitle,
+};

package/lib/session-visibility.js

@@ -0,0 +1,41 @@
+function normalize(value) {
+  return value === "shared" ? "shared" : "private";
+}
+
+function restore(meta) {
+  // Older releases persisted the shared default without recording intent.
+  return meta.sessionVisibilityExplicit === true ? normalize(meta.sessionVisibility) : "private";
+}
+
+function handleChange(ctx, ws, msg) {
+  if (typeof msg.sessionId !== "number" || (msg.visibility !== "shared" && msg.visibility !== "private")) return;
+  var session = ctx.sm.sessions.get(msg.sessionId);
+  if (!session) return;
+  if (ctx.usersModule.isMultiUser()) {
+    var user = ws._clayUser;
+    var project = ctx.getProjectAccess ? ctx.getProjectAccess() : { visibility: "public" };
+    if (!user || !session.ownerId || session.ownerId !== user.id ||
+        !ctx.usersModule.canAccessSession(user.id, session, project)) return;
+  } else if (session.ownerId) {
+    return;
+  }
+  ctx.sm.setSessionVisibility(msg.sessionId, msg.visibility);
+  revokeViewers(ctx, session);
+}
+
+function revokeViewers(ctx, session) {
+  if (ctx.usersModule.isMultiUser() && session.sessionVisibility === "private") {
+    var project = ctx.getProjectAccess ? ctx.getProjectAccess() : null;
+    ctx.clients.forEach(function(client) {
+      if (client._clayActiveSession !== session.localId) return;
+      var userId = client._clayUser && client._clayUser.id;
+      if (userId && ctx.usersModule.canAccessSession(userId, session, project)) return;
+      // Clear the server-side selection before reconnecting so no further
+      // session events or input can cross the revoked access boundary.
+      client._clayActiveSession = null;
+      if (client.readyState === 1) client.close(1008, "Session access changed");
+    });
+  }
+}
+
+module.exports = { normalize: normalize, restore: restore, handleChange: handleChange, revokeViewers: revokeViewers };

package/lib/sessions.js

@@ -6,6 +6,8 @@ var users = require("./users");
 var { CODEX_DEFAULTS } = require("./codex-defaults");
 var hygiene = require("./session-hygiene");
 var backgroundTaskTiming = require("./background-task-timing");
+var sessionProvenance = require("./session-provenance");
+var sessionVisibility = require("./session-visibility");
 
 function createSessionManager(opts) {
   var cwd = opts.cwd;
@@ -165,7 +167,8 @@ function createSessionManager(opts) {
       if (session.dangerouslySkipPermissions) metaObj.dangerouslySkipPermissions = true;
       if (session.permissionMode) metaObj.permissionMode = session.permissionMode;
       if (session.permissionModeBeforeFullAccess) metaObj.permissionModeBeforeFullAccess = session.permissionModeBeforeFullAccess;
-      if (session.sessionVisibility) metaObj.sessionVisibility = session.sessionVisibility;
+      metaObj.sessionVisibility = sessionVisibility.normalize(session.sessionVisibility);
+      if (session.sessionVisibilityExplicit) metaObj.sessionVisibilityExplicit = true;
       if (session.bookmarked) metaObj.bookmarked = true;
       if (typeof session.favoriteOrder === "number") metaObj.favoriteOrder = session.favoriteOrder;
       if (session.lastRewindUuid) metaObj.lastRewindUuid = session.lastRewindUuid;
@@ -180,6 +183,9 @@ function createSessionManager(opts) {
       if (session.homeDebateInitialTopic) metaObj.homeDebateInitialTopic = session.homeDebateInitialTopic;
       if (session.homeClayEntryRequestId) metaObj.homeClayEntryRequestId = session.homeClayEntryRequestId;
       if (session.homeClayEntryMode) metaObj.homeClayEntryMode = session.homeClayEntryMode;
+      var provenanceMeta = sessionProvenance.metadata(session);
+      metaObj.sessionOriginId = provenanceMeta.sessionOriginId;
+      if (provenanceMeta.sessionProvenance) metaObj.sessionProvenance = provenanceMeta.sessionProvenance;
       var meta = JSON.stringify(metaObj);
       var lines = [meta];
       for (var i = 0; i < session.history.length; i++) {
@@ -300,6 +306,8 @@ function createSessionManager(opts) {
       if (m.homeClayEntryRequestId) session.homeClayEntryRequestId = m.homeClayEntryRequestId;
       if (m.homeClayEntryMode) session.homeClayEntryMode = m.homeClayEntryMode;
       if (m.ownerId) session.ownerId = m.ownerId;
+      session.sessionOriginId = m.sessionOriginId || null;
+      session._provenanceMigrationNeeded = sessionProvenance.restore(m, session);
       // Born-TUI session: PTY is gone after restart, but the cliSessionId
       // is still resumable via `claude --resume <id>`. We mark the mode
       // here so it shows up in the sidebar with the right icon; the
@@ -315,11 +323,26 @@ function createSessionManager(opts) {
       session.terminalId = null;
       session.runtimeMode = null;
       session.runtimeTerminalId = null;
-      session.sessionVisibility = m.sessionVisibility || "shared";
+      session.sessionVisibility = sessionVisibility.restore(m);
+      session.sessionVisibilityExplicit = m.sessionVisibilityExplicit === true;
       session.bookmarked = !!m.bookmarked;
       session.favoriteOrder = typeof m.favoriteOrder === "number" ? m.favoriteOrder : null;
       sessions.set(localId, session);
     }
+
+    // Versionless legacy records are safe top-level Drivers. Assigning an
+    // opaque origin ID is the only migration: no title, slug or active split
+    // state is used to invent historical parentage.
+    sessions.forEach(function (session) {
+      if (!session.cliSessionId || !session._provenanceMigrationNeeded) return;
+      var activityTime = session.lastActivity;
+      saveSessionFile(session);
+      try {
+        var preservedTime = new Date(activityTime);
+        fs.utimesSync(sessionFilePath(session.cliSessionId), preservedTime, preservedTime);
+      } catch (e) {}
+      delete session._provenanceMigrationNeeded;
+    });
   }
 
   // Adopt orphaned CLI sessions from ~/.claude/projects/<encoded-cwd>/ as
@@ -427,7 +450,7 @@ function createSessionManager(opts) {
         terminalId: null,
         runtimeMode: null,
         runtimeTerminalId: null,
-        sessionVisibility: "shared",
+        sessionVisibility: "private",
         bookmarked: false,
         favoriteOrder: null,
       };
@@ -516,7 +539,7 @@ function createSessionManager(opts) {
       loop: loop,
       spawn: s.spawn || null,
       ownerId: s.ownerId || null,
-      sessionVisibility: s.sessionVisibility || "shared",
+      sessionVisibility: sessionVisibility.normalize(s.sessionVisibility),
       bookmarked: !!s.bookmarked,
       favoriteOrder: typeof s.favoriteOrder === "number" ? s.favoriteOrder : null,
       unread: unreadMap[s.localId] || 0,
@@ -532,6 +555,19 @@ function createSessionManager(opts) {
     };
   }
 
+  function mapSessionsForClient(source, clientActiveId, wsUnread) {
+    var hierarchy = sessionProvenance.hierarchyFor(source);
+    return source.map(function (session) {
+      var mapped = mapSessionForClient(session, clientActiveId, wsUnread);
+      var node = hierarchy[session.localId];
+      mapped.sessionRole = node.role;
+      mapped.parentSessionId = node.parentSessionId;
+      mapped.parentAvailable = node.parentAvailable;
+      mapped.workerGeneration = node.generation;
+      return mapped;
+    });
+  }
+
   function getVisibleSessions() {
     var multiUser = users.isMultiUser();
     return [...sessions.values()].filter(function (s) {
@@ -554,14 +590,14 @@ function createSessionManager(opts) {
         if (ws.readyState === 1) {
           ws.send(JSON.stringify({
             type: "session_list",
-            sessions: filtered.map(function (s) { return mapSessionForClient(s, clientActiveId, wsUnread); }),
+            sessions: mapSessionsForClient(filtered, clientActiveId, wsUnread),
           }));
         }
       });
     } else {
       send({
         type: "session_list",
-        sessions: allVisible.map(function (s) { return mapSessionForClient(s); }),
+        sessions: mapSessionsForClient(allVisible),
       });
     }
   }
@@ -587,7 +623,8 @@ function createSessionManager(opts) {
       history: [],
       messageUUIDs: [],
       ownerId: (sessionOpts && sessionOpts.ownerId) || null,
-      sessionVisibility: (sessionOpts && sessionOpts.sessionVisibility) || "shared",
+      sessionVisibility: sessionVisibility.normalize(sessionOpts && sessionOpts.sessionVisibility),
+      sessionVisibilityExplicit: !!(sessionOpts && sessionOpts.sessionVisibility === "shared"),
       bookmarked: false,
       favoriteOrder: null,
       vendor: (sessionOpts && sessionOpts.vendor) || null,
@@ -598,7 +635,9 @@ function createSessionManager(opts) {
       permissionMode: (sessionOpts && sessionOpts.permissionMode) || null,
       permissionModeBeforeFullAccess: null,
       terminalId: null,
+      sessionOriginId: null,
     };
+    sessionProvenance.ensureOrigin(session);
     sessions.set(localId, session);
     switchSession(localId, targetWs);
     return session;
@@ -626,7 +665,8 @@ function createSessionManager(opts) {
       history: [],
       messageUUIDs: [],
       ownerId: (sessionOpts && sessionOpts.ownerId) || null,
-      sessionVisibility: (sessionOpts && sessionOpts.sessionVisibility) || "shared",
+      sessionVisibility: sessionVisibility.normalize(sessionOpts && sessionOpts.sessionVisibility),
+      sessionVisibilityExplicit: !!(sessionOpts && sessionOpts.sessionVisibility === "shared"),
       bookmarked: false,
       favoriteOrder: null,
       vendor: (sessionOpts && sessionOpts.vendor) || null,
@@ -637,7 +677,9 @@ function createSessionManager(opts) {
       permissionMode: (sessionOpts && sessionOpts.permissionMode) || null,
       permissionModeBeforeFullAccess: null,
       terminalId: null,
+      sessionOriginId: null,
     };
+    sessionProvenance.ensureOrigin(session);
     sessions.set(localId, session);
     return session;
   }
@@ -879,7 +921,8 @@ function createSessionManager(opts) {
     // Send to active clients without recording to history/disk (ephemeral data)
     if (sendEach) {
       var data = JSON.stringify(obj);
-      sendEach(function (ws) {
+      sendEach(function (ws, filterFn) {
+        if (filterFn && !filterFn(session)) return;
         if (session.homeDebatePlanning === true) return;
         if (ws._clayActiveSession === session.localId && ws.readyState === 1) {
           ws.send(data);
@@ -910,7 +953,8 @@ function createSessionManager(opts) {
       // Multi-user: send to clients whose active session matches this one
       var data = JSON.stringify(outgoingObj);
       var ioData = null;
-      sendEach(function (ws) {
+      sendEach(function (ws, filterFn) {
+        if (filterFn && !filterFn(session)) return;
         if (session.homeDebatePlanning === true) return;
         if (ws._clayActiveSession === session.localId) {
           if (ws.readyState === 1) ws.send(data);
@@ -1248,11 +1292,14 @@ function createSessionManager(opts) {
     searchSessionContent: searchSessionContent,
     setResolveLoopInfo: setResolveLoopInfo,
     mapSessionForClient: mapSessionForClient,
+    mapSessionsForClient: mapSessionsForClient,
     migrateSessionTitles: migrateSessionTitles,
     setSessionVisibility: function (localId, visibility) {
       var session = sessions.get(localId);
       if (!session) return { error: "Session not found" };
+      if (visibility !== "shared" && visibility !== "private") return { error: "Invalid session visibility" };
       session.sessionVisibility = visibility;
+      session.sessionVisibilityExplicit = true;
       saveSessionFile(session);
       broadcastSessionList();
       return { ok: true };

package/lib/tools-registry.js

@@ -3,9 +3,10 @@ var path = require("path");
 var config = require("./config");
 var toolUiSpec = require("./tool-ui-spec");
 var toolCapsuleSource = require("./tool-capsule-source");
+var capsuleFloor = require("./capsule-display-floor");
 
 var CAPSULES_ROOT = path.join(__dirname, "capsules");
-var SEED_MARKER = ".capsules-v7";
+var SEED_MARKER = ".capsules-v10";
 var REMOVED_BUILTIN_IDS = ["board", "translator", "scratchpad"];
 var UI_NODE_TYPES = toolUiSpec.UI_NODE_TYPES;
 var DISCOVERY_FIELD_MAX_LENGTH = 240;
@@ -98,6 +99,11 @@ function validateManifest(manifest, opts) {
   if (manifest.skills !== undefined && typeof manifest.skills !== "string") {
     throw new Error("Tool skills must be markdown text.");
   }
+  // The floor gate always validates the Display itself, so a manifest may
+  // never carry a claim about it.
+  if (manifest.displayFloor !== undefined) {
+    throw new Error("Tool displayFloor cannot be authored; Clay validates the Display itself.");
+  }
   validateDiscoveryField(manifest, "description", "description");
   validateDiscoveryField(manifest, "useWhen", "useWhen");
   if (manifest.permissions !== undefined) {
@@ -129,33 +135,90 @@ function toolDirectory(ctx, id) {
   return path.join(resolveToolsRoot(ctx), id);
 }
 
+function hasAnySeedMarker(root) {
+  try {
+    return fs.readdirSync(root).some(function (name) { return /^\.capsules-v\d+$/.test(name); });
+  } catch (e) {
+    return false;
+  }
+}
+
 function seedBuiltInCapsules(ctx) {
   var root = resolveToolsRoot(ctx);
   var marker = path.join(root, SEED_MARKER);
   if (fs.existsSync(marker)) return;
+  // The removed-built-in cleanup is a one-time migration. Any earlier marker
+  // means it already ran, so a later marker bump must not delete a Capsule the
+  // user has since authored under one of those IDs.
+  var migrated = hasAnySeedMarker(root);
   fs.mkdirSync(root, { recursive: true });
-  for (var ri = 0; ri < REMOVED_BUILTIN_IDS.length; ri++) {
+  for (var ri = 0; !migrated && ri < REMOVED_BUILTIN_IDS.length; ri++) {
     fs.rmSync(path.join(root, REMOVED_BUILTIN_IDS[ri]), { recursive: true, force: true });
   }
-  // Clay ships no built-in Capsules any more, so lib/capsules/ is absent from a
-  // fresh checkout and from the npm tarball (neither git nor npm carries an
-  // empty directory). Seeding still owns the removed-built-in migration above
-  // and the marker below, so an absent root means "nothing to copy" rather than
-  // a failure. Anything other than a missing root is still a real error.
+  // lib/capsules/ holds the shipped Capsules, currently the Pig validation
+  // Capsule. It may still be absent from an older checkout or tarball, and
+  // seeding also owns the removed-built-in migration above and the marker
+  // below, so a missing root means "nothing to copy" rather than a failure.
+  // Anything other than a missing root is still a real error.
   var entries = [];
   try {
     entries = fs.readdirSync(CAPSULES_ROOT, { withFileTypes: true });
   } catch (e) {
     if (e.code !== "ENOENT") throw e;
   }
+  // A previously seeded server-runtime Capsule that is no longer shipped is
+  // always a stale copy: the server runtime is reserved for lib/capsules/, so
+  // no user-authored Capsule can ever match this test. Remove it, or it would
+  // linger as a dead entry with no Logic behind it.
+  var shippedIds = Object.create(null);
+  for (var si = 0; si < entries.length; si++) {
+    if (entries[si].isDirectory()) shippedIds[entries[si].name] = true;
+  }
+  var rootEntries = [];
+  try {
+    rootEntries = fs.readdirSync(root, { withFileTypes: true });
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  for (var re = 0; re < rootEntries.length; re++) {
+    if (!rootEntries[re].isDirectory() || shippedIds[rootEntries[re].name]) continue;
+    try {
+      var staleManifest = JSON.parse(fs.readFileSync(path.join(root, rootEntries[re].name, "manifest.json"), "utf8"));
+      if (staleManifest && staleManifest.runtime === "server") {
+        fs.rmSync(path.join(root, rootEntries[re].name), { recursive: true, force: true });
+      }
+    } catch (e) { /* not a capsule directory; leave it alone */ }
+  }
+
   var seeded = [];
+  var SOURCE_FILES = ["manifest.json", "ui.json", "logic.js", "display.js", "skills.md"];
   for (var i = 0; i < entries.length; i++) {
     if (!entries[i].isDirectory()) continue;
     var destination = path.join(root, entries[i].name);
     if (!fs.existsSync(destination)) {
       fs.cpSync(path.join(CAPSULES_ROOT, entries[i].name), destination, { recursive: true });
       seeded.push(entries[i].name);
+      continue;
+    }
+    var shippedManifestPath = path.join(CAPSULES_ROOT, entries[i].name, "manifest.json");
+    var shippedRuntime = "worker";
+    try {
+      shippedRuntime = JSON.parse(fs.readFileSync(shippedManifestPath, "utf8")).runtime || "worker";
+    } catch (e) { /* fall through to the conservative worker path */ }
+    if (shippedRuntime === "server") {
+      // Server-runtime Capsules are Clay-owned: their source is not editable
+      // by users or Mates, so a marker bump syncs the shipped source files
+      // exactly, dropping ones the shipped set no longer carries. The
+      // Capsule's datastore and anything else in the directory is preserved.
+      for (var sf = 0; sf < SOURCE_FILES.length; sf++) {
+        var shippedFile = path.join(CAPSULES_ROOT, entries[i].name, SOURCE_FILES[sf]);
+        var localFile = path.join(destination, SOURCE_FILES[sf]);
+        if (fs.existsSync(shippedFile)) fs.copyFileSync(shippedFile, localFile);
+        else fs.rmSync(localFile, { force: true });
+      }
     } else {
+      // Worker Capsules may have been edited by the user, so only files the
+      // local copy is missing entirely are filled in.
       var sourceFiles = fs.readdirSync(path.join(CAPSULES_ROOT, entries[i].name));
       for (var fi = 0; fi < sourceFiles.length; fi++) {
         var sourceFile = path.join(CAPSULES_ROOT, entries[i].name, sourceFiles[fi]);
@@ -185,6 +248,11 @@ function getTool(ctx, id) {
     manifest: Object.assign({}, manifest, { runtime: runtime }),
     logicSource: runtime === "worker" ? fs.readFileSync(logicPath, "utf8") : null,
     uiTree: uiTree,
+    // Rich Display is opted into by shipping a display.js next to the floor,
+    // the same way logic.js opts into the worker runtime. Only the flag
+    // travels; the source is served solely by the isolated frame origin, so
+    // it can never leak into a manifest, a prompt, or a Mate surface.
+    hasRichDisplay: fs.existsSync(path.join(directory, "display.js")),
     metadata: toolCapsuleSource.sanitizedMetadata(resolveToolsRoot(ctx), id),
   };
 }
@@ -199,8 +267,14 @@ function listTools(ctx) {
     if (entries[i].name.charAt(0) === ".") continue;
     try {
       var tool = getTool(ctx, entries[i].name);
-      if (tool) manifests.push(tool.manifest);
-      else manifests.push({ id: entries[i].name, error: "Capsule requires manifest.json and ui.json." });
+      if (tool) {
+        // The flat manifest carries its own Display alongside it, so a
+        // Mate-facing gate can validate the real tree without a second read
+        // and without trusting a claim. Non-enumerable, so the tree never
+        // leaks into a projection, a prompt, or a serialized message.
+        Object.defineProperty(tool.manifest, "uiTree", { value: tool.uiTree, enumerable: false, configurable: true });
+        manifests.push(tool.manifest);
+      } else manifests.push({ id: entries[i].name, error: "Capsule requires manifest.json and ui.json." });
     } catch (e) {
       manifests.push({ id: entries[i].name, error: e.message });
     }
@@ -216,6 +290,7 @@ function installTool(ctx, input) {
     throw new Error("Tool logic source is required.");
   }
   validateUiTreeForManifest(input.uiTree, input.manifest);
+  capsuleFloor.assertFloor(input.uiTree, input.manifest);
   var manifest = Object.assign({}, input.manifest, { name: input.manifest.name.trim(), runtime: "worker" });
   var directory = toolDirectory(ctx, manifest.id);
   if (fs.existsSync(directory)) throw new Error("A Capsule with this ID already exists. Read its source and use the update tool instead.");
@@ -253,7 +328,10 @@ function updateTool(ctx, id, input) {
   if (!tool) throw new Error("Tool not found.");
   toolCapsuleSource.updateSource(toolDirectory(ctx, id), input, {
     validateManifest: validateManifest,
-    validateUiNode: function (uiTree) { return validateUiTreeForManifest(uiTree, input.manifest); },
+    validateUiNode: function (uiTree) {
+      validateUiTreeForManifest(uiTree, input.manifest);
+      return capsuleFloor.assertFloor(uiTree, input.manifest);
+    },
   });
   return getTool(ctx, id);
 }
@@ -268,6 +346,7 @@ function removeTool(ctx, id) {
 
 module.exports = {
   CAPSULES_ROOT: CAPSULES_ROOT,
+  SEED_MARKER: SEED_MARKER,
   UI_NODE_TYPES: UI_NODE_TYPES,
   resolveToolsRoot: resolveToolsRoot,
   validateToolId: validateToolId,