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

package/lib/server.js

@@ -23,6 +23,8 @@ var serverPalette = require("./server-palette");
 var workspaceQueryModule = require("./workspace-query-service");
 var { attachWorkspaceQueryService } = workspaceQueryModule;
 var { attachWorkspaceAssignmentService } = require("./workspace-assignment-service");
+var { attachProjectLogsService } = require("./project-logs-service");
+var { attachMateKnowledgeService } = require("./mate-knowledge-service");
 var serverEmail = require("./server-email");
 var serverGlobalWs = require("./server-global-ws");
 var { parseWsRequestUrl } = require("./ws-request");
@@ -306,18 +308,50 @@ function createServer(opts) {
   var workspaceQueryService = attachWorkspaceQueryService({
     getProjects: function () { return projects; },
     isMultiUser: function () { return users.isMultiUser(); },
-    canAccessProject: function (userId, status) {
-      return users.canAccessProject(userId, {
-        ownerId: status && status.projectOwnerId || null,
-        visibility: status && status.visibility || "public",
-        allowedUsers: status && status.allowedUsers || [],
-      });
+    // Project access is resolved from the authoritative project record, not
+    // from getStatus(), which carries no visibility or allowedUsers fields and
+    // would otherwise default every project to public.
+    onGetProjectAccess: onGetProjectAccess,
+    canAccessProject: function (userId, access) {
+      return users.canAccessProject(userId, access) === true;
     },
     resolveMate: function (userId, mateId) {
       return mates.getMate(mates.buildMateCtx(users.isMultiUser() ? userId : null), mateId);
     },
     assignmentService: assignmentService,
   });
+  // Project access is resolved from the authoritative project record, not from
+  // getStatus(), which carries no visibility or allowedUsers fields.
+  var projectLogsService = attachProjectLogsService({
+    getProjects: function () { return projects; },
+    isMultiUser: function () { return users.isMultiUser(); },
+    canAccessProject: function (userId, status) {
+      if (!status || !status.slug || !onGetProjectAccess) return false;
+      var access = onGetProjectAccess(status.slug);
+      if (!access || access.error) return false;
+      return users.canAccessProject(userId, access) === true;
+    },
+    resolveMate: function (userId, mateId) {
+      return mates.getMate(mates.buildMateCtx(users.isMultiUser() ? userId : null), mateId);
+    },
+    findUserById: function (userId) { return users.findUserById(userId); },
+  });
+  // Mate Knowledge reads the synchronized Knowledge records. The Mate list is
+  // derived from the owning user alone, so a binding can never span users.
+  var mateKnowledgeService = attachMateKnowledgeService({
+    getProjects: function () { return projects; },
+    isMultiUser: function () { return users.isMultiUser(); },
+    resolveMate: function (userId, mateId) {
+      return mates.getMate(mates.buildMateCtx(users.isMultiUser() ? userId : null), mateId);
+    },
+    listMates: function (userId) {
+      var mateCtx = mates.buildMateCtx(users.isMultiUser() ? userId : null);
+      var all = mates.getAllMates(mateCtx) || [];
+      return all.map(function (mate) {
+        return { id: mate.id, name: mate.name || null, createdBy: mate.createdBy || null, dir: mates.getMateDir(mateCtx, mate.id) };
+      });
+    },
+  });
 
   // --- Admin module ---
   var admin = serverAdmin.attachAdmin({
@@ -351,6 +385,9 @@ function createServer(opts) {
     projects: projects,
     opts: opts,
     CONFIG_DIR: CONFIG_DIR,
+    onCapsulesPreferenceChanged: function (userId) {
+      if (toolsHandler) toolsHandler.refreshMateCatalogs(userId);
+    },
   });
 
   var palette = serverPalette.attachPalette({
@@ -388,16 +425,38 @@ function createServer(opts) {
     securityHeaders["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains";
   }
 
-  function setSecurityHeaders(res) {
+  // Capsule rich-Display frames are served by a second listener on the same
+  // hostname but a different port, so frame-src cannot stay at the default
+  // 'self'. The allowance is computed from the request's own hostname with
+  // any port, never a wildcard host, and only for the scheme the app itself
+  // speaks. If the host header is unusable the CSP stays at 'self' and the
+  // frame silently falls back to the floor Display.
+  function frameSrcFor(req) {
+    var host = req && req.headers && typeof req.headers.host === "string" ? req.headers.host : "";
+    if (!host) return "'self'";
+    var scheme = tlsOptions ? "https" : "http";
+    var hostname;
+    try {
+      hostname = new URL(scheme + "://" + host).hostname;
+    } catch (error) {
+      return "'self'";
+    }
+    if (!hostname) return "'self'";
+    if (hostname.indexOf(":") !== -1) hostname = "[" + hostname + "]";
+    return "'self' " + scheme + "://" + hostname + ":*";
+  }
+
+  function setSecurityHeaders(res, req) {
     var keys = Object.keys(securityHeaders);
     for (var i = 0; i < keys.length; i++) {
       res.setHeader(keys[i], securityHeaders[keys[i]]);
     }
+    res.setHeader("Content-Security-Policy", securityHeaders["Content-Security-Policy"] + " frame-src " + frameSrcFor(req) + ";");
   }
 
   // --- HTTP handler ---
   var appHandler = function (req, res) {
-    setSecurityHeaders(res);
+    setSecurityHeaders(res, req);
     var fullUrl = req.url.split("?")[0];
 
     // --- Auth routes (delegated to server-auth) ---
@@ -937,17 +996,24 @@ function createServer(opts) {
 
   // --- WebSocket ---
   var wss = new WebSocketServer({ noServer: true });
+  var homePreferencesHandler = null;
 
   // Slug-less /ws handler: lets a user with no projects yet load the regular
   // app shell and create/add/clone their first one. Only knows about the
-  // small set of bootstrap messages (browse_dir, add_project, create_project,
-  // clone_project, ping).
+  // small set of bootstrap messages, including the Home preferences required
+  // to dismiss the workspace restoration screen.
   var globalWs = serverGlobalWs.attachGlobalWs({
     osUsers: osUsers,
     usersModule: users,
     onAddProject: onAddProject,
     onCreateProject: onCreateProject,
     onCloneProject: onCloneProject,
+    onHomePreferenceMessage: function (ws, msg) {
+      return homePreferencesHandler ? homePreferencesHandler.handleMessage(ws, msg) : false;
+    },
+    onAppMessage: function (ws, msg) {
+      return handleDmMessage(ws, msg);
+    },
   });
 
   server.on("upgrade", function (req, socket, head) {
@@ -1155,6 +1221,24 @@ function createServer(opts) {
   }
 
   // --- Project management ---
+  function refreshVendorAuthEverywhere(vendor, linuxUser) {
+    var refreshes = [];
+    projects.forEach(function (projectCtx) {
+      if (!projectCtx || typeof projectCtx.refreshVendorAuth !== "function") return;
+      try {
+        refreshes.push(Promise.resolve(projectCtx.refreshVendorAuth(vendor, linuxUser)).catch(function (err) {
+          console.error("[server] Cross-project " + vendor + " auth refresh failed:", err && err.message ? err.message : err);
+          return false;
+        }));
+      } catch (err) {
+        console.error("[server] Cross-project " + vendor + " auth refresh threw:", err && err.message ? err.message : err);
+      }
+    });
+    return Promise.all(refreshes).then(function (results) {
+      return results.some(function (refreshed) { return !!refreshed; });
+    });
+  }
+
   function addProject(cwd, slug, title, icon, projectOwnerId, worktreeMeta, extraOpts) {
     if (projects.has(slug)) return false;
     var extra = extraOpts || {};
@@ -1164,6 +1248,7 @@ function createServer(opts) {
       title: title || null,
       icon: icon || null,
       projectOwnerId: projectOwnerId || null,
+      projectKnowledgeId: extra.projectKnowledgeId || (worktreeMeta && worktreeMeta.projectKnowledgeId) || null,
       worktreeMeta: worktreeMeta || null,
       isMate: extra.isMate || false,
       mateId: extra.mateId || (extra.isMate ? path.basename(cwd) : null),
@@ -1174,6 +1259,8 @@ function createServer(opts) {
         return mateHandler.createReadyMateFromInterview(ws, userId, definition);
       },
       workspaceQueryService: workspaceQueryService,
+      projectLogsService: projectLogsService,
+      mateKnowledgeService: mateKnowledgeService,
       getProjectAccess: function () {
         return onGetProjectAccess ? onGetProjectAccess(slug) : { visibility: "public", ownerId: projectOwnerId || null };
       },
@@ -1327,6 +1414,7 @@ function createServer(opts) {
       onDmMessage: handleDmMessage,
       broadcastAll: broadcastAll,
       notificationsModule: _globalNotifications,
+      refreshVendorAuthEverywhere: refreshVendorAuthEverywhere,
       getProject: function (s) { return projects.get(s) || null; },
       isUserOnline: isUserOnline,
     });
@@ -1342,6 +1430,10 @@ function createServer(opts) {
     return true;
   }
 
+  function setProjectLogContextState(slug, status) {
+    return projectLogsService.setContextState(slug, status);
+  }
+
   // --- DM message handler (delegated to server-dm + server-mates inline) ---
   var dmHandler = serverDm.attachDm({
     users: users,
@@ -1362,9 +1454,10 @@ function createServer(opts) {
     projects: projects,
     addProject: addProject,
     workspaceQueryService: workspaceQueryService,
+    projectLogsService: projectLogsService,
   });
 
-  var homePreferencesHandler = serverHomePreferences.attachHomePreferences({
+  homePreferencesHandler = serverHomePreferences.attachHomePreferences({
     users: users,
     projects: projects,
   });
@@ -1373,6 +1466,17 @@ function createServer(opts) {
   var toolsHandler = serverTools.attachTools({
     users: users,
     projects: projects,
+    // The rich-Display frame listener must speak the same scheme as the app,
+    // or the sandboxed frame would be blocked as mixed content under TLS.
+    tlsOptions: tlsOptions,
+    // Lets a Capsule turn handed to the mate seat wake the opponent Mate's
+    // project, registering it first if it has never been opened.
+    findMateProject: homeChatHandler.findMateProject,
+    isCapsulesEnabled: function (userId) {
+      if (users.isMultiUser()) return users.getCapsulesEnabled(userId);
+      var daemonConfig = onGetDaemonConfig ? onGetDaemonConfig() : {};
+      return daemonConfig.capsulesEnabled === true;
+    },
   });
 
   // --- Mate handler ---
@@ -1383,13 +1487,14 @@ function createServer(opts) {
   }
 
   function handleDmMessage(ws, msg, routedProjectSlug) {
-    if (assignmentService.handleMessage(ws, msg, routedProjectSlug)) return;
-    if (dmHandler.handleMessage(ws, msg)) return;
-    if (mateHandler && mateHandler.handleMessage(ws, msg)) return;
-    if (emailHandler.handleMessage(ws, msg)) return;
-    if (homeChatHandler.handleMessage(ws, msg)) return;
-    if (homePreferencesHandler.handleMessage(ws, msg)) return;
-    if (toolsHandler.handleMessage(ws, msg)) return;
+    if (assignmentService.handleMessage(ws, msg, routedProjectSlug)) return true;
+    if (dmHandler.handleMessage(ws, msg)) return true;
+    if (mateHandler && mateHandler.handleMessage(ws, msg)) return true;
+    if (emailHandler.handleMessage(ws, msg)) return true;
+    if (homeChatHandler.handleMessage(ws, msg)) return true;
+    if (homePreferencesHandler.handleMessage(ws, msg)) return true;
+    if (toolsHandler.handleMessage(ws, msg)) return true;
+    return false;
   }
 
   function removeProject(slug) {
@@ -1683,6 +1788,7 @@ function createServer(opts) {
     forEachProject: forEachProject,
     destroyProject: removeProject,
     destroyAll: destroyAll,
+    setProjectLogContextState: setProjectLogContextState,
   };
 }
 

package/lib/session-driver-eligibility.js

@@ -0,0 +1,38 @@
+// Driver capability for a visible Driver/Split Worker pair.
+//
+// Model and vendor choice belongs to the user. A session does not need to
+// clear a model-tier threshold to coordinate a Split Worker; runtime catalog
+// validation belongs to session-pair-factory.js and applies equally to every
+// requested role. The only session-level exclusion here is structural: an
+// embedded terminal has no project chat surface on which to host the Driver
+// controls or the paired pane.
+
+var sessionProvenance = require("./session-provenance");
+
+function evaluateDriverSession(session) {
+  if (!session) {
+    return { ok: false, error: "No session was bound to this request." };
+  }
+  if (session.mode === "tui") {
+    return {
+      ok: false,
+      error: "An embedded terminal session cannot take the Driver role.",
+    };
+  }
+  if (sessionProvenance.isWorker(session)) {
+    return {
+      ok: false,
+      error: "A Split Worker session cannot take the Driver role.",
+    };
+  }
+  return { ok: true, error: null };
+}
+
+function isEligibleDriverSession(session) {
+  return evaluateDriverSession(session).ok;
+}
+
+module.exports = {
+  evaluateDriverSession: evaluateDriverSession,
+  isEligibleDriverSession: isEligibleDriverSession,
+};

package/lib/session-driver-orchestration.js

@@ -0,0 +1,31 @@
+// Model-tier policy for proactive Split Worker orchestration.
+//
+// Structural Driver eligibility remains model-agnostic. This policy only
+// decides whether a model should be prompted to judge when delegation helps.
+
+var HIGH_TIER_PATTERNS = {
+  claude: [/(?:^|-)fable(?:-|$)/i, /(?:^|-)opus(?:-|$)/i],
+  codex: [/^gpt-6(?:-|$)/i, /^gpt-[0-9]+(?:\.[0-9]+)?-sol(?:-|$)/i],
+};
+
+function resolvedModel(session, sm) {
+  if (!session) return "";
+  var vendor = session.vendor || "claude";
+  var defaults = sm && sm.defaultModelByVendor || {};
+  return session.model || defaults[vendor] || "";
+}
+
+function isHighTierDriverSession(session, sm) {
+  if (!session) return false;
+  var patterns = HIGH_TIER_PATTERNS[session.vendor || "claude"] || [];
+  var model = resolvedModel(session, sm);
+  for (var i = 0; i < patterns.length; i++) {
+    if (patterns[i].test(model)) return true;
+  }
+  return false;
+}
+
+module.exports = {
+  isHighTierDriverSession: isHighTierDriverSession,
+  resolvedModel: resolvedModel,
+};

package/lib/session-hygiene.js

@@ -2,6 +2,8 @@
 // "New session" request and which abandoned blanks are safe to sweep.
 // Pure decision logic only -- deletion/switching stays in sessions.js.
 
+var sessionProvenance = require("./session-provenance");
+
 var BLANK_SESSION_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 var CLAUDE_INTERRUPTED_TEXT = "[Request interrupted by user]";
 
@@ -19,6 +21,7 @@ function isBlankSession(s) {
     && !s.bookmarked
     && !s.spawn
     && !s.loop
+    && !sessionProvenance.isWorker(s)
     && (s.mode || "gui") !== "tui"
     && s.terminalId == null;
 }

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

@@ -9,14 +9,18 @@ var MEMORY_CONTRACT =
   "Important exception for deferred defects: while doing code or technical work, actively create a sticky note when you discover a concrete defect, regression risk, security issue, or data-loss risk that is outside the current session goal and will remain unfixed when the turn ends. Do not wait for the user to ask. Include the observable evidence, affected component, likely impact, and a clear next action. Check active notes first when a duplicate is plausible. Do not create defect notes for speculation, general cleanup ideas, or problems you fixed in the current session. " +
   "Important exception for deferred proposals: when you propose work (a fix, follow-up, improvement, or next step) and the user defers it rather than declining it (\"let's do that later\", \"next time\", \"after this\"), actively create a sticky note before the topic moves on. Do not wait to be asked. Capture what was proposed, why it mattered, and the agreed timing if any. Deferred agreements scroll out of chat history quickly and are hard to track; the board is where they survive. If the user declines the idea outright, do not write a note. " +
   "Never create a note merely because work is important, lengthy, spans agents or restarts, or might help another agent. Do not record completed work, implementation details, test results, investigation logs, transient blockers, conversation summaries, or announcements of your own activity. When uncertain, do not write. " +
-  "Updates are visible too: update only when durable state materially changes, and remove a note created by your session when it stops being useful instead of turning it into a completion log. Put a concise plain-text title on the first line, stay focused on one topic, and include only the context needed for future action.";
+  "Updates are visible too: update only when durable state materially changes. " +
+  "A note is an attention item, so finishing it means closing it, never erasing it: call close_note once the thing it is asking for is done, and the note leaves the active board while the record stays and can be reopened. Do not turn a note into a completion log instead of closing it. " +
+  "Put a concise plain-text title on the first line, stay focused on one topic, and include only the context needed for future action.";
 
 function getToolDefs(handlers) {
   return [
     {
       name: "list_notes",
-      description: MEMORY_CONTRACT + " List the active notes before writing when you need to avoid duplicates or inspect full memory beyond the injected summary.",
-      inputSchema: buildShape({}),
+      description: MEMORY_CONTRACT + " List the notes before writing when you need to avoid duplicates or inspect full memory beyond the injected summary. Lists open notes by default; pass state to see closed ones.",
+      inputSchema: buildShape({
+        state: { type: "string", enum: ["open", "closed", "all"], description: "Which notes to list. Defaults to open, the notes still asking for action." },
+      }),
       handler: function (args) { return handlers.list(args || {}); },
     },
     {
@@ -29,11 +33,27 @@ function getToolDefs(handlers) {
       }, ["text"]),
       handler: function (args) { return handlers.write(args || {}); },
     },
+    {
+      name: "close_note",
+      description: MEMORY_CONTRACT + " Close a note created by this same session once what it asked for is done. Closing is not deletion: the note leaves the active board, stays queryable under state closed, and can be reopened. Notes created by users or other sessions cannot be closed by this session.",
+      inputSchema: buildShape({
+        id: { type: "string", description: "Id of the note to close." },
+      }, ["id"]),
+      handler: function (args) { return handlers.close(args || {}); },
+    },
+    {
+      name: "reopen_note",
+      description: MEMORY_CONTRACT + " Reopen a closed note created by this same session when it turns out to still need action. The note returns to the active board unchanged.",
+      inputSchema: buildShape({
+        id: { type: "string", description: "Id of the note to reopen." },
+      }, ["id"]),
+      handler: function (args) { return handlers.reopen(args || {}); },
+    },
     {
       name: "remove_note",
-      description: MEMORY_CONTRACT + " Remove a note created by this same session when it is no longer true. Notes created by users or other sessions cannot be removed.",
+      description: MEMORY_CONTRACT + " Deprecated: use close_note. This tool no longer deletes anything and now closes the note instead, so an older caller cannot destroy a record. Same ownership rule as close_note.",
       inputSchema: buildShape({
-        id: { type: "string", description: "Id of the note to remove." },
+        id: { type: "string", description: "Id of the note to close. Nothing is deleted." },
       }, ["id"]),
       handler: function (args) { return handlers.remove(args || {}); },
     },

package/lib/session-pair-factory.js

@@ -0,0 +1,247 @@
+// Split-group pair creation.
+//
+// Extracted from project-session-pair.js, which operates a pair once it
+// exists; this module is only about how one comes into being. Both the
+// explicit "Add Split Worker", accepted proposal, and transactional replacement
+// flows land here, so vendor validation, owner derivation and the group record
+// are written in exactly one place.
+//
+// Ownership always comes from the connection or the Driver session, never from
+// the incoming message.
+//
+// CONTEXT CONTRACT: this module reads `sm`, `splitStore`, `isMate`,
+// `usersModule` and `sendTo` off its own argument, all at the top level.
+// attachSessionPair's context already carries all five, so it is passed
+// through unchanged. Re-wrapping it (it was once `{ sm, splitStore, ctx }`)
+// leaves `isMate`, `usersModule` and `sendTo` undefined, which silently
+// disables the Mate guard, breaks the pair_session_create reply, and throws
+// "Cannot read properties of undefined (reading 'isMultiUser')" the moment a
+// pair is created for an owned session — single-user installs escape it only
+// because a Driver with no ownerId short-circuits that expression. Add any new
+// dependency as a top-level field of that same context.
+//
+// Two ordering rules matter and are load-bearing:
+//
+//   1. Nothing is created until everything is validated. Driver capability and
+//      both runtime requests are settled first, so a rejected request leaves no
+//      orphan session behind. Any installed, available model may be the Driver;
+//      model choice is the user's rather than a server-side tier policy.
+//   2. `preflightRuntime` is side-effect free, so a caller that is about to
+//      destroy something (replacement dissolving a live pair) can validate the
+//      replacement first and abort while the old pair is still intact.
+
+var driverEligibility = require("./session-driver-eligibility");
+var models = require("./project-models");
+var yoke = require("./yoke");
+var sessionProvenance = require("./session-provenance");
+
+function attachPairFactory(ctx) {
+  var sm = ctx.sm;
+  var store = ctx.splitStore;
+
+  function validateVendor(vendor) {
+    var installed = sm.installedVendors || [];
+    if (!vendor || installed.indexOf(vendor) === -1) throw new Error("vendor is not installed: " + (vendor || "unknown"));
+    return vendor;
+  }
+
+  // An explicitly requested model must exist in the server's own catalog for
+  // that vendor, matched through the repo's canonical matcher so an alias, an
+  // id or a resolvedModel all count. Caller text is never taken on trust: if
+  // the catalog is not populated we cannot confirm the model, so an explicit
+  // request fails closed rather than being forwarded blindly.
+  function validateModel(vendor, model) {
+    var requested = typeof model === "string" ? model.trim() : "";
+    if (!requested) return null;
+    var catalog = (sm.modelsByVendor && sm.modelsByVendor[vendor]) || [];
+    if (catalog.length === 0) {
+      throw new Error("no models are available yet for vendor \"" + vendor +
+        "\", so model \"" + requested + "\" cannot be confirmed");
+    }
+    for (var i = 0; i < catalog.length; i++) {
+      if (models.modelEntryMatches(catalog[i], requested)) return requested;
+    }
+    throw new Error("model is not available for vendor \"" + vendor + "\": " + requested);
+  }
+
+  function validateEffort(vendor, effort) {
+    var requested = typeof effort === "string" ? effort.trim() : "";
+    var fallback = (sm.currentEffortByVendor && sm.currentEffortByVendor[vendor]) || sm.currentEffort || "medium";
+    var clamped = yoke.clampEffort(vendor, requested || fallback) || null;
+    if (requested && !clamped) {
+      throw new Error("reasoning effort is not supported for vendor \"" + vendor + "\": " + requested);
+    }
+    return clamped;
+  }
+
+  // Resolve and validate one session runtime request without creating
+  // anything. Throws on the first unusable field.
+  function preflightRuntime(spec, defaultVendor) {
+    var request = spec || {};
+    var vendor = validateVendor((typeof request.vendor === "string" && request.vendor.trim()) || defaultVendor);
+    return {
+      vendor: vendor,
+      model: validateModel(vendor, request.model),
+      effort: validateEffort(vendor, request.effort),
+      explicitEffort: !!(typeof request.effort === "string" && request.effort.trim()),
+    };
+  }
+
+  // The default Worker vendor for an accepted proposal or replacement prefers
+  // a different engine from the Driver's own, so the pair does not double up.
+  function defaultWorkerVendorFor(driver) {
+    var installed = sm.installedVendors || [];
+    if (installed.length === 0) throw new Error("no coding agent is installed for a Split Worker session");
+    if (installed.indexOf("codex") !== -1 && driver.vendor !== "codex") return "codex";
+    for (var i = 0; i < installed.length; i++) {
+      if (installed[i] !== driver.vendor) return installed[i];
+    }
+    return installed[0];
+  }
+
+  // Side-effect-free check that this exact Driver could create this exact
+  // Worker right now. Used by replacement before it touches anything.
+  function preflightWorkerForDriver(driver, args) {
+    if (ctx.isMate) throw new Error("Pair sessions are only available in projects");
+    if (!driver) throw new Error("driver session not found");
+    var verdict = driverEligibility.evaluateDriverSession(driver, sm);
+    if (!verdict.ok) throw new Error(verdict.error);
+    var options = args || {};
+    var vendor = typeof options.workerVendor === "string" ? options.workerVendor.trim() : "";
+    return preflightRuntime({
+      vendor: vendor || defaultWorkerVendorFor(driver),
+      model: options.workerModel,
+      effort: options.workerEffort,
+    }, null);
+  }
+
+  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 ownerId = ws._clayUser && ctx.usersModule.isMultiUser() ? ws._clayUser.id : null;
+
+    // --- Validate everything first; create nothing yet. ---
+
+    var workerRuntime = preflightRuntime(workerSpec, sm.lastVendor || "codex");
+
+    var existingDriver = null;
+    var driverRuntime = null;
+    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.
+      existingDriver = sm.sessions.get(driverSpec.sessionId);
+      if (!existingDriver) throw new Error("driver session not found");
+      if ((existingDriver.ownerId || null) !== ownerId) throw new Error("driver session access denied");
+      if (store.groupForMember(existingDriver.localId)) throw new Error("this session is already in a split group");
+      var existingVerdict = driverEligibility.evaluateDriverSession(existingDriver, sm);
+      if (!existingVerdict.ok) throw new Error(existingVerdict.error);
+      groupName = undefined; // auto name from member titles
+    } else {
+      driverRuntime = preflightRuntime(driverSpec, "claude");
+      groupName = "Agent pair";
+    }
+
+    // --- Everything is valid; now create. ---
+
+    var driver = existingDriver;
+    var createdDriver = null;
+    if (!driver) {
+      driver = sm.createSessionRaw({
+        ownerId: ownerId,
+        vendor: driverRuntime.vendor,
+        model: driverRuntime.model,
+        effort: driverRuntime.effort,
+      });
+      createdDriver = driver;
+      driver.title = "Driver · " + ((yoke.getVendorInfo(driverRuntime.vendor) || {}).displayName || driverRuntime.vendor);
+      if (driverRuntime.explicitEffort) driver.loopSettings = { effort: driverRuntime.effort };
+    }
+
+    var worker = sm.createSessionRaw({
+      ownerId: ownerId,
+      vendor: workerRuntime.vendor,
+      model: workerRuntime.model,
+      effort: workerRuntime.effort,
+    });
+    worker.title = "Split Worker · " + ((yoke.getVendorInfo(workerRuntime.vendor) || {}).displayName || workerRuntime.vendor);
+    if (workerRuntime.explicitEffort) worker.loopSettings = { effort: workerRuntime.effort };
+
+    var result;
+    try {
+      // Creation provenance is durable and independent from the active split
+      // group. Persist both ends before the group's broadcast so the Worker
+      // never flashes as unrelated and survives a restart with its parentage.
+      sessionProvenance.markWorker(driver, worker, sm.sessions);
+      if (typeof sm.saveSessionFile === "function") {
+        sm.saveSessionFile(driver);
+        sm.saveSessionFile(worker);
+      }
+
+      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);
+    } catch (e) {
+      // Any failure after session creation must remove exactly the sessions
+      // made by this call. An existing Driver is never removed.
+      removeCreated(worker);
+      removeCreated(createdDriver);
+      throw e;
+    }
+    sm.broadcastSessionList();
+    return { driver: driver, worker: worker, group: result.group };
+  }
+
+  function removeCreated(session) {
+    if (!session) return;
+    if (typeof sm.deleteSessionQuiet === "function") {
+      try { sm.deleteSessionQuiet(session.localId); return; } catch (e) {}
+    }
+    try { sm.sessions.delete(session.localId); } catch (e) {}
+  }
+
+  function createWorkerForDriver(driver, args) {
+    // Validates the Driver's capability and the whole Worker runtime before
+    // any session is made, so a rejection creates nothing.
+    var runtime = preflightWorkerForDriver(driver, args);
+    var ws = {
+      _clayActiveSession: driver.localId,
+      _clayUser: driver.ownerId ? { id: driver.ownerId } : null,
+    };
+    var created = createPairRecord(ws, {
+      driver: { sessionId: driver.localId },
+      worker: {
+        vendor: runtime.vendor,
+        model: runtime.model || "",
+        effort: runtime.explicitEffort ? (args && args.workerEffort) || "" : "",
+      },
+    });
+    sm.sendToSession(driver, { type: "pair_session_created", ok: true, group: created.group });
+    return created;
+  }
+
+  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) });
+    }
+  }
+
+  return {
+    createPair: createPair,
+    createPairRecord: createPairRecord,
+    createWorkerForDriver: createWorkerForDriver,
+    preflightRuntime: preflightRuntime,
+    preflightWorkerForDriver: preflightWorkerForDriver,
+    validateModel: validateModel,
+    validateVendor: validateVendor,
+  };
+}
+
+module.exports = { attachPairFactory: attachPairFactory };