clay-server 4.3.0-beta.4 → 4.3.0-beta.6

package/lib/session-pair-factory.js

@@ -34,6 +34,7 @@ var driverEligibility = require("./session-driver-eligibility");
 var models = require("./project-models");
 var yoke = require("./yoke");
 var sessionProvenance = require("./session-provenance");
+var splitRoles = require("./session-split-group-roles");
 
 function attachPairFactory(ctx) {
   var sm = ctx.sm;
@@ -230,6 +231,69 @@ function attachPairFactory(ctx) {
     return created;
   }
 
+  function createUnpairedWorkerForDriver(driver, args) {
+    var runtime = preflightWorkerForDriver(driver, args);
+    var worker = sm.createSessionRaw({
+      ownerId: driver.ownerId || null,
+      vendor: runtime.vendor,
+      model: runtime.model,
+      effort: runtime.effort,
+    });
+    try {
+      worker.title = "Split Worker · " + ((yoke.getVendorInfo(runtime.vendor) || {}).displayName || runtime.vendor);
+      if (runtime.explicitEffort) worker.loopSettings = { effort: runtime.effort };
+      sessionProvenance.markWorker(driver, worker, sm.sessions);
+      if (typeof sm.saveSessionFile === "function") {
+        if (sm.saveSessionFile(driver) === false || sm.saveSessionFile(worker) === false) {
+          throw new Error("Split Worker session persistence returned false");
+        }
+      }
+      return worker;
+    } catch (error) {
+      removeCreated(worker);
+      throw error;
+    }
+  }
+
+  function exactMutation(driver, worker, args, method) {
+    var group = store.groupForMember(driver.localId);
+    if (!group) throw new Error("split group not found");
+    var role = splitRoles.normalizePair(group.pair, group.members);
+    if (!role.ok || role.kind === "adhoc") throw new Error("split group roles changed");
+    var created = createUnpairedWorkerForDriver(driver, args);
+    var request = {
+      groupId: group.id,
+      driverId: driver.localId,
+      driverOriginId: driver.sessionOriginId || null,
+      expectedGroup: args.expectedGroup || group,
+      expectedWorkerIds: Array.isArray(args.expectedWorkerIds) ? args.expectedWorkerIds.slice() : role.workerIds.slice(),
+      newWorkerId: created.localId,
+      newWorkerOriginId: created.sessionOriginId || null,
+    };
+    if (worker) {
+      request.workerId = worker.localId;
+      request.workerOriginId = worker.sessionOriginId || null;
+      request.generation = worker._pairGeneration ||
+        worker.sessionProvenance && worker.sessionProvenance.generation || null;
+    }
+    var result = store[method](driver.ownerId || null, request, ctx.multiWorkerFeature);
+    if (!result.ok) {
+      removeCreated(created);
+      throw new Error(result.error);
+    }
+    sm.broadcastSessionList();
+    sm.sendToSession(driver, { type: "pair_session_created", ok: true, group: result.group });
+    return { driver: driver, worker: created, group: result.group };
+  }
+
+  function addWorkerForDriver(driver, args) {
+    return exactMutation(driver, null, args, "addWorker");
+  }
+
+  function replaceWorkerForDriver(driver, worker, args) {
+    return exactMutation(driver, worker, args, "replaceWorker");
+  }
+
   function createOwnedPair(ownerId, args) {
     if (ctx.isMate) throw new Error("Pair sessions are only available in projects");
     var request = args || {};
@@ -276,6 +340,8 @@ function attachPairFactory(ctx) {
     createPair: createPair,
     createPairRecord: createPairRecord,
     createWorkerForDriver: createWorkerForDriver,
+    addWorkerForDriver: addWorkerForDriver,
+    replaceWorkerForDriver: replaceWorkerForDriver,
     createOwnedPair: createOwnedPair,
     removeOwnedPair: removeOwnedPair,
     preflightRuntime: preflightRuntime,

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

@@ -19,31 +19,33 @@ function getToolDefs(handlers, options) {
       description: "Delegate one concrete follow-up task to the existing visible Split Worker. This tool is exposed only after the user has configured and accepted an exact pair. A completed turn does not end the Split Worker session: reuse the same Split Worker for follow-up implementation and corrections instead of taking over its work. Detached completions are pushed back automatically. A delegated turn cannot delegate back, so keep orchestration one hop deep.",
       inputSchema: buildShape({
         message: { type: "string", description: "The complete task or question for the partner." },
-        wait: { type: "boolean", description: "Wait for the partner's turn to finish. Defaults to true." },
+        wait: { type: "boolean", description: "Wait for the partner's turn to finish. Defaults to false; set true for an explicit blocking wait." },
         timeoutSeconds: { type: "number", description: "Maximum wait in seconds, from 1 to 900. Defaults to 300." },
         operationId: { type: "string", description: "Optional stable id for this delegation. Reusing it within the same human turn returns the original operation instead of sending twice." },
         taskId: { type: "string", description: "Optional stable task id for generation and completion correlation." },
+        workerId: { type: "number", description: "Optional exact Worker session id; required when multiple Workers are configured." },
       }, ["message"]),
       handler: function (args) { return handlers.send(args || {}); },
     },
     {
       name: "read_partner",
-      description: "Read the Split Worker's current status and recent conversation turns, plus the same bounded capacity report partner_status returns. Use this for an interim check after a non-waiting delegation or timeout; completed results are pushed automatically.",
+      description: "Read the Split Worker's current status and recent conversation turns, plus the same bounded capacity report partner_status returns. Use only for a requested status, concrete failure or stall diagnosis, or capacity/queue decision; do not poll routinely. Completed results are pushed automatically.",
       inputSchema: buildShape({
         lastTurns: { type: "number", description: "Number of recent user-message-delimited turns, from 0 to 5. Use 0 for status only. Defaults to 1." },
+        workerId: { type: "number", description: "Optional exact Worker session id; required when multiple Workers are configured." },
       }),
       handler: function (args) { return handlers.read(args || {}); },
     },
     {
       name: "interrupt_partner",
       description: "Interrupt the Split Worker's current task. Use this when the task is going in the wrong direction, needs to be reprioritized, or must stop before the next instruction. The Split Worker returns any partial result to you for review.",
-      inputSchema: buildShape({ reason: { type: "string", description: "Why the Driver is interrupting this task." } }),
+      inputSchema: buildShape({ reason: { type: "string", description: "Why the Driver is interrupting this task." }, workerId: { type: "number", description: "Optional exact Worker session id; required when multiple Workers are configured." } }),
       handler: function (args) { return handlers.interrupt(args || {}); },
     },
     {
       name: "close_partner",
       description: "Close the visible Split Worker pane and dissolve the Driver/Split Worker pair while preserving both session histories. If the Split Worker is still running, Clay interrupts it before closing the pair.",
-      inputSchema: buildShape({}),
+      inputSchema: buildShape({ workerId: { type: "number", description: "Optional exact Worker session id; required when multiple Workers are configured." } }),
       handler: function (args) { return handlers.close(args || {}); },
     },
   ];
@@ -55,13 +57,14 @@ function getToolDefs(handlers, options) {
       inputSchema: buildShape({
         message: { type: "string", description: "Bounded correction or context for the current active Worker turn." },
         requestId: { type: "string", description: "Optional stable request id. Reuse it to deduplicate a retried delivery within this human turn." },
+        workerId: { type: "number", description: "Optional exact Worker session id; required when multiple Workers are configured." },
       }, ["message"]),
       handler: function (args) { return handlers.message(args || {}); },
     },
     {
       name: "partner_status",
       description: "Bounded capacity and continuity report for your Split Worker, for deciding reuse against replacement: context tokens used and the ratio of its window, current task and activity, vendor/model/effort, history size and idle time, whether it is safe to replace right now, and your own recorded results for earlier Worker generations. Returns no transcript. Prefer this over reading turns when you only need to decide.",
-      inputSchema: buildShape({}),
+      inputSchema: buildShape({ workerId: { type: "number", description: "Optional exact Worker session id; required when multiple Workers are configured." } }),
       handler: function (args) { return handlers.status(args || {}); },
     },
     {
@@ -80,6 +83,7 @@ function getToolDefs(handlers, options) {
         },
         operationId: { type: "string", description: "Optional stable id for this replacement. Reusing it within the same human turn returns the original operation instead of replacing twice." },
         supersedeProposalId: { type: "string", description: "Exact pending replacement proposal id to supersede with this new configuration." },
+        workerId: { type: "number", description: "Optional exact Worker session id; required when multiple Workers are configured." },
       }, ["message", "recommendationRationale"]),
       handler: function (args) { return handlers.replace(args || {}); },
     },
