clay-server 4.2.0 → 4.3.0-beta.10

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 = [
@@ -55,6 +65,11 @@ var DRIVER_CORE = [
   "interrupt true, which stops it first only after acceptance. A human Stop",
   "is authoritative: do not retry, send more work, or replace the Worker in the same turn. Clay blocks those",
   "actions until the human sends a new Driver message. Use close_partner when they ask to close the pane.",
+  "If replacement fails before a new Worker is created, retry only when the transaction explicitly confirms a safe",
+  "rollback; still respect the failed-attempt cap and the human Stop barrier. If a new Worker was created but its task or transport",
+  "failed, keep that Worker and use send_to_partner for a follow-up; do not replace it again merely because execution",
+  "failed. True replacement quota exhaustion remains bounded and honest, and a human Stop always requires a new",
+  "human message.",
   "A Worker outcome envelope is Worker-reported evidence, not Driver verification. Preserve partial results and",
   "correlate completions to their task and generation; never attach a late old-generation result to a new Worker.",
   "",
@@ -71,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.",
@@ -80,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

@@ -8,7 +8,9 @@
 
 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;
@@ -21,11 +23,16 @@ function attachPairTurnControl(ctx) {
         humanStopped: false,
         stoppedAt: null,
         stoppedWorkerId: null,
+        stoppedWorkerIds: [],
         creations: 0,
         replacements: 0,
+        failedReplacementAttempts: 0,
         operations: Object.create(null),
       };
     }
+    if (!Number.isFinite(driver._pairTurnControl.failedReplacementAttempts)) {
+      driver._pairTurnControl.failedReplacementAttempts = 0;
+    }
     return driver._pairTurnControl;
   }
 
@@ -37,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) {
@@ -54,8 +61,10 @@ function attachPairTurnControl(ctx) {
     state.humanStopped = false;
     state.stoppedAt = null;
     state.stoppedWorkerId = null;
+    state.stoppedWorkerIds = [];
     state.creations = 0;
     state.replacements = 0;
+    state.failedReplacementAttempts = 0;
     state.operations = Object.create(null);
     return true;
   }
@@ -66,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;
   }
 
@@ -88,20 +98,28 @@ function attachPairTurnControl(ctx) {
     if (kind === "replace" && state.replacements >= MAX_REPLACEMENTS_PER_TURN) {
       throw new Error("the Split Worker replacement limit for this human turn has been reached; wait for a new human message before replacing it again");
     }
+    if (kind === "replace" && state.failedReplacementAttempts >= MAX_FAILED_REPLACEMENT_ATTEMPTS_PER_TURN) {
+      throw new Error("the Split Worker replacement failure limit for this human turn has been reached; wait for a new human message before retrying replacement");
+    }
     if (state.creations >= MAX_CREATIONS_PER_TURN) {
       throw new Error("the Split Worker creation limit for this human turn has been reached; wait for a new human message before creating another Worker");
     }
     state.creations += 1;
     if (kind === "replace") state.replacements += 1;
-    return { driver: driver, kind: kind, active: true };
+    return { driver: driver, kind: kind, turnSerial: state.serial, active: true };
   }
 
   function releaseCreation(ticket) {
-    if (!ticket || !ticket.active || !liveSession(ticket.driver)) return;
+    if (!ticket || !ticket.active) return;
     ticket.active = false;
+    if (!liveSession(ticket.driver)) return;
     var state = stateFor(ticket.driver);
+    if (state.serial !== ticket.turnSerial) return;
     state.creations = Math.max(0, state.creations - 1);
-    if (ticket.kind === "replace") state.replacements = Math.max(0, state.replacements - 1);
+    if (ticket.kind === "replace") {
+      state.replacements = Math.max(0, state.replacements - 1);
+      state.failedReplacementAttempts += 1;
+    }
   }
 
   function operationId(value) {
@@ -133,9 +151,11 @@ 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,
+      failedReplacementAttemptsThisTurn: state.failedReplacementAttempts,
     };
   }
 
@@ -154,5 +174,6 @@ function attachPairTurnControl(ctx) {
 module.exports = {
   MAX_CREATIONS_PER_TURN: MAX_CREATIONS_PER_TURN,
   MAX_REPLACEMENTS_PER_TURN: MAX_REPLACEMENTS_PER_TURN,
+  MAX_FAILED_REPLACEMENT_ATTEMPTS_PER_TURN: MAX_FAILED_REPLACEMENT_ATTEMPTS_PER_TURN,
   attachPairTurnControl: attachPairTurnControl,
 };

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

@@ -0,0 +1,126 @@
+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),
+    origin: value(session && session.sessionOriginId) || value(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 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) {
+  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]);
+  var worker = pairFor(sessions.get(group.pair.workerId), previousCli[1], previousOrigin[1]);
+  return { cli: [driver.cli, worker.cli], origin: [driver.origin, worker.origin] };
+}
+
+function findSession(sessions, cliId, originId) {
+  var cli = value(cliId);
+  var origin = value(originId);
+  if (!cli && !origin) return null;
+  var found = null;
+  var ambiguous = false;
+  sessions.forEach(function (session) {
+    if (cli && session.cliSessionId !== cli) return;
+    if (origin && session.sessionOriginId !== origin) return;
+    if (found && found !== session) ambiguous = true;
+    else found = session;
+  });
+  return ambiguous ? null : found;
+}
+
+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 };