clay-server 4.0.0-beta.2 → 4.0.0-beta.21

package/lib/project-session-pair.js

@@ -1,20 +1,19 @@
 var pairMcp = require("./session-pair-mcp-server");
+var pairPrompts = require("./session-pair-prompts");
+var { attachPairFactory } = require("./session-pair-factory");
+var { attachPairLifecycle } = require("./project-pair-lifecycle");
+var { attachPairTurnControl } = require("./session-pair-turn-control");
+var driverEligibility = require("./session-driver-eligibility"), driverOrchestration = require("./session-driver-orchestration");
+var { attachWorkerPermission } = require("./project-worker-permission");
 var { attachWorkerProposal } = require("./project-worker-proposal");
-var yoke = require("./yoke");
-
 var MAX_RESPONSE_CHARS = 30000;
-
-function toolResult(value) {
-  return Promise.resolve({ content: [{ type: "text", text: JSON.stringify(value) }] });
-}
-
+function toolResult(value) { return Promise.resolve({ content: [{ type: "text", text: JSON.stringify(value) }] }); }
 function toolError(err) {
   return Promise.resolve({
     content: [{ type: "text", text: "Error: " + (err.message || err) }],
     isError: true,
   });
 }
-
 function responseText(history, fromIndex) {
   var text = "";
   for (var i = Math.max(0, fromIndex || 0); i < history.length; i++) {
@@ -59,11 +58,17 @@ function attachSessionPair(ctx) {
   var sm = ctx.sm;
   var store = ctx.splitStore;
   var workerProposal;
-
-  function groupAndPartner(caller) {
+  var workerPermission;
+  var lifecycle;
+  var turnControl = attachPairTurnControl({ sm: sm, splitStore: store });
+  function groupAndPartner(caller, missingPairMessage) {
     if (!caller) throw new Error("partner tools require a session-bound tool server");
+    // Captured handlers must remain bound to the exact live Session object.
+    if (sm.sessions.get(caller.localId) !== caller) {
+      throw new Error("this session is no longer live; the partner tools are bound to an exact session");
+    }
     var group = store.groupForMember(caller.localId);
-    if (!group) throw new Error("this session is not in a split group");
+    if (!group) throw new Error(missingPairMessage || "this session is not in a split group");
     if (group.pair && group.pair.driverId !== caller.localId) {
       throw new Error("only the configured Driver can direct this pair");
     }
@@ -93,27 +98,19 @@ function attachSessionPair(ctx) {
     broadcastDelegation(group, caller, partner, false);
   }
 
-  function resumeDriverWithResult(caller, partner, token) {
-    if (!token.detached || token.delivered || caller.destroying) return false;
-    token.delivered = true;
-    var failure = token.failure || null;
-    var response = token.response || "";
-    var text;
-    if (token.interrupted) {
-      text = "[Split Worker execution interrupted] The user interrupted the Split Worker mid-turn. Its work is PARTIAL and unverified — do not treat it as finished. Review what was done and decide next steps with the user.";
-    } else {
-      text = "A Split Worker task delegated through send_to_partner has finished.\n\n" +
-        "Original task:\n" + token.message + "\n\n" +
-        (failure ? "Split Worker error:\n" + failure : "Split Worker result:\n" + (response || "(No text response was recorded.)")) +
-        "\n\nReview the result, verify it as needed, and continue the task.";
-    }
-    sm.sendAndRecord(caller, {
+  function resumeDriverWithMessage(caller, text, meta) {
+    if (!caller || caller.destroying) return false;
+    if (turnControl.blockedReason(caller)) return false;
+    var record = {
       type: "user_message",
       text: text,
       _internal: true,
-      partnerResult: true,
-      partnerSessionId: partner.localId,
-    });
+    };
+    if (meta) {
+      var keys = Object.keys(meta);
+      for (var i = 0; i < keys.length; i++) record[keys[i]] = meta[keys[i]];
+    }
+    sm.sendAndRecord(caller, record);
     caller.lastActivity = Date.now();
     var sdk = ctx.getSdk();
     if (!sdk) {
@@ -138,6 +135,33 @@ function attachSessionPair(ctx) {
     return true;
   }
 
+  function resumeDriverWithResult(caller, partner, token) {
+    if (!token.detached || token.delivered || caller.destroying) return false;
+    token.delivered = true;
+    var failure = token.failure || null;
+    var response = token.response || "";
+    var text;
+    if (token.interrupted) {
+      text = "[Split Worker execution interrupted] The user interrupted the Split Worker mid-turn. Its work is PARTIAL and unverified — do not treat it as finished. Review what was done and decide next steps with the user.";
+    } else {
+      text = "A Split Worker task delegated through send_to_partner has finished.\n\n" +
+        "Original task:\n" + token.message + "\n\n" +
+        (failure ? "Split Worker error:\n" + failure : "Split Worker result:\n" + (response || "(No text response was recorded.)")) +
+        "\n\nReview the result, verify it as needed, and continue the task.";
+    }
+    return resumeDriverWithMessage(caller, text, {
+      partnerResult: true,
+      partnerSessionId: partner.localId,
+    });
+  }
+
+  function requestDetach(worker) {
+    var token = worker && worker._pairDelegation;
+    if (!token || token.detached || token.detachRequested) return false;
+    token.detachRequested = true;
+    return true;
+  }
+
   function handleTurnDone(partner) {
     var token = partner && partner._pairDelegation;
     if (!token) return false;
@@ -179,7 +203,8 @@ function attachSessionPair(ctx) {
           });
           return;
         }
-        if (Date.now() >= deadline) {
+        // Timeouts and permission requests both detach into the push-back path.
+        if (Date.now() >= deadline || token.detachRequested) {
           clearInterval(timer);
           token.detached = true;
           monitorPartner(group, caller, partner, token);
@@ -203,13 +228,11 @@ function attachSessionPair(ctx) {
   async function sendToPartner(args, caller) {
     try {
       if (caller && caller._delegatedBy) throw new Error("delegated turns cannot delegate to another session");
+      var resolved = groupAndPartner(caller,
+        "send_to_partner requires an exact existing Driver/Split Worker pair; call propose_worker while unpaired");
       var message = typeof args.message === "string" ? args.message.trim() : "";
       if (!message) throw new Error("message is required");
-      var created = null;
-      if (caller && !store.groupForMember(caller.localId)) {
-        created = createWorkerForDriver(caller, args);
-      }
-      var resolved = groupAndPartner(caller);
+      turnControl.assertWorkerAction(caller);
       var wait = args.wait !== false;
       var timeout = Number.isFinite(args.timeoutSeconds) ? Math.floor(args.timeoutSeconds) : 300;
       timeout = Math.max(1, Math.min(900, timeout));
@@ -247,13 +270,18 @@ function attachSessionPair(ctx) {
       if (!wait) {
         token.detached = true;
         monitorPartner(resolved.group, caller, partner, token);
-        return toolResult({ status: "running", partnerId: partner.localId, workerCreated: !!created, hint: "The completed result will be pushed back automatically. Use read_partner only for an interim status check." });
+        return toolResult({ status: "running", partnerId: partner.localId, hint: "The completed result will be pushed back automatically. Use read_partner only for an interim status check." });
       }
-      var completed = await waitForPartner(resolved.group, caller, partner, token, timeout);
-      if (created) {
-        completed.workerCreated = true;
-        completed.partnerId = partner.localId;
+      if (!partner.isProcessing && !partner._queryStarting) {
+        finishDelegation(resolved.group, caller, partner, token);
+        var immediateFailure = errorSince(partner.history || [], token.startIndex);
+        return toolResult({
+          status: immediateFailure ? "error" : "complete",
+          response: responseText(partner.history || [], token.startIndex),
+          error: immediateFailure || undefined,
+        });
       }
+      var completed = await waitForPartner(resolved.group, caller, partner, token, timeout);
       return toolResult(completed);
     } catch (e) {
       if (caller) {
@@ -274,13 +302,15 @@ function attachSessionPair(ctx) {
     try {
       var resolved = groupAndPartner(caller);
       var count = Number.isFinite(args.lastTurns) ? Math.floor(args.lastTurns) : 1;
-      count = Math.max(1, Math.min(5, count));
-      return toolResult({
+      count = Math.max(0, Math.min(5, count));
+      var payload = {
         status: resolved.partner.isProcessing ? "running" : (resolved.partner._lastTurnInterrupted ? "interrupted" : "idle"),
         partnerId: resolved.partner.localId,
         title: resolved.partner.title || "New Session",
-        turns: recentTurns(resolved.partner, count),
-      });
+        turns: count > 0 ? recentTurns(resolved.partner, count) : [],
+      };
+      payload.capacity = lifecycle.optionalStatus(caller);
+      return toolResult(payload);
     } catch (e) {
       return toolError(e);
     }
@@ -311,6 +341,7 @@ function attachSessionPair(ctx) {
         if (partner.abortController) partner.abortController.abort();
       }
       if (partner._pairDelegation) finishDelegation(resolved.group, caller, partner, partner._pairDelegation);
+      workerPermission.cancelForSession(partner, "The Driver closed the Split Worker pair.");
       var ws = { _clayUser: caller.ownerId ? { id: caller.ownerId } : null };
       var result = store.dissolve(ws, { id: resolved.group.id });
       if (!result.ok) throw new Error(result.error || "could not close the Worker pair");
@@ -320,115 +351,85 @@ function attachSessionPair(ctx) {
     }
   }
 
+  function handleHumanStop(session) {
+    var roles = turnControl.markHumanStop(session);
+    if (!roles) return false;
+    workerPermission.cancelForSession(roles.worker, "The human stopped this Split Worker turn.");
+    return true;
+  }
+
   function getToolDefs(boundSession) {
     if (!boundSession) return pairMcp.getToolDefs({
       send: function () { return toolError(new Error("send_to_partner requires a session-bound tool server")); },
       read: function () { return toolError(new Error("read_partner requires a session-bound tool server")); },
       interrupt: function () { return toolError(new Error("interrupt_partner requires a session-bound tool server")); },
       close: function () { return toolError(new Error("close_partner requires a session-bound tool server")); },
+      status: function () { return toolError(new Error("partner_status requires a session-bound tool server")); },
+      replace: function () { return toolError(new Error("replace_partner requires a session-bound tool server")); },
+      evaluate: function () { return toolError(new Error("record_partner_evaluation requires a session-bound tool server")); },
     });
-    // Mount whenever we have a bound session: MCP servers are fixed for the
-    // lifetime of a query, and Claude queries live across turns, so gating on
-    // group membership HERE would permanently hide the tools from a session
-    // whose split is created mid-conversation (the ad-hoc flow). Handlers
-    // re-resolve the group on every call, so an ungrouped session gets a
-    // clear error, and a session that gains a partner later just works.
-    // The one structural exclusion: a session that is ALREADY a configured
-    // pair worker at query start never sees the tools.
     var group = store.groupForMember(boundSession.localId);
     if (group && group.pair && group.pair.driverId !== boundSession.localId) return [];
+    var adHocSplit = !!(group && !group.pair);
+    if (!driverEligibility.isEligibleDriverSession(boundSession, sm)) return [];
+    var persistentCatalog = boundSession.vendor === "codex" && (!group || !!group.pair);
+    if (!group && !persistentCatalog) {
+      return workerProposal.getToolDefs(boundSession)
+        .concat(workerPermission.getToolDefs(boundSession, { dormantDriver: true }));
+    }
+    var lifecycleHandlers = lifecycle.toolHandlers(boundSession);
     var tools = pairMcp.getToolDefs({
-      send: function (args) { return sendToPartner(args, boundSession); },
+      send: function (args) {
+        return turnControl.runOperation(boundSession, "send", args && args.operationId, function () {
+          return sendToPartner(args || {}, boundSession);
+        });
+      },
       read: function (args) { return readPartner(args, boundSession); },
       interrupt: function (args) { return interruptPartner(args, boundSession); },
       close: function (args) { return closePartner(args, boundSession); },
-    });
-    return tools.concat(workerProposal.getToolDefs(boundSession));
-  }
-
-  function validateVendor(vendor) {
-    var installed = sm.installedVendors || [];
-    if (!vendor || installed.indexOf(vendor) === -1) throw new Error("vendor is not installed: " + (vendor || "unknown"));
-    return vendor;
-  }
-
-  function createPairRecord(ws, msg) {
-    if (ctx.isMate) throw new Error("Pair sessions are only available in projects");
-    var driverSpec = msg.driver || {};
-    var workerSpec = msg.worker || {};
-    var workerVendor = validateVendor(workerSpec.vendor || sm.lastVendor || "codex");
-    var ownerId = ws._clayUser && ctx.usersModule.isMultiUser() ? ws._clayUser.id : null;
-    var driver;
-    var groupName;
-    if (Number.isInteger(driverSpec.sessionId)) {
-      // "Add Split Worker" on an existing session: the current session becomes
-      // the Driver with its full conversation context intact.
-      driver = sm.sessions.get(driverSpec.sessionId);
-      if (!driver) throw new Error("driver session not found");
-      if ((driver.ownerId || null) !== ownerId) throw new Error("driver session access denied");
-      if (store.groupForMember(driver.localId)) throw new Error("this session is already in a split group");
-      groupName = undefined; // auto name from member titles
-    } else {
-      var driverVendor = validateVendor(driverSpec.vendor || "claude");
-      var driverEffort = yoke.clampEffort(driverVendor, driverSpec.effort || (sm.currentEffortByVendor && sm.currentEffortByVendor[driverVendor]) || sm.currentEffort || "medium") || null;
-      driver = sm.createSessionRaw({ ownerId: ownerId, vendor: driverVendor, model: driverSpec.model || null, effort: driverEffort });
-      driver.title = "Driver · " + ((yoke.getVendorInfo(driverVendor) || {}).displayName || driverVendor);
-      if (driverSpec.effort) driver.loopSettings = { effort: driverSpec.effort };
-      groupName = "Agent pair";
+      status: lifecycleHandlers.status,
+      replace: function (args) {
+        return turnControl.runOperation(boundSession, "replace", args && args.operationId, function () {
+          return workerProposal.proposeReplacement(args || {}, boundSession);
+        });
+      },
+      evaluate: lifecycleHandlers.evaluate,
+    }, { lifecycle: persistentCatalog || !adHocSplit });
+    if (persistentCatalog) {
+      return workerProposal.getToolDefs(boundSession, { persistent: true })
+        .concat(tools)
+        .concat(workerPermission.getToolDefs(boundSession, { dormantDriver: true }));
     }
-    var workerEffort = yoke.clampEffort(workerVendor, workerSpec.effort || (sm.currentEffortByVendor && sm.currentEffortByVendor[workerVendor]) || sm.currentEffort || "medium") || null;
-    var worker = sm.createSessionRaw({ ownerId: ownerId, vendor: workerVendor, model: workerSpec.model || null, effort: workerEffort });
-    worker.title = "Split Worker · " + ((yoke.getVendorInfo(workerVendor) || {}).displayName || workerVendor);
-    if (workerSpec.effort) worker.loopSettings = { effort: workerSpec.effort };
-    var result = store.create(ws, {
-      members: [driver.localId, worker.localId],
-      pair: { driverId: driver.localId, workerId: worker.localId },
-      name: groupName,
-    });
-    if (!result.ok) throw new Error(result.error);
-    sm.broadcastSessionList();
-    return { driver: driver, worker: worker, group: result.group };
+    return tools
+      .concat(workerPermission.getToolDefs(boundSession, { dormantDriver: false }));
   }
 
-  function createWorkerForDriver(driver, args) {
-    if (ctx.isMate) throw new Error("Pair sessions are only available in projects");
-    var installed = sm.installedVendors || [];
-    if (installed.length === 0) throw new Error("no coding agent is installed for a Split Worker session");
-    var vendor = typeof args.workerVendor === "string" ? args.workerVendor.trim() : "";
-    if (vendor) validateVendor(vendor);
-    if (!vendor) {
-      if (installed.indexOf("codex") !== -1 && driver.vendor !== "codex") vendor = "codex";
-      else {
-        vendor = installed[0];
-        for (var i = 0; i < installed.length; i++) {
-          if (installed[i] !== driver.vendor) { vendor = installed[i]; break; }
-        }
-      }
-    }
-    var ws = {
-      _clayActiveSession: driver.localId,
-      _clayUser: driver.ownerId ? { id: driver.ownerId } : null,
-    };
-    var created = createPairRecord(ws, {
-      driver: { sessionId: driver.localId },
-      worker: {
-        vendor: vendor,
-        model: typeof args.workerModel === "string" ? args.workerModel : "",
-        effort: typeof args.workerEffort === "string" ? args.workerEffort : "",
-      },
-    });
-    sm.sendToSession(driver, { type: "pair_session_created", ok: true, group: created.group });
-    return created;
-  }
+  var factory = attachPairFactory(ctx);
+  var createPairRecord = factory.createPairRecord;
+  var createWorkerForDriver = factory.createWorkerForDriver;
+  var createPair = factory.createPair;
+  var preflightWorkerForDriver = factory.preflightWorkerForDriver;
 
-  function createPair(ws, msg) {
-    try {
-      var created = createPairRecord(ws, msg);
-      ctx.sendTo(ws, { type: "pair_session_created", ok: true, group: created.group });
-    } catch (e) {
-      ctx.sendTo(ws, { type: "pair_session_created", ok: false, error: e.message || String(e) });
-    }
-  }
+  lifecycle = attachPairLifecycle({
+    sm: sm,
+    splitStore: store,
+    createWorkerForDriver: function (driver, args) { return createWorkerForDriver(driver, args); },
+    preflightWorkerForDriver: function (driver, args) { return preflightWorkerForDriver(driver, args); },
+    sendToPartner: function (args, caller) { return sendToPartner(args, caller); },
+    finishDelegation: finishDelegation,
+    cancelWorkerPermissions: function (worker, reason) {
+      return workerPermission.cancelForSession(worker, reason);
+    },
+    turnControl: turnControl,
+  });
+
+  workerPermission = attachWorkerPermission({
+    sm: sm,
+    splitStore: store,
+    onProcessingChanged: ctx.onProcessingChanged,
+    resumeDriverWithMessage: resumeDriverWithMessage,
+    requestDetach: requestDetach,
+  });
 
   workerProposal = attachWorkerProposal({
     sm: sm,
@@ -440,8 +441,11 @@ function attachSessionPair(ctx) {
     getLinuxUserForSession: ctx.getLinuxUserForSession,
     onProcessingChanged: ctx.onProcessingChanged,
     adapters: ctx.adapters,
+    dangerouslySkipPermissions: ctx.dangerouslySkipPermissions,
     createPairRecord: createPairRecord,
+    recordGenerationStart: function (driver, worker) { return lifecycle.recordGenerationStart(driver, worker); },
     sendToPartner: sendToPartner,
+    replacePartner: function (args, session) { return lifecycle.replacePartner(args, session); },
   });
 
   function handleMessage(ws, msg) {
@@ -468,18 +472,27 @@ function attachSessionPair(ctx) {
     var group = store.groupForMember(session.localId);
     var pairPrompt = "";
     if (group && group.pair && group.pair.driverId === session.localId) {
-      pairPrompt = "You are the Driver in a two-agent pair. The tools send_to_partner, read_partner, interrupt_partner, and close_partner are provided directly to you. Infer the user's intended target from conversational and UI context. References to the user-visible paired or split pane, its session, its activity or status, or a collaborator the user opened resolve to Clay's Split Worker and the appropriate partner tool. Internal Sub-agents are a distinct execution mechanism, not a lexical category; use them only when the user clearly intends internal or background parallel delegation rather than the visible paired session. When ambiguous and a visible pair exists, prefer the visible Split Worker. If the ambiguity would materially change where work runs, ask a concise clarification instead of guessing. Use send_to_partner to delegate concrete bounded work to the Split Worker. The human may also message or stop the Split Worker directly; treat that intervention as authoritative. Use close_partner immediately when the human asks to close, dismiss, or remove the Split Worker pane; it preserves the session history. A completed Split Worker turn leaves the Split Worker session available for more work. Use interrupt_partner when execution must stop or change direction but the pair should remain open; its work is partial and unverified until you review it. If review or user feedback requires corrections to the Split Worker's implementation, delegate a follow-up turn to that Split Worker instead of editing the Split Worker-owned files yourself. If the Split Worker is no longer available, keep the work in the visible Split Worker flow and use send_to_partner again after the stale pair is removed; never substitute a background Sub-agent. If a non-waiting delegation finishes later, Clay pushes the result back and resumes you automatically; use read_partner only when you need an interim status check. Integrate and verify the final outcome. Do not search the project for implementations of these tools, and do not delegate work that must be performed sequentially in this same session.";
-    } else if (!group && !ctx.isMate) {
-      pairPrompt = "Infer the user's intended target from conversational and UI context. References to a user-visible paired or split pane, its session, its activity or status, or a collaborator the user wants opened resolve to Clay's Split Worker and its partner tools. Internal Sub-agents are a distinct execution mechanism, not a lexical category; use them only when the user clearly intends internal or background parallel delegation rather than a visible paired session. When ambiguity would materially change where work runs, ask a concise clarification instead of guessing. When the user intends a visible collaborator, call send_to_partner directly; Clay will create the paired Split Worker session and open it in the right pane automatically before delivering the task. Do not ask the user to start split mode and do not use a background Sub-agent as a substitute for a visible Split Worker.";
+      pairPrompt = pairPrompts.DRIVER_CORE;
+      if (driverOrchestration.isHighTierDriverSession(session, sm)) {
+        pairPrompt += " " + pairPrompts.DRIVER_DELEGATION;
+      }
+    } else if (!group && !ctx.isMate && driverEligibility.isEligibleDriverSession(session, sm) &&
+      driverOrchestration.isHighTierDriverSession(session, sm)) {
+      pairPrompt = pairPrompts.UNPAIRED + " " + workerProposal.getSystemPrompt(session);
     }
-    return [pairPrompt, workerProposal.getSystemPrompt(session)].filter(Boolean).join("\n\n");
+    return pairPrompt;
   }
 
-  return { getToolDefs: getToolDefs, handleMessage: handleMessage, handleTurnDone: handleTurnDone, getSystemPrompt: getSystemPrompt };
+  return {
+    beginHumanTurn: turnControl.beginHumanTurn,
+    getToolDefs: getToolDefs,
+    handleHumanStop: handleHumanStop,
+    handleMessage: handleMessage,
+    handleTurnDone: handleTurnDone,
+    getSystemPrompt: getSystemPrompt,
+    respondToWorkerProposal: workerProposal.respondToProposal,
+    workerPermission: workerPermission,
+  };
 }
 
-module.exports = {
-  attachSessionPair: attachSessionPair,
-  responseText: responseText,
-  recentTurns: recentTurns,
-};
+module.exports = { attachSessionPair: attachSessionPair, responseText: responseText, recentTurns: recentTurns };

package/lib/project-session-spawn.js

@@ -198,7 +198,7 @@ function attachSessionSpawn(ctx) {
     var create = typeof sm.createSessionRaw === "function" ? sm.createSessionRaw : sm.createSession;
     var session = create.call(sm, {
       ownerId: parent.ownerId || null,
-      sessionVisibility: parent.sessionVisibility || "shared",
+      sessionVisibility: "private",
       vendor: vendor,
     });
     session.spawn = { parentId: parent.localId, index: index, batchId: batchId };

package/lib/project-sessions.js

@@ -3,7 +3,9 @@ var path = require("path");
 var crypto = require("crypto");
 var { execFileSync } = require("child_process");
 var { CODEX_DEFAULTS, getCodexConfig } = require("./codex-defaults");
+var updateSnooze = require("./update-snooze");
 var yoke = require("./yoke");
+var sessionVisibility = require("./session-visibility");
 
 function vendorSupportsTui(vendor) {
   var info = yoke.getVendorInfo(vendor);
@@ -71,6 +73,9 @@ function attachSessions(ctx) {
   var send = ctx.send;
   var sendTo = ctx.sendTo;
   var sendToAdmins = ctx.sendToAdmins;
+  var broadcastUpdateAvailable = ctx.broadcastUpdateAvailable || function () {};
+  var broadcastUpdateStarted = ctx.broadcastUpdateStarted || function () {};
+  var sendToUpdateUser = ctx.sendToUpdateUser || function () {};
   var sendToSession = ctx.sendToSession;
   var sendToSessionOthers = ctx.sendToSessionOthers;
   var opts = ctx.opts;
@@ -492,7 +497,7 @@ function attachSessions(ctx) {
       sm.sweepBlankSessions();
       var sessionOpts = {};
       if (ws._clayUser && usersModule.isMultiUser()) sessionOpts.ownerId = ws._clayUser.id;
-      if (msg.sessionVisibility) sessionOpts.sessionVisibility = msg.sessionVisibility;
+      sessionOpts.sessionVisibility = sessionVisibility.normalize(msg.sessionVisibility);
       if (msg.vendor) sessionOpts.vendor = msg.vendor;
       // Mode resolution: vendors without a TUI session mode are always GUI.
       // TUI-capable sessions honor the explicit msg.mode if provided, otherwise
@@ -577,7 +582,8 @@ function attachSessions(ctx) {
         if (reusable) {
           if (sessionOpts.vendor && reusable.vendor !== sessionOpts.vendor) reusable.vendor = sessionOpts.vendor;
           if (!reusable.effort) reusable.effort = sessionOpts.effort;
-          if (msg.sessionVisibility) reusable.sessionVisibility = msg.sessionVisibility;
+          sm.setSessionVisibility(reusable.localId, sessionOpts.sessionVisibility);
+          sessionVisibility.revokeViewers(ctx, reusable);
           sm.switchSession(reusable.localId, ws);
           newSess = reusable;
         } else {
@@ -605,9 +611,7 @@ function attachSessions(ctx) {
     }
 
     if (msg.type === "set_session_visibility") {
-      if (typeof msg.sessionId === "number" && (msg.visibility === "shared" || msg.visibility === "private")) {
-        sm.setSessionVisibility(msg.sessionId, msg.visibility);
-      }
+      sessionVisibility.handleChange(ctx, ws, msg);
       return true;
     }
 
@@ -897,25 +901,30 @@ function attachSessions(ctx) {
     }
 
     if (msg.type === "set_update_channel") {
-      if (usersModule.isMultiUser() && (!ws._clayUser || ws._clayUser.role !== "admin")) return true;
+      if (!updateSnooze.isUpdateAdmin(ws, usersModule)) return true;
       var newChannel = msg.channel === "beta" ? "beta" : "stable";
       setUpdateChannel(newChannel);
       setLatestVersion(null);
       if (typeof opts.onSetUpdateChannel === "function") {
         opts.onSetUpdateChannel(newChannel);
       }
-      // Re-fetch with new channel and broadcast to admin clients
+      // Re-fetch with new channel and broadcast to admin clients, honouring
+      // any snooze each of them has on the version that comes back.
       fetchVersion(newChannel).then(function (v) {
         if (v && isNewer(v, currentVersion)) {
           setLatestVersion(v);
-          sendToAdmins({ type: "update_available", version: v });
+          broadcastUpdateAvailable(v);
         }
       }).catch(function () {});
       return true;
     }
 
     if (msg.type === "check_update") {
-      if (usersModule.isMultiUser() && (!ws._clayUser || ws._clayUser.role !== "admin")) return true;
+      if (!updateSnooze.isUpdateAdmin(ws, usersModule)) return true;
+      // A manual check is the user deliberately re-engaging, so it answers
+      // truthfully and ends any snooze rather than reporting an update it
+      // would then refuse to show.
+      updateSnooze.clearSnooze(updateSnooze.userKeyFor(ws, usersModule));
       var updateChannel = getUpdateChannel();
       fetchVersion(updateChannel).then(function (v) {
         if (v && isNewer(v, currentVersion)) {
@@ -928,9 +937,40 @@ function attachSessions(ctx) {
       return true;
     }
 
+    if (msg.type === "update_snooze") {
+      if (!updateSnooze.isUpdateAdmin(ws, usersModule)) return true;
+      var snoozeKey = updateSnooze.userKeyFor(ws, usersModule);
+      // The target is always the server's own latest version. A version named
+      // in the payload is ignored, as are any timestamps or user ids.
+      var snoozeResult = updateSnooze.snooze(
+        snoozeKey,
+        getLatestVersion(),
+        msg.duration,
+        Date.now(),
+        msg.tzOffsetMinutes
+      );
+      if (!snoozeResult.ok) {
+        sendTo(ws, { type: "update_snoozed", ok: false, error: snoozeResult.error });
+        return true;
+      }
+      // Every live connection of this user, so a second device stops showing
+      // a banner the user has already dealt with.
+      sendToUpdateUser(snoozeKey, {
+        type: "update_snoozed",
+        ok: true,
+        version: snoozeResult.version,
+        until: snoozeResult.until,
+        duration: snoozeResult.duration,
+      });
+      return true;
+    }
+
     if (msg.type === "update_now") {
-      if (usersModule.isMultiUser() && (!ws._clayUser || ws._clayUser.role !== "admin")) return true;
-      send({ type: "update_started", version: getLatestVersion() || "" });
+      if (!updateSnooze.isUpdateAdmin(ws, usersModule)) return true;
+      // Installing makes any snooze moot; drop it so the record does not
+      // outlive the version it referred to.
+      updateSnooze.clearSnooze(updateSnooze.userKeyFor(ws, usersModule));
+      broadcastUpdateStarted(getLatestVersion());
       var _ipc = require("./ipc");
       var _config = require("./config");
       _ipc.sendIPCCommand(_config.socketPath(), { cmd: "update" });
@@ -964,7 +1004,8 @@ function attachSessions(ctx) {
 
     if (msg.type === "stop") {
       var session = getSessionForWs(ws);
-      if (session && session.isProcessing) {
+      if (session && (session.isProcessing || session._queryStarting)) {
+        if (typeof ctx.onHumanPairStop === "function") ctx.onHumanPairStop(session);
         session.taskStopRequested = true;
         if (session.abortController) session.abortController.abort();
       }
@@ -1736,8 +1777,12 @@ function attachSessions(ctx) {
         sendTo(ws, { type: "create_worktree_result", ok: false, error: "Invalid branch name" });
         return true;
       }
+      if (!/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(wtDirName)) {
+        sendTo(ws, { type: "create_worktree_result", ok: false, error: "Invalid worktree directory name" });
+        return true;
+      }
       if (typeof onCreateWorktree === "function") {
-        var wtResult = onCreateWorktree(slug, wtBranch, wtDirName, wtBase);
+        var wtResult = onCreateWorktree(slug, wtBranch, wtDirName, wtBase, ws._clayUser);
         sendTo(ws, { type: "create_worktree_result", ok: wtResult.ok, slug: wtResult.slug, error: wtResult.error });
       } else {
         sendTo(ws, { type: "create_worktree_result", ok: false, error: "Not supported" });