clay-server 4.0.0-beta.9 → 4.0.0

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 };

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

@@ -2,26 +2,27 @@
 
 var buildShape = require("./session-spawn-mcp-server").buildShape;
 
-function getToolDefs(handlers) {
-  return [
+// `options.lifecycle` adds the autonomous management tools. They are omitted
+// for a plain side-by-side split, which has no Driver role to exercise them.
+function getToolDefs(handlers, options) {
+  var lifecycle = !!(options && options.lifecycle);
+  var defs = [
     {
       name: "send_to_partner",
-      description: "Delegate one concrete task to the visible Split Worker. If this session has no pair yet, Clay creates a real Split Worker session and opens it visibly in the right pane before starting the task. 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.",
+      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." },
         timeoutSeconds: { type: "number", description: "Maximum wait in seconds, from 1 to 900. Defaults to 300." },
-        workerVendor: { type: "string", description: "Optional Split Worker vendor to use only when creating a new pair. Defaults to a suitable installed vendor." },
-        workerModel: { type: "string", description: "Optional Split Worker model to use only when creating a new pair." },
-        workerEffort: { type: "string", description: "Optional Split Worker reasoning effort to use only when creating a new pair." },
+        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." },
       }, ["message"]),
       handler: function (args) { return handlers.send(args || {}); },
     },
     {
       name: "read_partner",
-      description: "Read the partner's current status and recent conversation turns. 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 this for an interim check after a non-waiting delegation or timeout; completed results are pushed automatically.",
       inputSchema: buildShape({
-        lastTurns: { type: "number", description: "Number of recent user-message-delimited turns, from 1 to 5. Defaults to 1." },
+        lastTurns: { type: "number", description: "Number of recent user-message-delimited turns, from 0 to 5. Use 0 for status only. Defaults to 1." },
       }),
       handler: function (args) { return handlers.read(args || {}); },
     },
@@ -38,6 +39,43 @@ function getToolDefs(handlers) {
       handler: function (args) { return handlers.close(args || {}); },
     },
   ];
+  if (!lifecycle) return defs;
+  return defs.concat([
+    {
+      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({}),
+      handler: function (args) { return handlers.status(args || {}); },
+    },
+    {
+      name: "replace_partner",
+      description: "Propose replacing the current Split Worker with a fresh runtime. This non-mutating call shows a user-controlled vendor, model, and effort card. Only acceptance performs the transactional replacement and delegates the supplied task once; decline keeps the existing pair and resumes the Driver. The previous Worker's conversation remains browsable. An active Worker requires interrupt true.",
+      inputSchema: buildShape({
+        interrupt: { type: "boolean", description: "Stop the Worker first if it is mid-turn or holding a delegated task. Required to replace an active Worker." },
+        message: { type: "string", description: "Task to deliver exactly once after the user accepts the replacement." },
+        workerVendor: { type: "string", description: "Optional vendor for the new Worker. Must be installed and available." },
+        workerModel: { type: "string", description: "Optional model for the new Worker. Must be offered by that vendor." },
+        workerEffort: { type: "string", description: "Optional reasoning effort for the new Worker." },
+        recommendationRationale: { type: "string", description: "Concise Driver-authored explanation of why the recommended replacement vendor, model, and effort fit the next task." },
+        evaluation: {
+          type: "object",
+          description: "Optional bounded assessment of the Worker being replaced, recorded against that exact generation.",
+        },
+        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." },
+      }, ["message", "recommendationRationale"]),
+      handler: function (args) { return handlers.replace(args || {}); },
+    },
+    {
+      name: "record_partner_evaluation",
+      description: "Record a bounded assessment of one Split Worker generation so your later model choices can use observed outcomes instead of re-reading transcripts. Records your judgement alongside the objective signals Clay already measured (turns, errors, interruption, context used). This is scoped to your own pair and forms no global model ranking.",
+      inputSchema: buildShape({
+        outcome: { type: "string", 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." },
+      }, ["outcome"]),
+      handler: function (args) { return handlers.evaluate(args || {}); },
+    },
+  ]);
 }
 
 module.exports = { getToolDefs: getToolDefs };

package/lib/session-pair-prompts.js

@@ -0,0 +1,79 @@
+// Driver-facing system prompt text for the visible Driver/Split Worker pair.
+//
+// Pure data, extracted from project-session-pair.js so that module stays under
+// the size limit and so the guidance can be reviewed as prose.
+
+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.",
+].join(" ").replace(/ {2,}/g, " ");
+
+var DRIVER_CORE = [
+  "You are the Driver of a visible Driver/Split Worker pair, and you manage that Split Worker yourself.",
+  "The tools send_to_partner, read_partner, partner_status, replace_partner, interrupt_partner, close_partner,",
+  "and record_partner_evaluation are provided directly to you.",
+  "",
+  "Reuse the existing Split Worker",
+  "only when its accumulated context genuinely helps the next task; when it is context-bloated, stale, or",
+  "working on something unrelated, replace it instead of carrying that cost forward. Call partner_status to",
+  "decide: it reports context tokens used and the ratio of its window, current activity, vendor/model/effort,",
+  "history size and idle time, whether replacing is safe right now, and the results you recorded for earlier",
+  "Worker generations. It returns no transcript, so it is cheap to consult. Never tell the user that you will",
+  "reuse the current Worker before checking partner_status. If you previously expected reuse but the status leads",
+  "you to replace it, explicitly say that the decision changed and give the reason.",
+  "",
+  "Use send_to_partner seamlessly for follow-up work in the existing pair. Runtime creation and replacement are",
+  "recorded through a configuration card before anything mutates. replace_partner always posts that card. When",
+  "this Driver is in full-access mode, Clay may auto-accept your exact server-validated recommendation; otherwise",
+  "the selected vendor, model, and effort remain pending until the user explicitly accepts them.",
+  "The replaced Worker keeps its conversation, so nothing is lost. Replacing an actively running Worker requires",
+  "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.",
+  "",
+  "Recommend a Worker vendor, model, and effort from what is actually installed and offered, and include a concise",
+  "rationale explaining why all three fit the task. The card remains visible as an audit trail even when full access",
+  "auto-accepts it; an unavailable choice is never auto-accepted. After a Worker generation finishes or is",
+  "replaced, call record_partner_evaluation with succeeded, partial, failed, or abandoned and a short reason.",
+  "Clay stores that against that exact generation alongside what it measured itself, and partner_status hands it",
+  "back, so your next model choice can use observed results instead of guesswork. This is your own record for",
+  "this pair, not a general ranking of models.",
+  "",
+  "Internal Sub-agents are a distinct execution mechanism, not a lexical category; use them only when the user",
+  "clearly intends internal or background parallel delegation rather than the visible paired session. When",
+  "ambiguous and a visible pair exists, prefer the visible Split Worker. If 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;",
+  "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.",
+].join(" ").replace(/ {2,}/g, " ");
+
+var DRIVER = DRIVER_CORE + " " + DRIVER_DELEGATION;
+
+var UNPAIRED = [
+  "Infer the user's intended target from conversational and UI context. References to a user-visible paired or",
+  "split pane, its session, its activity or status, or a collaborator the user wants opened resolve to Clay's",
+  "Split Worker and its partner tools. Internal Sub-agents are a distinct execution mechanism, not a lexical",
+  "category; use them only when the user clearly intends internal or background parallel delegation rather than a",
+  "visible paired session. When ambiguity would materially change where work runs, ask a concise clarification",
+  "instead of guessing. Treat implementation as heavy when it spans multiple modules, crosses client/server/data",
+  "boundaries, requires a migration, or contains independent investigation and execution. In those cases, call",
+  "propose_worker before substantial execution unless the user explicitly asks you to work directly or the work",
+  "must remain sequential in this session. Your own capability is not a reason to skip delegation: preserve the",
+  "Driver for decomposition, runtime selection, judgment, review, and integration. Give an exact runtime recommendation",
+  "and concise rationale. Clay records and shows the card before the visible pair is accepted or auto-accepted. Do not use a background",
+  "Sub-agent as a substitute for a visible Split Worker.",
+].join(" ").replace(/ {2,}/g, " ");
+
+module.exports = {
+  DRIVER: DRIVER,
+  DRIVER_CORE: DRIVER_CORE,
+  DRIVER_DELEGATION: DRIVER_DELEGATION,
+  UNPAIRED: UNPAIRED,
+};

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

