clay-server 5.2.0-beta.1 → 5.2.0-beta.11

package/lib/server-home-chat.js

@@ -31,7 +31,7 @@ function attachHomeChat(deps) {
       }
       if (!mateId && allMates[i].builtinKey === "clay") mate = allMates[i];
     }
-    if (!mate) return null;
+    if (!mate || mate.lifecycleDeletion) return null;
     var slug = "mate-" + mate.id;
     if (!projects.has(slug)) {
       if (!ensureRegistered) return null;
@@ -123,6 +123,7 @@ function attachHomeChat(deps) {
         model: sessionString(session.model, 240),
         createdAt: createdAt,
         lastActivity: lastActivity,
+        sessionOriginId: session.sessionOriginId || null,
         isProcessing: !!session.isProcessing,
         sessionRole: hierarchy[session.localId].role,
         parentSessionId: hierarchy[session.localId].parentSessionId == null ? null : sessionReference(sessionManager.sessions.get(hierarchy[session.localId].parentSessionId)),
@@ -184,6 +185,12 @@ function attachHomeChat(deps) {
       }
     });
     if (!unsubscribe) return;
+    var unregisterConsent = null;
+    if (openedSession && typeof found.ctx.registerMcpConsentViewer === 'function') {
+      try { unregisterConsent = found.ctx.registerMcpConsentViewer(ws, openedSession); } catch (error) {}
+    }
+    var unsubscribeEvents = unsubscribe;
+    unsubscribe = function () { if (unregisterConsent) unregisterConsent(); unsubscribeEvents(); };
     ws[tapKey] = {
       unsubscribe: unsubscribe,
       sessionId: sessionId,
@@ -222,6 +229,7 @@ function attachHomeChat(deps) {
   var homeDebates = attachHomeDebates({ mates: mates, findMateProject: findMateProject, ownsSession: ownsSession, sessionReference: sessionReference, sendMessage: sendMessage });
   var homeClaySessionLinks = attachHomeClaySessionLinks({
     projects: projects,
+    findMateProject: findMateProject, ownsSession: ownsSession, isActorLive: isActorLive,
     workspaceQueryService: deps.workspaceQueryService,
     projectLogsService: deps.projectLogsService,
     sendMessage: sendMessage,
@@ -238,7 +246,7 @@ function attachHomeChat(deps) {
         requestId: requestId || null,
         model: session.model || null,
         vendor: session.vendor || null,
-        messages: historyToHomeChat(session.history || [], session.debateSetupMode === true, session.mateCreationMode === true),
+        messages: historyToHomeChat(session.history || [], session.debateSetupMode === true, session.mateCreationMode === true, session.pendingAskUser),
         isProcessing: session.isProcessing === true,
       };
       if (session.homeClayEntryMode === "search") {
@@ -293,7 +301,10 @@ function attachHomeChat(deps) {
     homeModels: homeModels, isActorLive: isActorLive, persistActiveSession: persistActiveSession,
   });
   var homeMateCreation = attachHomeMateCreation({ findMateProject: findMateProject, resolveHomeSession: resolveHomeSession, sessionReference: sessionReference, setupTap: setupTap, sendHistory: sendHistory, sendSessionList: sendSessionList, sendError: sendError, sendModelError: sendModelError, homeModels: homeModels, isActorLive: isActorLive, persistActiveSession: persistActiveSession });
-  var homeClayEntry = attachHomeClayEntry({ findMateProject: findMateProject, ownsSession: ownsSession, sessionReference: sessionReference, setupSearchTap: setupSearchTap, sendHistory: sendHistory, sendSessionList: sendSessionList, sendError: sendError, sendModelError: sendModelError, homeModels: homeModels, isActorLive: isActorLive });
+  var homeMcpConsent = require('./server-home-mcp-consent').attachHomeMcpConsent({ findMateProject: findMateProject, resolveHomeSession: resolveHomeSession, messageTap: messageTap, isActorLive: isActorLive, sendError: sendError });
+  var homeClayEntry = attachHomeClayEntry({ findMateProject: findMateProject, ownsSession: ownsSession, sessionReference: sessionReference, setupSearchTap: setupSearchTap, sendHistory: sendHistory, sendSessionList: sendSessionList, sendError: sendError, sendModelError: sendModelError, sendMessage: sendMessage, homeModels: homeModels, isActorLive: isActorLive });
+
+  var contextualSessions = require('./server-contextual-mate-sessions').attachContextualMateSessions({ findMateProject: findMateProject, ownsSession: ownsSession, resolveHomeSession: resolveHomeSession, listHomeSessions: listHomeSessions, isActorLive: isActorLive, homeModels: homeModels, sendMessage: sendMessage });
 
   async function openExactSession(ws, found, userId, selected, msg) {
     await ensureSessionModel(ws, found, userId, selected, null);
@@ -397,20 +408,8 @@ function attachHomeChat(deps) {
       historyError.sessionId = sessionReference(activeSession);
       throw historyError;
     }
-    sessionManager.sendAndRecord(activeSession, { type: "user_message", text: text });
     try {
-      if (!activeSession.isProcessing) {
-        activeSession.isProcessing = true;
-        activeSession.sentToolResults = {};
-        if (typeof options.onRecorded === "function") options.onRecorded(activeSession);
-        if (!activeSession.queryInstance && (!activeSession.worker || activeSession.messageQueue !== "worker")) {
-          sdk.startQuery(activeSession, options.queryText || text, null, null);
-        } else {
-          sdk.pushMessage(activeSession, options.queryText || text, null);
-        }
-      } else {
-        sdk.pushMessage(activeSession, options.queryText || text, null);
-      }
+      await require('./mate-message-delivery').deliver({ sm: sessionManager, sdk: sdk }, activeSession, text, options);
     } catch (error) {
       error.sessionId = sessionReference(activeSession);
       throw error;
@@ -418,7 +417,7 @@ function attachHomeChat(deps) {
     return sessionReferenceValue;
   }
 
-  function handleMessage(ws, msg) {
+  function handleMessage(ws, msg, routedProjectSlug) {
     if (!msg || typeof msg.type !== "string") return false;
     if (msg.type === "home_mate_stop" || msg.type === "home_mate_permission_response") {
       var controlUserId = ws._clayUser ? ws._clayUser.id : null;
@@ -449,10 +448,12 @@ function attachHomeChat(deps) {
       }
       return true;
     }
-    if (msg.type !== "issue_reference_resolve" && msg.type !== "home_debates_list" && msg.type !== "home_clay_ask" && msg.type !== "home_clay_session_resolve" && msg.type !== "home_clay_log_resolve" && msg.type !== "home_mate_present" && msg.type !== "home_mate_open" && msg.type !== "home_mate_sessions_list" && msg.type !== "home_mate_session_open" && msg.type !== "home_mate_send" && msg.type !== "home_mate_new_session" && msg.type !== "home_mate_debate_plan" && msg.type !== "home_debate_proposal_response" && msg.type !== "home_debate_question_response" && msg.type !== "home_debate_control" && msg.type !== "home_mate_creation_plan" && msg.type !== "home_mate_creation_question_response" && msg.type !== "home_mate_creation_proposal_response" && msg.type !== "home_mate_close" && msg.type !== "home_mate_memory_list" && msg.type !== "home_mate_knowledge_list" && msg.type !== "home_mate_models_get" && msg.type !== "home_mate_model_set") {
+    if (msg.type !== "issue_reference_resolve" && msg.type !== "home_debates_list" && msg.type !== "home_clay_ask" && msg.type !== "home_clay_session_resolve" && msg.type !== "home_clay_log_resolve" && msg.type !== "home_mate_present" && msg.type !== "home_mate_open" && msg.type !== "home_mate_sessions_list" && msg.type !== "home_mate_session_open" && msg.type !== "home_mate_send" && msg.type !== "home_mate_new_session" && msg.type !== "home_mate_debate_plan" && msg.type !== "home_debate_proposal_response" && msg.type !== "home_mcp_import_response" && msg.type !== "home_mate_question_response" && msg.type !== "home_debate_question_response" && msg.type !== "home_debate_control" && msg.type !== "home_mate_creation_plan" && msg.type !== "home_mate_creation_question_response" && msg.type !== "home_mate_creation_proposal_response" && msg.type !== "home_mate_close" && msg.type !== "home_mate_memory_list" && msg.type !== "home_mate_knowledge_list" && msg.type !== "home_mate_models_get" && msg.type !== "home_mate_model_set") {
       return false;
     }
 
+    if (contextualSessions.handle(ws, ws._clayUser ? ws._clayUser.id : null, msg)) return true;
+
     if (msg.type === "home_mate_present") {
       ws._homeChatPresented = msg.visible === true;
       return true;
@@ -474,11 +475,12 @@ function attachHomeChat(deps) {
       return true;
     }
 
+    if (msg.type === "home_mcp_import_response" || msg.type === "home_mate_question_response") { homeMcpConsent.respond(ws, userId, msg); return true; }
     if (msg.type === "issue_reference_resolve") { resolveIssueLink(ws, msg); return true; }
     if (homeDebates.handle(ws, userId, msg)) return true;
     if (msg.type === "home_clay_ask") { homeClayEntry.start(ws, userId, msg); return true; }
-    if (msg.type === "home_clay_session_resolve") { homeClaySessionLinks.resolve(ws, msg); return true; }
-    if (msg.type === "home_clay_log_resolve") { homeClaySessionLinks.resolveLog(ws, msg); return true; }
+    if (msg.type === "home_clay_session_resolve") { homeClaySessionLinks.resolve(ws, msg, routedProjectSlug); return true; }
+    if (msg.type === "home_clay_log_resolve") { homeClaySessionLinks.resolveLog(ws, msg, routedProjectSlug); return true; }
 
     if (msg.type === "home_mate_debate_plan") {
       homeDebate.start(ws, userId, msg);

package/lib/server-home-clay-entry.js

@@ -15,10 +15,12 @@ function attachHomeClayEntry(ctx) {
   }
 
   async function start(ws, userId, msg) {
+    var contextual = msg.presentation === 'contextual';
     var text = typeof msg.text === "string" ? msg.text.replace(/[\u0000-\u001f\u007f]/g, " ").trim().slice(0, 12000) : "";
     var requestId = typeof msg.requestId === "string" ? msg.requestId.slice(0, 240) : null;
+    if (ctx.isActorLive && !ctx.isActorLive(ws, userId)) { ctx.sendError(ws, null, 'Your account is no longer available.', requestId, null, 'actor_unavailable'); return; }
     var found = ctx.findMateProject(userId, null, true);
-    if (!found || found.mate.builtinKey !== "clay") {
+    if (!found || found.mate.builtinKey !== "clay" || found.mate.archived || ctx.isActorLive && !ctx.isActorLive(ws, userId)) {
       ctx.sendError(ws, null, "Clay is not available.", requestId, null, "mate_unavailable");
       return;
     }
@@ -27,26 +29,43 @@ function attachHomeClayEntry(ctx) {
       return;
     }
     var manager = found.ctx.getSessionManager();
+    var mateStamp = JSON.stringify([found.mate.id, found.mate.createdAt || null, found.mate.createdBy || null]);
     if (!manager || typeof manager.sendAndRecord !== "function") {
       ctx.sendError(ws, found.mate.id, "Conversation history is unavailable.", requestId, null, "session_unavailable");
       return;
     }
     var existing = findExisting(manager, userId, requestId);
     if (existing) {
+      if (contextual) {
+        if (existing.homeClayEntryMode !== 'contextual' || existing.homeClayEntryText !== text || msg.sessionOriginId && msg.sessionOriginId !== existing.sessionOriginId) { ctx.sendError(ws, found.mate.id, 'This request belongs to a different conversation.', requestId, null, 'request_mismatch'); return; }
+        ctx.sendMessage(ws, { type: 'home_clay_contextual_session', requestId: requestId, mateId: found.mate.id, sessionId: existing.localId, sessionOriginId: existing.sessionOriginId }); return;
+      }
       ctx.setupSearchTap(ws, found, existing.localId, requestId);
       ctx.sendHistory(ws, found, existing, requestId);
       ctx.sendSessionList(ws, found, userId);
       return;
     }
+    if (contextual && msg.sessionOriginId) { ctx.sendError(ws, found.mate.id, 'This new conversation is no longer available. Start a new Ask.', requestId, null, 'session_unavailable'); return; }
     var session = null;
     try {
       var resolved = await ctx.homeModels.resolveMateModel(ws, found, userId);
       if (ctx.isActorLive && !ctx.isActorLive(ws, userId)) throw new Error("Your account is no longer available.");
       var liveFound = ctx.findMateProject(userId, null, true);
-      if (!liveFound || liveFound.ctx !== found.ctx || !liveFound.mate || liveFound.mate.builtinKey !== "clay") throw new Error("Clay is no longer available.");
-      session = manager.createSession({ ownerId: userId, vendor: resolved.vendor, model: resolved.model, effort: resolved.effort || null }, null);
+      if (!liveFound || liveFound.ctx !== found.ctx || !liveFound.mate || liveFound.ctx.getSessionManager() !== manager || liveFound.mate.builtinKey !== "clay" || JSON.stringify([liveFound.mate.id, liveFound.mate.createdAt || null, liveFound.mate.createdBy || null]) !== mateStamp || liveFound.mate.archived) throw new Error("Clay is no longer available.");
+      // Another request may have completed while model resolution was awaiting.
+      if (findExisting(manager, userId, requestId)) return start(ws, userId, msg);
+      var options = { ownerId: userId, vendor: resolved.vendor, model: resolved.model, effort: resolved.effort || null };
+      // Background creation must not switch any existing pane/native writer.
+      session = contextual ? manager.createSessionRaw(options) : manager.createSession(options, null);
       session.homeClayEntryRequestId = requestId;
-      session.homeClayEntryMode = "search";
+      session.homeClayEntryMode = contextual ? 'contextual' : 'search';
+      if (contextual) {
+        session.homeClayEntryText = text;
+        session.title = text.slice(0, 80);
+        manager.saveSessionFile(session);
+        ctx.sendMessage(ws, { type: 'home_clay_contextual_session', requestId: requestId, mateId: found.mate.id, sessionId: session.localId, sessionOriginId: session.sessionOriginId });
+        return;
+      }
       manager.sendAndRecord(session, { type: "user_message", text: text });
       session.isProcessing = true;
       session.sentToolResults = {};

package/lib/server-home-clay-session-links.js

@@ -2,23 +2,43 @@
 // owner-bound source session.
 
 function attachHomeClaySessionLinks(ctx) {
-  function source(ws, msg) {
+  function source(ws, msg, routedProjectSlug) {
+    if (Object.prototype.hasOwnProperty.call(msg, "contextualSource")) {
+      var hint = msg.contextualSource, userId = ws && ws._clayUser && ws._clayUser.id;
+      if (!hint || typeof hint.mateId !== "string" || !Number.isSafeInteger(hint.sessionId) || typeof hint.sessionOriginId !== "string" || typeof hint.mateStamp !== "string" || !ctx.isActorLive || !ctx.isActorLive(ws, userId)) return {};
+      var found = ctx.findMateProject && ctx.findMateProject(userId, hint.mateId, false);
+      if (!found || found.mate.archived || found.mate.lifecycleDeletion || found.mate.createdBy && found.mate.createdBy !== userId) return {};
+      var stamp = JSON.stringify([found.mate.id, found.mate.createdBy || null, found.mate.createdAt || null, found.mate.builtinKey || null]);
+      if (stamp !== hint.mateStamp || ctx.projects.get(found.slug) !== found.ctx) return {};
+      var manager = found.ctx.getSessionManager && found.ctx.getSessionManager();
+      var session = manager && manager.sessions.get(hint.sessionId);
+      if (!ctx.ownsSession(session, userId) || session.sessionOriginId !== hint.sessionOriginId) return {};
+      return { tap: { mateSlug: found.slug, mateId: found.mate.id, sessionId: hint.sessionId }, project: found.ctx, session: session };
+    }
     var tap = msg.surface === "search" ? ws._searchClayTap : ws._homeChatTap;
+    if (!tap && routedProjectSlug) {
+      var routedProject = ctx.projects.get(routedProjectSlug);
+      var routedManager = routedProject && routedProject.getSessionManager ? routedProject.getSessionManager() : null;
+      var routedSession = routedManager && ws._clayActiveSession ? routedManager.sessions.get(ws._clayActiveSession) : null;
+      return { tap: { mateSlug: routedProjectSlug, sessionId: ws._clayActiveSession }, project: routedProject, session: routedSession };
+    }
     var sourceProject = tap && tap.mateSlug ? ctx.projects.get(tap.mateSlug) : null;
     var sourceManager = sourceProject && sourceProject.getSessionManager ? sourceProject.getSessionManager() : null;
     var sourceSession = sourceManager && tap ? sourceManager.sessions.get(tap.sessionId) : null;
     return { tap: tap, project: sourceProject, session: sourceSession };
   }
 
-  function resolve(ws, msg) {
-    var selected = source(ws, msg);
-    var bound = ctx.workspaceQueryService && selected.session
-      ? ctx.workspaceQueryService.bindProjectSession({ projectSlug: selected.tap.mateSlug, session: selected.session })
-      : null;
+  function resolve(ws, msg, routedProjectSlug) {
+    var selected = source(ws, msg, routedProjectSlug);
     var payload = { type: "home_clay_session_target", requestId: msg.requestId || null, sessionRef: msg.sessionRef || null, status: "error" };
     try {
+      var binding = selected.session ? { projectSlug: selected.tap.mateSlug, session: selected.session } : null;
+      if (binding && ws && ws._clayUser) binding.viewerId = ws._clayUser.id;
+      var bound = ctx.workspaceQueryService && binding
+        ? ctx.workspaceQueryService.bindProjectSession(binding)
+        : null;
       if (!bound) throw new Error("The source conversation is no longer available.");
-      payload.target = bound.resolveSessionNavigation({ sessionRef: msg.sessionRef });
+      payload.target = bound.resolveSessionNavigation({ sessionRef: msg.sessionRef, entryIndex: msg.entryIndex });
       payload.status = "ready";
     } catch (error) {
       payload.error = error.message || "Session not available.";
@@ -26,8 +46,8 @@ function attachHomeClaySessionLinks(ctx) {
     ctx.sendMessage(ws, payload);
   }
 
-  function resolveLog(ws, msg) {
-    var selected = source(ws, msg);
+  function resolveLog(ws, msg, routedProjectSlug) {
+    var selected = source(ws, msg, routedProjectSlug);
     var status = selected.project && selected.project.getStatus ? selected.project.getStatus() : null;
     var bound = ctx.projectLogsService && selected.session && status
       ? ctx.projectLogsService.bindMate({

package/lib/server-home-mate-creation.js

@@ -18,6 +18,7 @@ var INITIATION_PROMPT = [
   "Before the user answers again, your first and only action must be the next most useful AskUserQuestion. Before presenting it, do not use Bash, Read, Glob, Grep, workspace history, general knowledge, or any other inspection tool, and do not add a preface.",
   "When that tool returns the user's answer, continue the interview normally. Inspect only bounded context that is directly relevant to what the user supplied, and do not bulk-read knowledge files.",
   "Then explore the working relationship, recurring activities and context, communication preferences, autonomy, boundaries, and escalation behavior. Use grounded choices only when helpful. Every three to five exchanges, briefly summarize what you understand inside the next question and let the user correct it.",
+  "If the user explicitly asks the future Mate to send a scheduled message, collect the message and exact local date/time, timezone, and repetition only through one focused structured question at a time. Treat it as optional schedule intent: never create or register a job during this interview; include it only in propose_mate after reviewing it with the user.",
   "Choose the Mate's name last. Do not write files and do not create or update a Mate directly.",
   "When the identity is complete, end only by calling propose_mate with a concise public bio, structured preferences, and a complete first-person identityMarkdown. Do not emit a normal assistant preface or conclusion.",
 ].join("\n");

package/lib/server-home-mcp-consent.js

@@ -0,0 +1,14 @@
+// Home transcript responses retain the project's server-owned consent request.
+function attachHomeMcpConsent(ctx) {
+  function respond(ws, userId, msg) {
+    var found = ctx.findMateProject(userId, msg.mateId || null, false);
+    var session = found && ctx.resolveHomeSession(found, userId, msg.sessionId);
+    var tap = ctx.messageTap(ws, msg), pending = session && session.pendingAskUser && session.pendingAskUser[msg.toolId];
+    if (!ctx.isActorLive(ws, userId) || !found || !session || !tap || tap.mateSlug !== found.slug || tap.sessionId !== session.localId || (tap.requestId || null) !== (msg.requestId || null) || !pending || !pending.request || ['mcp-import', 'mate-schedule', 'mcp_fallback', 'product-control'].indexOf(pending.request.source) < 0) {
+      ctx.sendError(ws, found && found.mate.id, 'This owner question is unavailable or expired.', msg.requestId || null, msg.sessionId || null, 'question_expired', { toolId: msg.toolId }); return;
+    }
+    if (!found.ctx.handleHomeAskUserResponse({ type: 'ask_user_response', toolId: msg.toolId, answers: msg.answers || {} }, session, ws)) ctx.sendError(ws, found.mate.id, 'This question could not be submitted.', msg.requestId || null, msg.sessionId, 'question_refused', { toolId: msg.toolId });
+  }
+  return { respond: respond };
+}
+module.exports = { attachHomeMcpConsent: attachHomeMcpConsent };

package/lib/server-mates.js

@@ -74,12 +74,26 @@ function attachMates(ctx) {
     var mateSlug = "mate-" + mate.id;
     var mateName = (mate.profile && mate.profile.displayName) || mate.name || "Mate";
     var registered = false;
+    var boundScheduleJob = null;
     var favorites;
     try {
       registered = addProject(mateDir, mateSlug, mateName, null, mate.createdBy || effectiveUserId, null, { isMate: true, mateDisplayName: mateName }) !== false;
       if (!registered) throw new Error("The Mate project could not be registered.");
+      var intent = mate.seedData && mate.seedData.scheduleIntent;
+      if (intent && intent.message && intent.scheduleRule) {
+        var targetProject = projects.get(mateSlug);
+        var targetManager = targetProject && targetProject.getSessionManager();
+        if (!targetProject || !targetManager || typeof targetProject.bindMateSchedule !== "function") throw new Error("The Mate schedule could not be bound to the new Mate.");
+        var targetSession = targetManager.createSessionRaw({ ownerId: users.isMultiUser() ? effectiveUserId : null, vendor: mate.vendor, model: mate.model });
+        boundScheduleJob = targetProject.bindMateSchedule(targetSession, intent, "creation-" + mate.id);
+        if (!boundScheduleJob) throw new Error("The Mate schedule could not be persisted.");
+        mates.updateMate(mateCtx, mate.id, { seedData: Object.assign({}, mate.seedData, { scheduleIntent: null }) });
+      }
       favorites = users.addDmFavorite(effectiveUserId, mate.id);
     } catch (error) {
+      if (targetSession && targetSession.mateSchedules && targetProject && typeof targetProject.cancelMateSchedule === "function") {
+        try { targetSession.mateSchedules.forEach(function (record) { targetProject.cancelMateSchedule(targetSession, record); }); } catch (cancelError) {}
+      }
       if (registered) try { removeProject(mateSlug); } catch (removeError) {}
       try { mates.deleteMate(mateCtx, mate.id); } catch (deleteError) {}
       throw error;
@@ -97,6 +111,10 @@ function attachMates(ctx) {
     return mate;
   }
 
+  var lifecycle = require("./mate-lifecycle-service").attachMateLifecycleService({
+    users: users, mates: mates, projects: projects, removeProject: removeProject, refresh: refreshTeamSections,
+  });
+
   // --- Mate message handlers ---
 
   function handleMessage(ws, msg) {
@@ -168,7 +186,7 @@ function attachMates(ctx) {
       for (var mi = 0; mi < mateList.length; mi++) {
         var m = mateList[mi];
         var mSlug = "mate-" + m.id;
-        if (!projects.has(mSlug)) {
+        if (!m.lifecycleDeletion && !projects.has(mSlug)) {
           var mDir = mates.getMateDir(mateCtx5, m.id);
           fs.mkdirSync(mDir, { recursive: true });
           var mName = (m.profile && m.profile.displayName) || m.name || "New Mate";
@@ -200,45 +218,9 @@ function attachMates(ctx) {
 
     if (msg.type === "mate_delete") {
       if (!msg.mateId) return true;
-      var mateCtx6 = mates.buildMateCtx(userId);
-      // Track deleted built-in mate key so it doesn't auto-recreate
-      var mateToDelete = mates.getMate(mateCtx6, msg.mateId);
-      if (mateToDelete && mateToDelete.builtinKey) {
-        users.addDeletedBuiltinKey(userId, mateToDelete.builtinKey);
-      }
-      var result = mates.deleteMate(mateCtx6, msg.mateId);
-      if (result.error) {
-        ws.send(JSON.stringify({ type: "mate_error", error: result.error }));
-      } else {
-        removeProject("mate-" + msg.mateId);
-        // Build updated available builtins list
-        var builtinDefs3 = require("./builtin-mates");
-        var missingKeys3 = mates.getMissingBuiltinKeys(mateCtx6);
-        var availableBuiltins3 = [];
-        for (var abk3 = 0; abk3 < missingKeys3.length; abk3++) {
-          var bDef3 = builtinDefs3.getBuiltinByKey(missingKeys3[abk3]);
-          if (bDef3) {
-            availableBuiltins3.push({
-              key: bDef3.key,
-              displayName: bDef3.displayName,
-              bio: bDef3.bio,
-              avatarCustom: bDef3.avatarCustom || "",
-              avatarStyle: bDef3.avatarStyle || "imprint",
-              avatarColor: bDef3.avatarColor || "",
-            });
-          }
-        }
-        ws.send(JSON.stringify({ type: "mate_deleted", mateId: msg.mateId, availableBuiltins: availableBuiltins3 }));
-        // Broadcast to all clients so strips update
-        projects.forEach(function (pCtx) {
-          pCtx.forEachClient(function (otherWs) {
-            if (otherWs === ws) return;
-            if (users.isMultiUser() && (!otherWs._clayUser || otherWs._clayUser.id !== userId)) return;
-            if (otherWs.readyState !== 1) return;
-            otherWs.send(JSON.stringify({ type: "mate_deleted", mateId: msg.mateId, availableBuiltins: availableBuiltins3 }));
-          });
-        });
-      }
+      lifecycle.remove(userId, msg.mateId, null, ws).then(function () {}, function (error) {
+        ws.send(JSON.stringify({ type: "mate_error", mateId: msg.mateId, error: error.message }));
+      });
       return true;
     }
 
@@ -303,28 +285,8 @@ function attachMates(ctx) {
         ws.send(JSON.stringify({ type: "mate_error", mateId: msg.mateId, error: "Use the Mate model selector to change this setting." }));
         return true;
       }
-      var mateCtx7 = mates.buildMateCtx(userId);
-      var updated = mates.updateMate(mateCtx7, msg.mateId, msg.updates);
-      if (updated && updated.error) {
-        ws.send(JSON.stringify({ type: "mate_error", mateId: msg.mateId, requestId: msg.requestId, error: updated.error }));
-        return true;
-      }
-      if (updated) {
-        ws.send(JSON.stringify({ type: "mate_updated", mate: updated, requestId: msg.requestId }));
-        // Broadcast update
-        projects.forEach(function (pCtx) {
-          pCtx.forEachClient(function (otherWs) {
-            if (otherWs === ws) return;
-            if (users.isMultiUser() && (!otherWs._clayUser || otherWs._clayUser.id !== userId)) return;
-            if (otherWs.readyState !== 1) return;
-            otherWs.send(JSON.stringify({ type: "mate_updated", mate: updated }));
-          });
-        });
-        // Re-enforce team sections across all mate projects so roster stays current
-        refreshTeamSections(mateCtx7);
-      } else {
-        ws.send(JSON.stringify({ type: "mate_error", mateId: msg.mateId, requestId: msg.requestId, error: "Mate not found" }));
-      }
+      try { lifecycle.update(userId, msg.mateId, msg.updates, ws, msg.requestId); }
+      catch (error) { ws.send(JSON.stringify({ type: "mate_error", mateId: msg.mateId, requestId: msg.requestId, error: error.message })); }
       return true;
     }
 
@@ -333,6 +295,7 @@ function attachMates(ctx) {
 
   return {
     handleMessage: handleMessage,
+    lifecycle: lifecycle,
     scheduleRegistryRefresh: scheduleRegistryRefresh,
     createReadyMateFromInterview: createReadyMateFromInterview,
   };

package/lib/server-owner-ui.js

@@ -0,0 +1,118 @@
+var crypto = require('crypto');
+// Only authenticated application sockets enumerated by the server are targets.
+function attachOwnerUi(ctx) {
+  var identities = new WeakMap(), capabilities = new WeakMap(), deliveries = new Map();
+  var activityOrder = 0;
+  function activity(owner, slug, sessionId, mateId, selected, source, validateSource, navigationTarget) {
+    var order = ++activityOrder;
+    var viewers = selected ? [check(owner, selected)] : sockets(owner).filter(function (viewer) {
+      var tap = viewer.ws._homeChatTap;
+      return viewer.slug === slug && viewer.sessionId === sessionId || tap && tap.mateSlug === slug && tap.sessionId === sessionId;
+    });
+    function send(message, receiptViewer) {
+      viewers.forEach(function (viewer) {
+        try {
+          if (receiptViewer && viewer.ws !== receiptViewer || !alive(viewer.ws, owner)) return;
+          if (message.phase !== 'clear' && validateSource) validateSource();
+          var live = inspect(owner, viewer.ref), tap = live.ws._homeChatTap;
+          if (message.phase !== 'clear' && (selected ? (live.slug !== viewer.slug || live.sessionId !== viewer.sessionId) && !(message.phase === 'rendered' && navigationTarget && live.slug === navigationTarget.projectSlug && live.sessionId === navigationTarget.sessionId) : !(live.slug === slug && live.sessionId === sessionId || tap && tap.mateSlug === slug && tap.sessionId === sessionId))) return;
+          live.ws.send(JSON.stringify(Object.assign({ type: 'clay_control_activity', ownerId: owner, mateId: mateId,
+            sourceSlug: slug, sourceSessionId: sessionId, order: order, recipientViewerRef: live.ref }, source, message)));
+        } catch (error) { /* Presentation cannot alter the authoritative effect. */ }
+      });
+    }
+    return { send: send, clear: function (id, sequence) { send({ version: 1, id: id, sequence: sequence, phase: 'clear' }); } };
+  }
+  function alive(ws, owner) {
+    return ws && ws.readyState === 1 && (!ws._clayAuthCheck || ws._clayAuthCheck()) &&
+      (ctx.isMultiUser() ? !!owner && ws._clayUser && ws._clayUser.id === owner && !!ctx.findUser(owner) : !ws._clayUser);
+  }
+  function sockets(owner) {
+    var all = new Map();
+    ctx.forEachClient(function (ws, slug) {
+      if (!alive(ws, owner) || all.has(ws)) return;
+      if (!identities.has(ws)) identities.set(ws, 'viewer:' + crypto.randomUUID());
+      all.set(ws, { ws: ws, ref: identities.get(ws), slug: slug || null, sessionId: ws._clayActiveSession || null,
+        supported: capabilities.get(ws) === 1 && !ws._clayPane });
+    });
+    return Array.from(all.values());
+  }
+  function get(owner, ref) { return sockets(owner).find(function (item) { return item.ref === ref; }); }
+  function inspect(owner, ref) {
+    var viewer = get(owner, ref);
+    if (!viewer) throw new Error('The exact owner UI connection is absent or revoked.');
+    return viewer;
+  }
+  function check(owner, original) {
+    var live = inspect(owner, original.ref);
+    if (live.ws !== original.ws || live.slug !== original.slug || live.sessionId !== original.sessionId || live.supported !== original.supported) throw new Error('The selected viewer context changed. Inspect again.');
+    return live;
+  }
+  function deliver(owner, original, target, revalidate, activity) {
+    revalidate(); var viewer = check(owner, original);
+    if (!viewer.supported) return { status: 'unsupported', delivered: false, acknowledged: false, visible: 'unknown' };
+    if (deliveries.size >= 100) {
+      deliveries.forEach(function (item, key) { if (Date.now() - item.created > 300000) deliveries.delete(key); });
+      if (deliveries.size >= 100) throw new Error('UI delivery capacity is full; wait for earlier attempts to expire.');
+    }
+    var id = 'navigation:' + crypto.randomUUID();
+    var renderToken = crypto.randomUUID();
+    var record = { owner: owner, viewer: viewer, target: target, revalidate: revalidate, activity: activity, created: Date.now(), claimed: false, renderToken: renderToken, renderClosed: false,
+      result: { status: 'delivered', deliveryId: id, delivered: false, acknowledged: false, visible: 'unknown' } };
+    deliveries.set(id, record);
+    record.renderTimer = setTimeout(function () {
+      if (record.renderClosed) return;
+      record.renderClosed = true; record.result.renderStatus = 'unknown';
+      if (record.activity) record.activity.navigation('unknown');
+    }, ctx.renderTimeoutMs || 5000); record.renderTimer.unref();
+    try {
+      viewer.ws.send(JSON.stringify({ type: 'clay_navigation_offer', deliveryId: id }));
+      if (!alive(viewer.ws, owner)) throw new Error('Viewer authorization or connection ended during delivery.');
+      record.result.delivered = true;
+    } catch (error) { record.result.status = 'failed'; record.result.error = error.message; record.result.retrySafe = false; }
+    return Object.assign({}, record.result);
+  }
+  function read(owner, id) {
+    var record = deliveries.get(id);
+    if (!record || record.owner !== owner) throw new Error('No delivery exists for this owner.');
+    if (Date.now() - record.created > 300000) { deliveries.delete(id); throw new Error('The five-minute navigation receipt expired. Inspect the current view before any new reviewed request.'); }
+    record.revalidate();
+    return Object.assign({}, record.result);
+  }
+  function handleMessage(ws, msg) {
+    if (['clay_ui_ready', 'clay_navigation_claim', 'clay_navigation_ack', 'clay_navigation_rendered'].indexOf(msg.type) < 0) return false;
+    var owner = ctx.isMultiUser() ? ws._clayUser && ws._clayUser.id : null;
+    if (!sockets(owner).some(function (item) { return item.ws === ws; })) return true;
+    if (msg.type === 'clay_ui_ready') {
+      if (msg.version === 1) { capabilities.set(ws, 1); ws.send(JSON.stringify({ type: 'clay_control_viewer', viewerRef: identities.get(ws) })); }
+      return true;
+    }
+    var record = deliveries.get(msg.deliveryId);
+    if (!record || record.viewer.ws !== ws || record.owner !== owner || Date.now() - record.created > 30000) return true;
+    try {
+      record.revalidate();
+      if (msg.type === 'clay_navigation_rendered') {
+        if (!record.renderClosed && Date.now() > record.created + (ctx.renderTimeoutMs || 5000)) { record.renderClosed = true; clearTimeout(record.renderTimer); record.result.renderStatus = 'unknown'; if (record.activity) record.activity.navigation('unknown'); }
+        if (record.renderClosed || !record.claimed || !record.result.acknowledged || record.result.clientStatus !== 'accepted' || msg.renderToken !== record.renderToken) return true;
+        var current = inspect(owner, record.viewer.ref);
+        if (current.ws !== ws || msg.sessionOriginId !== record.target.sessionOriginId || !record.target.sessionOriginId || msg.projectSlug !== record.target.projectSlug || msg.sessionId !== record.target.sessionId || msg.surface !== 'conversation' || msg.entryIndex !== record.target.entryIndex || current.slug !== record.target.projectSlug || current.sessionId !== record.target.sessionId) throw new Error('Rendered target or authenticated viewer changed.');
+        record.renderClosed = true; clearTimeout(record.renderTimer);
+        record.result.renderStatus = msg.visible === true ? 'rendered' : 'unknown'; record.result.visible = msg.visible === true ? true : 'unknown';
+        if (record.activity) record.activity.navigation(msg.visible === true ? 'rendered' : 'unknown');
+      } else if (msg.type === 'clay_navigation_claim') {
+        if (record.claimed) return true;
+        check(owner, record.viewer); record.claimed = true;
+        ws.send(JSON.stringify({ type: 'clay_navigation_apply', deliveryId: msg.deliveryId, target: record.target, renderToken: record.renderToken, renderDeadline: record.created + (ctx.renderTimeoutMs || 5000) }));
+      } else if (record.claimed && !record.result.acknowledged && ['accepted', 'refused', 'failed'].indexOf(msg.status) >= 0) {
+        record.result.acknowledged = true;
+        // Accepted only confirms invocation of the existing navigator, never rendering.
+        record.result.clientStatus = msg.status;
+        if (msg.status !== 'accepted') { record.renderClosed = true; clearTimeout(record.renderTimer); }
+        if (record.activity) record.activity.navigation(msg.status === 'accepted' ? 'acknowledged' : msg.status === 'refused' ? 'cancelled' : 'failed');
+      }
+    } catch (error) { record.renderClosed = true; clearTimeout(record.renderTimer); record.result.visible = 'unknown'; record.result.status = 'failed'; record.result.error = error.message; record.result.retrySafe = false; if (record.activity) record.activity.cancel(); }
+    return true;
+  }
+  return { list: sockets, inspect: inspect, check: check, deliver: deliver, read: read, handleMessage: handleMessage, activity: activity };
+}
+module.exports = { attachOwnerUi: attachOwnerUi };

package/lib/server-path-access.js

@@ -0,0 +1,38 @@
+// Directory pickers and project registration must not become content-access
+// bypasses through another spelling, symlink or nested directory.
+var fs = require("fs");
+var path = require("path");
+function inside(root, target) {
+  var relative = path.relative(root, target);
+  return relative !== ".." && relative.indexOf(".." + path.sep) !== 0 && !path.isAbsolute(relative);
+}
+function attachPathAccess(ctx) {
+  return function (userId, requested) {
+    if (!ctx.users.isMultiUser()) return true;
+    var user = userId && ctx.users.findUserById(userId);
+    if (!user) return false;
+    var target;
+    try { target = fs.realpathSync(requested); } catch (error) { return false; }
+    var allowed = false;
+    var denied = false;
+    ctx.projects.forEach(function (project, slug) {
+      var status = project.getStatus();
+      var root;
+      try { root = fs.realpathSync(status.path); } catch (error) { return; }
+      if (inside(root, target) || inside(target, root)) {
+        if (!ctx.canAccess(userId, slug)) denied = true;
+        else if (inside(root, target)) allowed = true;
+      }
+    });
+    if (denied) return false;
+    if (ctx.osUsers) {
+      if (!user.linuxUser) return false;
+      try {
+        var identity = ctx.resolveIdentity(user.linuxUser);
+        return inside(fs.realpathSync(identity.home), target);
+      } catch (error) { return false; }
+    }
+    return allowed || ctx.users.getAllUsers().length === 1;
+  };
+}
+module.exports = { attachPathAccess: attachPathAccess };

package/lib/server-project-removal.js

@@ -0,0 +1,22 @@
+// Shared runtime removal used by the server callback and lifecycle controls.
+function removeProjectRuntime(projects, slug, awaitCompletion, registryRefresh) {
+  var project = projects.get(slug);
+  if (!project) return false;
+  var wasMate = project.getStatus().isMate;
+  var shutdownResult = project.destroy();
+  if (!awaitCompletion) projects.delete(slug);
+  if (shutdownResult && typeof shutdownResult.catch === 'function') {
+    shutdownResult.catch(function (error) {
+      console.error('[server] Project destroy failed for ' + slug + ':', error && error.message ? error.message : error);
+    });
+  }
+  if (!wasMate && registryRefresh) registryRefresh();
+  if (awaitCompletion) return Promise.resolve(shutdownResult).then(function (result) {
+    if (result !== true) throw new Error('Project runtime shutdown did not complete successfully: ' + slug);
+    if (projects.get(slug) !== project) throw new Error('Project runtime was replaced during shutdown: ' + slug);
+    projects.delete(slug);
+    return true;
+  });
+  return true;
+}
+module.exports = { removeProjectRuntime: removeProjectRuntime };

package/lib/server-settings.js

@@ -12,11 +12,13 @@ function attachSettings(ctx) {
   var CONFIG_DIR = ctx.CONFIG_DIR;
 
   var profilePath = path.join(CONFIG_DIR, "profile.json");
+  var contextualClaySettings = require('./server-contextual-clay-settings').attachContextualClaySettings(ctx);
   var appearanceSettings = require('./server-appearance-settings').attachAppearanceSettings(ctx);
   var notificationSettings = require('./server-notification-settings').attachNotificationSettings(ctx);
   var experimentalSettings = attachExperimentalSettings(ctx);
 
   function handleRequest(req, res, fullUrl) {
+    if (contextualClaySettings.handleRequest(req, res, fullUrl)) return true;
     if (appearanceSettings.handleRequest(req, res, fullUrl)) return true;
     if (notificationSettings.handleRequest(req, res, fullUrl)) return true;
     if (experimentalSettings.handleRequest(req, res, fullUrl)) return true;
@@ -755,7 +757,10 @@ function attachSettings(ctx) {
     return false;
   }
 
-  return { handleRequest: handleRequest };
+  return {
+    handleRequest: handleRequest,
+    getInitialAppearance: appearanceSettings.getInitialAppearance
+  };
 }
 
 module.exports = { attachSettings: attachSettings };