@@ -90,6 +94,7 @@ function getToolDefs(handlers, options) {
         outcome: { enum: EVALUATION_OUTCOMES, description: 'One of "succeeded", "partial", "failed", "abandoned".' },
         note: { type: "string", description: "Optional short reason, up to 400 characters." },
         generation: { type: "number", description: "Optional generation number. Defaults to the current Worker." },
+        workerId: { type: "number", description: "Optional exact Worker session id; required when multiple Workers are configured." },
       }, ["outcome"]),
       handler: function (args) { return handlers.evaluate(args || {}); },
     },

package/lib/session-pair-prompts.js

@@ -4,32 +4,42 @@
 // the size limit and so the guidance can be reviewed as prose.
 
 var WORKER_RUNTIME_SELECTION = [
-  "Use a high-low model mix by default: keep decomposition, judgment, review, and independent verification",
-  "with the Driver. Give the Split Worker concrete, bounded execution tasks with clear acceptance criteria.",
-  "For routine bounded implementation, start with a lightweight Worker at low effort. When the installed",
-  "catalog offers it, codex / gpt-5.6-luna / low is the starting recommendation; otherwise choose a comparable",
-  "lightweight option from the offered catalog. Do not routinely recommend gpt-5.6-sol at high effort.",
-  "Do not mirror the Driver's model or default to the",
-  "strongest available model merely because it is available. Explicitly fill the vendor, model, and thinking",
-  "effort recommendation fields for both creation and replacement; never leave model selection to card defaults.",
-  "Select model capability and thinking effort separately. Start with the lowest effort adequate for the task,",
-  "not high effort by habit. Choose from the installed, offered catalog; do not invent model availability or prices.",
-  "Explain why the lighter choice can handle the task. Escalate only for a concrete requirement beyond its",
-  "capabilities or observed failures it cannot adequately resolve, and state that reason. Small corrections",
-  "found during Driver review are not by themselves a reason to escalate. Send those corrections back to the",
-  "Worker and verify the final result. Optimize for time to a completed, verified outcome, not first-draft speed.",
-  "Use recorded Worker outcomes when available,",
-  "and reconsider a lighter model for the next bounded task after an escalation. Honor the user's explicit",
-  "runtime choice; this is a recommendation policy, not a restriction on which model the user may select.",
+  "Use a role-based mix by default: keep decomposition, judgment, review, and independent verification with",
+  "the Driver, and give the Split Worker concrete, bounded execution tasks with clear acceptance criteria.",
+  "Recommend the lowest-capability model and thinking effort that are adequate for the specific task, based on",
+  "the requirements, the server-provided capability evidence, the offered runtime catalog, and recorded local",
+  "Worker outcomes. Choose vendor, model, and effort separately. Do not mirror the Driver, prefer a vendor by",
+  "Explicitly fill the vendor, model, and thinking effort recommendation fields for both creation and replacement;",
+  "never rely on card defaults or leave model selection implicit.",
+  "brand, or default to the strongest available option. Do not invent availability, prices, rankings, or missing",
+  "metadata. If the catalog or capability evidence is incomplete, say what is unknown and choose only from what",
+  "is actually offered. Honor an explicit user runtime choice; this is guidance, not a restriction.",
+  "Escalate only for a concrete task requirement or an observed failure the current runtime cannot resolve, and",
+  "state the evidence. A small review correction is not by itself an escalation reason; send one consolidated",
+  "bounded correction to the Worker and verify the result. Repeated same-class failures require reassessing the",
+  "task contract, model, and effort with evidence, not endless cheap-model loops or escalation of every correction.",
+  "Aim for a role-based workload direction near 30 percent Driver and 70 percent Worker effort when useful, but",
+  "never promise that ratio or treat it as a quota, token, or cost guarantee, and never pad work to reach it.",
 ].join(" ").replace(/ {2,}/g, " ");
 
 var DRIVER_DELEGATION = [
-  "Your management objective: protect your own context, keep the Split Worker compact, and put execution where",
-  "it runs best. Delegate implementation-heavy work rather than doing it here. Treat work spanning multiple modules,",
-  "crossing client/server/data boundaries, requiring a migration, or containing independent investigation and",
-  "execution as implementation-heavy. Your own capability is not a reason to retain that execution: preserve",
-  "the Driver for decomposition, runtime selection, judgment, review, and integration unless the user explicitly",
-  "asks you to work directly or the work must remain sequential in this session.",
+  "Your management objective: protect your own context, keep the Split Worker compact, and put substantive execution where it runs best.",
+  "Delegate implementation-heavy work rather than doing it here. Treat work spanning multiple modules, crossing",
+  "client/server/data boundaries, requiring independent investigation, testing, or self-correction as implementation-heavy.",
+  "Your own capability is not a reason to retain that execution: preserve the Driver for decomposition,",
+  "runtime selection, judgment, review, and integration unless the user explicitly asks you to work directly or the",
+  "work must remain sequential in this session.",
+  "Give each Worker one bounded contract: goal and scope, constraints and non-goals, acceptance commands and the",
+  "expected behaviors, and the required handoff. Delegate substantive investigation, implementation, testing, and",
+  "self-correction. The Worker must finish its allowed scope, inspect its diff against the criteria, run meaningful",
+  "production-path tests, and correct failures before reporting. It must not hand back an unchecked draft. Require",
+  "a bounded self-correction attempt; when progress is not possible, require a precise blocker and evidence.",
+  "Review once per coherent completed milestone with risk-focused source review and independent verification. Do not",
+  "rubber-stamp or sacrifice quality for an efficiency direction. Consolidate review feedback into one correction",
+  "task rather than sending overlapping live and queued work.",
+  "When discussing measured efficiency, distinguish requests, input tokens, output tokens, cached tokens, and cost.",
+  "Unknown usage is not zero; the 30/70 direction is role-based and aspirational, not a guaranteed token or cost",
+  "ratio or quota.",
 ].join(" ").replace(/ {2,}/g, " ");
 
 var DRIVER_CORE = [
@@ -76,7 +86,13 @@ var DRIVER_CORE = [
   "ambiguous and a visible pair exists, prefer the visible Split Worker. 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 its files yourself. If a non-waiting delegation finishes later, Clay pushes the result back and",
-  "resumes you automatically. You also decide the Split Worker's tool-permission requests when they arise;",
+  "resumes you automatically. send_to_partner returns immediately by default; set wait to true only when you",
+  "explicitly need the final result in the same tool call. Do useful independent work after a non-waiting",
+  "delegation, then yield for Clay's automatic completion callback; do not poll read_partner or partner_status,",
+  "or sleep while waiting. Use those reads only for a user-requested status, concrete failure or stall diagnosis,",
+  "capacity/reuse decision, or exact queue inspection before mutation. Do not send the same correction as both",
+  "a live message and a queued task; consolidate review feedback into one bounded follow-up. You also decide",
+  "the Split Worker's tool-permission requests when they arise;",
   "approve only what falls inside the task the user authorized. 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.",
@@ -85,7 +101,7 @@ var DRIVER_CORE = [
 var DRIVER = DRIVER_CORE + " " + DRIVER_DELEGATION;
 
 function worker(taskId) {
-  return "You are the configured Split Worker. For task " + (taskId || "unknown") + ", call report_partner_outcome before finishing when the tool is available. Report only what you observed: changed files, verification commands/results, unverified work, running processes, and next action. Never claim Driver verification.";
+  return "You are the configured Split Worker. For task " + (taskId || "unknown") + ", finish only the allowed bounded scope. Inspect your diff against the stated acceptance criteria, run meaningful production-path tests, and correct your own failures within a bounded self-correction attempt before reporting. Do not hand back an unchecked draft or hide a failure; if progress is blocked, report the precise blocker and evidence. Call report_partner_outcome before finishing when the tool is available. Report only what you observed: changed files and behavior, commands with actual exit results, known limits or unverified work, running processes, and next action. Never claim Driver verification.";
 }
 
 var UNPAIRED = [

package/lib/session-pair-target.js

@@ -0,0 +1,42 @@
+var splitRoles = require("./session-split-group-roles");
+var multiWorkerFeature = require("./multi-worker-feature");
+
+function resolveGroupTarget(sm, group, caller, args, options) {
+  if (!caller || 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 requestedWorkerId = args && args.workerId;
+  var normalized = splitRoles.normalizePair(group && group.pair, group && group.members);
+  if (!normalized.ok) throw new Error(normalized.error);
+  var workerId;
+  if (normalized.kind === "adhoc") {
+    workerId = group.members[0] === caller.localId ? group.members[1] : group.members[0];
+    if (requestedWorkerId != null && requestedWorkerId !== workerId) throw new Error("workerId must identify the exact split partner");
+  } else {
+    if (normalized.driverId !== caller.localId) throw new Error("only the configured Driver can direct this pair");
+    var target = splitRoles.resolveWorkerTarget(normalized, requestedWorkerId);
+    if (!target.ok) throw new Error(target.error);
+    workerId = target.workerId;
+    if (normalized.kind === "versioned" && (!options || options.readOnly !== true) &&
+        (!options || !multiWorkerFeature.isEnabled(options.multiWorkerFeature))) {
+      throw new Error("multi-Worker mutations remain gated until lifecycle, result, and Stop routing are migrated");
+    }
+  }
+  var worker = sm.sessions.get(workerId);
+  if (!worker || sm.sessions.get(worker.localId) !== worker) throw new Error("split partner session was not found");
+  if ((caller.ownerId || null) !== (worker.ownerId || null)) throw new Error("split partner access denied");
+  if (group.members.indexOf(caller.localId) === -1 || group.members.indexOf(worker.localId) === -1) {
+    throw new Error("the exact caller and Worker must both belong to this split group");
+  }
+  return { group: group, partner: worker, role: normalized, workerId: workerId };
+}
+
+function rolesFor(sm, store, session) {
+  if (!session || sm.sessions.get(session.localId) !== session) return null;
+  var group = store.groupForMember(session.localId);
+  var roles = group && group.pair ? splitRoles.resolveLiveRoles(sm, group) : null;
+  if (!roles) return null;
+  roles.worker = roles.workers.length === 1 ? roles.workers[0] :
+    roles.workers.find(function (worker) { return worker === session; }) || null;
+  return roles;
+}
+
+module.exports = { resolveGroupTarget: resolveGroupTarget, rolesFor: rolesFor };

package/lib/session-pair-turn-control.js

@@ -10,6 +10,7 @@ var MAX_CREATIONS_PER_TURN = 2;
 var MAX_REPLACEMENTS_PER_TURN = 1;
 var MAX_FAILED_REPLACEMENT_ATTEMPTS_PER_TURN = 2;
 var MAX_OPERATION_ID_CHARS = 120;
+var splitRoles = require("./session-split-group-roles");
 
 function attachPairTurnControl(ctx) {
   var sm = ctx.sm;
@@ -22,6 +23,7 @@ function attachPairTurnControl(ctx) {
         humanStopped: false,
         stoppedAt: null,
         stoppedWorkerId: null,
+        stoppedWorkerIds: [],
         creations: 0,
         replacements: 0,
         failedReplacementAttempts: 0,
@@ -42,11 +44,11 @@ function attachPairTurnControl(ctx) {
     if (!liveSession(session)) return null;
     var group = store.groupForMember(session.localId);
     if (!group || !group.pair) return null;
-    var driver = sm.sessions.get(group.pair.driverId);
-    var worker = sm.sessions.get(group.pair.workerId);
-    if (!liveSession(driver) || !liveSession(worker)) return null;
-    if ((driver.ownerId || null) !== (worker.ownerId || null)) return null;
-    return { group: group, driver: driver, worker: worker };
+    var roles = splitRoles.resolveLiveRoles(sm, group);
+    if (!roles) return null;
+    roles.worker = roles.workers.length === 1 ? roles.workers[0] :
+      roles.workers.find(function (worker) { return worker === session; }) || null;
+    return roles;
   }
 
   function beginHumanTurn(session) {
@@ -59,6 +61,7 @@ function attachPairTurnControl(ctx) {
     state.humanStopped = false;
     state.stoppedAt = null;
     state.stoppedWorkerId = null;
+    state.stoppedWorkerIds = [];
     state.creations = 0;
     state.replacements = 0;
     state.failedReplacementAttempts = 0;
@@ -72,7 +75,8 @@ function attachPairTurnControl(ctx) {
     var state = stateFor(roles.driver);
     state.humanStopped = true;
     state.stoppedAt = Date.now();
-    state.stoppedWorkerId = roles.worker.localId;
+    state.stoppedWorkerId = roles.worker ? roles.worker.localId : null;
+    state.stoppedWorkerIds = roles.workers.map(function (worker) { return worker.localId; });
     return roles;
   }
 
@@ -147,6 +151,7 @@ function attachPairTurnControl(ctx) {
       humanStopped: state.humanStopped,
       stoppedAt: state.stoppedAt,
       stoppedWorkerId: state.stoppedWorkerId,
+      stoppedWorkerIds: state.stoppedWorkerIds.slice(),
       turnSerial: state.serial,
       creationsThisTurn: state.creations,
       replacementsThisTurn: state.replacements,

package/lib/session-split-group-anchors.js

@@ -2,6 +2,8 @@ function value(input) {
   return typeof input === "string" && input ? input : null;
 }
 
+var splitRoles = require("./session-split-group-roles");
+
 function pairFor(session, previousCli, previousOrigin) {
   return {
     cli: value(session && session.cliSessionId) || value(previousCli),
@@ -9,16 +11,87 @@ function pairFor(session, previousCli, previousOrigin) {
   };
 }
 
+function versionedAnchor(session) {
+  var cli = value(session && session.cliSessionId);
+  var origin = value(session && session.sessionOriginId);
+  if (!cli && !origin) return null;
+  return { cli: cli, origin: origin };
+}
+
+function versionedPairAnchors(group, sessions) {
+  var normalized = splitRoles.normalizePair(group && group.pair, group && group.members);
+  if (!normalized.ok || normalized.kind !== "versioned") return null;
+  var driver = versionedAnchor(sessions.get(group.pair.driverId));
+  if (!driver) return null;
+  var workers = [];
+  for (var i = 0; i < normalized.workerIds.length; i++) {
+    var worker = versionedAnchor(sessions.get(normalized.workerIds[i]));
+    if (!worker) return null;
+    workers.push(worker);
+  }
+  return { version: 2, driver: driver, workers: workers };
+}
+
+function versionedMemberAnchors(group, sessions) {
+  var normalized = splitRoles.normalizePair(group && group.pair, group && group.members);
+  if (!normalized.ok || normalized.kind !== "versioned") return null;
+  var members = [];
+  for (var i = 0; i < group.members.length; i++) {
+    var anchor = versionedAnchor(sessions.get(group.members[i]));
+    if (!anchor) return null;
+    members.push(anchor);
+  }
+  return { version: 2, members: members };
+}
+
+function resolveVersionedPair(sessions, anchors) {
+  if (!anchors || anchors.version !== 2 || !anchors.driver || !Array.isArray(anchors.workers) ||
+      (anchors.workers.length !== 1 && anchors.workers.length !== 2)) return null;
+  var driver = findSession(sessions, anchors.driver.cli, anchors.driver.origin);
+  if (!driver) return null;
+  var workers = [];
+  for (var i = 0; i < anchors.workers.length; i++) {
+    var workerAnchor = anchors.workers[i];
+    if (!workerAnchor || (!value(workerAnchor.cli) && !value(workerAnchor.origin))) return null;
+    var worker = workerAnchor && findSession(sessions, workerAnchor.cli, workerAnchor.origin);
+    if (!worker || workers.indexOf(worker) !== -1 || worker === driver) return null;
+    workers.push(worker);
+  }
+  return { driver: driver, workers: workers };
+}
+
+function resolveVersionedMembers(sessions, anchors) {
+  if (!anchors || anchors.version !== 2 || !Array.isArray(anchors.members) ||
+      (anchors.members.length !== 2 && anchors.members.length !== 3)) return null;
+  var resolved = [];
+  for (var i = 0; i < anchors.members.length; i++) {
+    var anchor = anchors.members[i];
+    if (!anchor || (!value(anchor.cli) && !value(anchor.origin))) return null;
+    var session = anchor && findSession(sessions, anchor.cli, anchor.origin);
+    if (!session || resolved.indexOf(session) !== -1) return null;
+    resolved.push(session);
+  }
+  return resolved;
+}
+
 function memberAnchors(group, sessions) {
-  var previousCli = Array.isArray(group.memberCliIds) ? group.memberCliIds : [null, null];
-  var previousOrigin = Array.isArray(group.memberOriginIds) ? group.memberOriginIds : [null, null];
-  var left = pairFor(sessions.get(group.members[0]), previousCli[0], previousOrigin[0]);
-  var right = pairFor(sessions.get(group.members[1]), previousCli[1], previousOrigin[1]);
-  return { cli: [left.cli, right.cli], origin: [left.origin, right.origin] };
+  var normalized = splitRoles.normalizePair(group && group.pair, group && group.members);
+  if (!normalized.ok) return null;
+  if (normalized.kind === "versioned") return versionedMemberAnchors(group, sessions);
+  var previousCli = Array.isArray(group.memberCliIds) ? group.memberCliIds : [];
+  var previousOrigin = Array.isArray(group.memberOriginIds) ? group.memberOriginIds : [];
+  var cli = [], origin = [];
+  for (var i = 0; i < group.members.length; i++) {
+    var anchor = pairFor(sessions.get(group.members[i]), previousCli[i], previousOrigin[i]);
+    cli.push(anchor.cli); origin.push(anchor.origin);
+  }
+  return { cli: cli, origin: origin };
 }
 
 function pairAnchors(group, sessions) {
-  if (!group.pair) return null;
+  var normalized = splitRoles.normalizePair(group && group.pair, group && group.members);
+  if (!normalized.ok || normalized.kind === "adhoc") return null;
+  if (normalized.kind === "versioned") return versionedPairAnchors(group, sessions);
   var previousCli = Array.isArray(group.pairCliIds) ? group.pairCliIds : [null, null];
   var previousOrigin = Array.isArray(group.pairOriginIds) ? group.pairOriginIds : [null, null];
   var driver = pairFor(sessions.get(group.pair.driverId), previousCli[0], previousOrigin[0]);
@@ -41,4 +114,13 @@ function findSession(sessions, cliId, originId) {
   return ambiguous ? null : found;
 }
 
-module.exports = { findSession: findSession, memberAnchors: memberAnchors, pairAnchors: pairAnchors };
+module.exports = {
+  findSession: findSession,
+  memberAnchors: memberAnchors,
+  pairAnchors: pairAnchors,
+  resolveVersionedMembers: resolveVersionedMembers,
+  resolveVersionedPair: resolveVersionedPair,
+  versionedAnchor: versionedAnchor,
+  versionedMemberAnchors: versionedMemberAnchors,
+  versionedPairAnchors: versionedPairAnchors,
+};

package/lib/session-split-group-persistence.js

@@ -0,0 +1,136 @@
+var fs = require("fs");
+var path = require("path");
+var anchors = require("./session-split-group-anchors");
+var roles = require("./session-split-group-roles");
+
+var ANCHOR_KEYS = ["memberCliIds", "memberOriginIds", "pairCliIds", "pairOriginIds", "memberAnchors", "pairAnchors"];
+
+function attachPersistence(opts) {
+  var sessions = opts.sessions;
+  var groupsFile = path.join(opts.sessionsDir, "split-groups.json");
+  var preserved = [];
+
+  function anchorPair(group) {
+    if (!group.pair) return;
+    var pair = anchors.pairAnchors(group, sessions);
+    if (!pair) return;
+    if (pair.version === 2) {
+      group.pairAnchors = pair;
+      delete group.pairCliIds; delete group.pairOriginIds;
+    } else {
+      group.pairCliIds = pair.cli; group.pairOriginIds = pair.origin;
+    }
+  }
+
+  function anchoredClone(group) {
+    var clone = Object.assign({}, group, { members: group.members.slice(),
+      pair: group.pair ? Object.assign({}, group.pair) : undefined });
+    if (clone.pair && Array.isArray(clone.pair.workerIds)) clone.pair.workerIds = clone.pair.workerIds.slice();
+    var member = anchors.memberAnchors(clone, sessions);
+    if (!member) throw new Error("Split group does not have durable session anchors");
+    if (member.version === 2) {
+      clone.memberAnchors = member;
+      delete clone.memberCliIds; delete clone.memberOriginIds;
+    } else {
+      clone.memberCliIds = member.cli; clone.memberOriginIds = member.origin;
+    }
+    anchorPair(clone);
+    return clone;
+  }
+
+  function save(groups) {
+    var saved = groups.map(anchoredClone);
+    var serialized = JSON.stringify(saved.concat(preserved), null, 2) + "\n";
+    if (typeof opts.persistGroups === "function") {
+      if (opts.persistGroups(groupsFile, serialized) === false) throw new Error("Split group persistence returned false");
+    } else {
+      var tmp = groupsFile + ".tmp." + process.pid;
+      fs.mkdirSync(opts.sessionsDir, { recursive: true });
+      fs.writeFileSync(tmp, serialized);
+      if (process.platform !== "win32") try { fs.chmodSync(tmp, 0o600); } catch (e) {}
+      fs.renameSync(tmp, groupsFile);
+    }
+    for (var i = 0; i < groups.length; i++) {
+      (function (live, stored) {
+        ANCHOR_KEYS.forEach(function (key) {
+          if (Object.prototype.hasOwnProperty.call(stored, key)) live[key] = stored[key];
+          else delete live[key];
+        });
+      })(groups[i], saved[i]);
+    }
+  }
+
+  function resolveVersioned(group, normalized) {
+    if (typeof group.id !== "string" || !group.id) return false;
+    var members = anchors.resolveVersionedMembers(sessions, group.memberAnchors);
+    var pair = anchors.resolveVersionedPair(sessions, group.pairAnchors);
+    if (!members || !pair) return false;
+    var memberIds = members.map(function (session) { return session.localId; });
+    var workerIds = pair.workers.map(function (session) { return session.localId; });
+    if (memberIds.length !== group.members.length || workerIds.length !== normalized.workerIds.length) return false;
+    var nextPair = { version: 2, driverId: pair.driver.localId, workerIds: workerIds };
+    var nextRoles = roles.normalizePair(nextPair, memberIds);
+    if (!nextRoles.ok || nextRoles.kind !== "versioned") return false;
+    var changed = group.members.join(",") !== memberIds.join(",") ||
+      group.pair.driverId !== pair.driver.localId || group.pair.workerIds.join(",") !== workerIds.join(",");
+    group.members = memberIds;
+    group.pair = nextPair;
+    return { changed: changed };
+  }
+
+  function resolveLegacy(group) {
+    var changed = false;
+    if (Array.isArray(group.memberCliIds) || Array.isArray(group.memberOriginIds)) {
+      var cli = Array.isArray(group.memberCliIds) ? group.memberCliIds : [null, null];
+      var origin = Array.isArray(group.memberOriginIds) ? group.memberOriginIds : [null, null];
+      var left = anchors.findSession(sessions, cli[0], origin[0]);
+      var right = anchors.findSession(sessions, cli[1], origin[1]);
+      if (!left || !right || left === right) return false;
+      if (group.members[0] !== left.localId || group.members[1] !== right.localId) {
+        group.members = [left.localId, right.localId]; changed = true;
+      }
+    }
+    if (group.pair && (Array.isArray(group.pairCliIds) || Array.isArray(group.pairOriginIds))) {
+      var pairCli = Array.isArray(group.pairCliIds) ? group.pairCliIds : [null, null];
+      var pairOrigin = Array.isArray(group.pairOriginIds) ? group.pairOriginIds : [null, null];
+      var driver = anchors.findSession(sessions, pairCli[0], pairOrigin[0]);
+      var worker = anchors.findSession(sessions, pairCli[1], pairOrigin[1]);
+      if (driver && worker && (group.pair.driverId !== driver.localId || group.pair.workerId !== worker.localId)) {
+        group.pair.driverId = driver.localId; group.pair.workerId = worker.localId; changed = true;
+      }
+    }
+    return roles.validateStoredGroup(group, sessions) ? { changed: changed } : false;
+  }
+
+  function load() {
+    var loaded = [], rewrite = false, claimed = {};
+    preserved = [];
+    try { loaded = JSON.parse(fs.readFileSync(groupsFile, "utf8")); if (!Array.isArray(loaded)) loaded = []; }
+    catch (error) { if (error.code !== "ENOENT") rewrite = true; }
+    var groups = loaded.filter(function (group) {
+      var normalized = group && roles.normalizePair(group.pair, group.members);
+      if (!normalized || !normalized.ok) {
+        if (group && roles.isUnsupportedPair(group.pair)) preserved.push(group);
+        return false;
+      }
+      var versioned = !!(normalized && normalized.ok && normalized.kind === "versioned");
+      if (versioned && !opts.versionedEnabled) { preserved.push(group); return false; }
+      var resolved = versioned ? resolveVersioned(group, normalized) : resolveLegacy(group);
+      if (!resolved) {
+        if (versioned || group && roles.isUnsupportedPair(group.pair)) preserved.push(group);
+        return false;
+      }
+      if (resolved.changed) rewrite = true;
+      for (var i = 0; i < group.members.length; i++) if (claimed[group.members[i]]) return false;
+      for (var j = 0; j < group.members.length; j++) claimed[group.members[j]] = true;
+      return true;
+    });
+    if (groups.length + preserved.length !== loaded.length) rewrite = true;
+    if (rewrite) save(groups);
+    return groups;
+  }
+
+  return { load: load, save: save };
+}
+
+module.exports = { attachPersistence: attachPersistence };