@@ -0,0 +1,153 @@
+// Per-human-turn safety policy for Driver/Split Worker orchestration.
+//
+// A human Stop is a cancellation barrier, not merely an AbortController
+// signal. It blocks delegation and Worker replacement until the next ordinary
+// human message reaches the Driver. Internal result and permission messages do
+// not clear it. Creation budgets and operation ids also make retries bounded
+// and idempotent even when no Stop occurred.
+
+var MAX_CREATIONS_PER_TURN = 2;
+var MAX_REPLACEMENTS_PER_TURN = 1;
+var MAX_OPERATION_ID_CHARS = 120;
+
+function attachPairTurnControl(ctx) {
+  var sm = ctx.sm;
+  var store = ctx.splitStore;
+
+  function stateFor(driver) {
+    if (!driver._pairTurnControl) {
+      driver._pairTurnControl = {
+        serial: 0,
+        humanStopped: false,
+        stoppedAt: null,
+        stoppedWorkerId: null,
+        creations: 0,
+        replacements: 0,
+        operations: Object.create(null),
+      };
+    }
+    return driver._pairTurnControl;
+  }
+
+  function liveSession(session) {
+    return !!(session && sm.sessions.get(session.localId) === session);
+  }
+
+  function rolesFor(session) {
+    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 };
+  }
+
+  function beginHumanTurn(session) {
+    if (!liveSession(session)) return false;
+    var roles = rolesFor(session);
+    var driver = roles ? roles.driver : session;
+    if (roles && roles.driver !== session) return false;
+    var state = stateFor(driver);
+    state.serial += 1;
+    state.humanStopped = false;
+    state.stoppedAt = null;
+    state.stoppedWorkerId = null;
+    state.creations = 0;
+    state.replacements = 0;
+    state.operations = Object.create(null);
+    return true;
+  }
+
+  function markHumanStop(session) {
+    var roles = rolesFor(session);
+    if (!roles) return null;
+    var state = stateFor(roles.driver);
+    state.humanStopped = true;
+    state.stoppedAt = Date.now();
+    state.stoppedWorkerId = roles.worker.localId;
+    return roles;
+  }
+
+  function blockedReason(driver) {
+    if (!liveSession(driver)) return "this Driver session is no longer live";
+    var state = stateFor(driver);
+    if (!state.humanStopped) return null;
+    return "the human stopped this Split Worker turn; Worker actions are blocked until the human sends a new message to the Driver";
+  }
+
+  function assertWorkerAction(driver) {
+    var reason = blockedReason(driver);
+    if (reason) throw new Error(reason);
+  }
+
+  function reserveCreation(driver, kind) {
+    assertWorkerAction(driver);
+    var state = stateFor(driver);
+    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 (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 };
+  }
+
+  function releaseCreation(ticket) {
+    if (!ticket || !ticket.active || !liveSession(ticket.driver)) return;
+    ticket.active = false;
+    var state = stateFor(ticket.driver);
+    state.creations = Math.max(0, state.creations - 1);
+    if (ticket.kind === "replace") state.replacements = Math.max(0, state.replacements - 1);
+  }
+
+  function operationId(value) {
+    if (typeof value !== "string") return "";
+    var clean = value.trim();
+    if (!clean || clean.length > MAX_OPERATION_ID_CHARS || !/^[A-Za-z0-9._:-]+$/.test(clean)) return "";
+    return clean;
+  }
+
+  function runOperation(driver, kind, rawId, fn) {
+    var id = operationId(rawId);
+    if (!id) return Promise.resolve().then(fn);
+    var state = stateFor(driver);
+    var key = kind + ":" + id;
+    if (state.operations[key]) return state.operations[key];
+    var promise = Promise.resolve().then(fn);
+    state.operations[key] = promise;
+    return promise;
+  }
+
+  function status(driver) {
+    var state = stateFor(driver);
+    return {
+      humanStopped: state.humanStopped,
+      stoppedAt: state.stoppedAt,
+      stoppedWorkerId: state.stoppedWorkerId,
+      turnSerial: state.serial,
+      creationsThisTurn: state.creations,
+      replacementsThisTurn: state.replacements,
+    };
+  }
+
+  return {
+    assertWorkerAction: assertWorkerAction,
+    beginHumanTurn: beginHumanTurn,
+    blockedReason: blockedReason,
+    markHumanStop: markHumanStop,
+    releaseCreation: releaseCreation,
+    reserveCreation: reserveCreation,
+    runOperation: runOperation,
+    status: status,
+  };
+}
+
+module.exports = {
+  MAX_CREATIONS_PER_TURN: MAX_CREATIONS_PER_TURN,
+  MAX_REPLACEMENTS_PER_TURN: MAX_REPLACEMENTS_PER_TURN,
+  attachPairTurnControl: attachPairTurnControl,
+};