clay-server 4.0.0-beta.11 → 4.0.0-beta.13

package/lib/public/modules/project-logs.js

@@ -15,15 +15,10 @@ import { getWs } from './ws-ref.js';
 import { refreshIcons } from './icons.js';
 import { showToast } from './utils.js';
 import { closeScheduler } from './scheduler.js';
-import { hideNotes } from './sticky-notes.js';
 import { closeNotesBrowser } from './sticky-notes-browser.js';
 import { closeFileViewer } from './filebrowser.js';
 import { closeTerminal } from './terminal.js';
 import { renderFilter, renderList, renderDetail } from './project-logs-render.js';
-import {
-  initProjectLogsAmbient, bindPanelHover, noteCanonicalUpdate,
-  acknowledgeUpdates, resetAmbient, syncAmbient, hidePreview, pinFromPreview
-} from './project-logs-ambient.js';
 
 var panel = null;
 var listEl = null;
@@ -34,6 +29,37 @@ var backBtn = null;
 var searchTimer = null;
 var requestCounter = 0;
 
+function syncUnreadBadge() {
+  var button = document.getElementById("project-logs-btn");
+  if (!button) return;
+  var unread = store.get('projectLogsUnread') || 0;
+  button.classList.toggle("project-logs-unread", unread > 0);
+  var badge = document.getElementById("project-logs-count");
+  if (!badge) return;
+  badge.textContent = unread > 0 ? String(unread) : "";
+  badge.classList.toggle("hidden", unread < 1);
+}
+
+function acknowledgeUpdates() {
+  if (!store.get('projectLogsUnread')) return;
+  store.set({ projectLogsUnread: 0 });
+  syncUnreadBadge();
+}
+
+function noteCanonicalUpdate(msg) {
+  if (!msg || !msg.ref || !msg.revision) return false;
+  var seen = store.get('projectLogsSeenRevisions') || {};
+  if (seen[msg.ref] >= msg.revision) return false;
+  var next = Object.assign({}, seen);
+  next[msg.ref] = msg.revision;
+  store.set({
+    projectLogsSeenRevisions: next,
+    projectLogsUnread: store.get('projectLogsOpen') ? 0 : (store.get('projectLogsUnread') || 0) + 1,
+  });
+  syncUnreadBadge();
+  return true;
+}
+
 function nextRequestId(prefix) {
   requestCounter += 1;
   return prefix + "-" + Date.now() + "-" + requestCounter;
@@ -80,11 +106,7 @@ function ensurePanel() {
   backBtn = panel.querySelector("#project-logs-back");
 
   panel.querySelector("#project-logs-close").addEventListener("click", closeProjectLogs);
-  backBtn.addEventListener("click", function () { pinOnInteraction(); showList(); });
-  // Any meaningful interaction inside a preview commits to it.
-  searchEl.addEventListener("focus", pinOnInteraction);
-  panel.addEventListener("pointerdown", pinOnInteraction);
-  bindPanelHover(panel);
+  backBtn.addEventListener("click", showList);
   panel.querySelector("#project-logs-wide").addEventListener("click", function () {
     applyWindowState(!store.get('projectLogsWide'), store.get('projectLogsFullscreen'));
   });
@@ -98,24 +120,6 @@ function ensurePanel() {
   refreshIcons();
 }
 
-// A preview reveals the pane without committing to it: no acknowledgement, no
-// open state, and no list refresh beyond what is already on screen.
-function revealPreview() {
-  ensurePanel();
-  if (!panel) return;
-  panel.classList.remove("hidden");
-  panel.classList.add("project-logs-previewing");
-  applyWindowState(store.get('projectLogsWide'), false);
-  if (!store.get('projectLogsEntries') || !store.get('projectLogsEntries').length) requestList();
-}
-
-function hideRevealedPreview() {
-  if (!panel) return;
-  panel.classList.remove("project-logs-previewing");
-  if (store.get('projectLogsOpen')) return;
-  panel.classList.add("hidden");
-}
-
 // Width and fullscreen are transient view state, so they live in the store like
 // every other mutable UI value. `panel-fullscreen` is the shared class the
 // document viewer and terminal already use.
@@ -147,13 +151,6 @@ function showList() {
   listEl.scrollTop = store.get('projectLogsListScroll') || 0;
 }
 
-// A preview becomes a real open the moment the user does something with it.
-function pinOnInteraction() {
-  if (store.get('projectLogsOpen')) return;
-  if (!store.get('projectLogsPreview')) return;
-  pinFromPreview();
-}
-
 function showDetail(entry) {
   if (!panel || !entry) return;
   store.set({ projectLogsListScroll: listEl.scrollTop, projectLogsView: "detail", projectLogsSelectedRef: entry.ref });
@@ -170,12 +167,21 @@ function showDetail(entry) {
 function requestList() {
   var requestId = nextRequestId("list-logs");
   store.set({ projectLogsListRequestId: requestId });
-  send({
+  if (listEl && !store.get('projectLogsEntries').length) {
+    listEl.setAttribute("aria-busy", "true");
+    renderList(listEl, [], requestEntry, "Loading the project ledger...");
+  }
+  if (!send({
     type: "project_logs_list",
     requestId: requestId,
     query: searchEl ? searchEl.value.trim() : "",
     category: store.get('projectLogsCategory') || "",
-  });
+  })) {
+    if (listEl) {
+      listEl.removeAttribute("aria-busy");
+      renderList(listEl, [], requestEntry, "Logs are unavailable while disconnected.");
+    }
+  }
 }
 
 function requestEntry(ref) {
@@ -185,7 +191,6 @@ function requestEntry(ref) {
 }
 
 function submitComment(ref, body, statusEl, inputEl) {
-  pinOnInteraction();
   var requestId = nextRequestId("comment-log");
   store.set({ projectLogsCommentRequestId: requestId, projectLogsCommentInput: inputEl || null });
   if (!send({ type: "project_log_comment", requestId: requestId, ref: ref, body: body })) {
@@ -197,7 +202,6 @@ function submitComment(ref, body, statusEl, inputEl) {
 }
 
 function applyFilter(category) {
-  pinOnInteraction();
   store.set({ projectLogsCategory: category || "" });
   requestList();
 }
@@ -211,18 +215,13 @@ export function initProjectLogs() {
     if (store.get('projectLogsOpen')) closeProjectLogs();
     else openProjectLogs();
   });
-  initProjectLogsAmbient({
-    reveal: revealPreview,
-    hide: hideRevealedPreview,
-    pin: openProjectLogs,
-  });
+  syncUnreadBadge();
   store.subscribe(function (state, previous) {
     if (state.currentSlug === previous.currentSlug) return;
     closeProjectLogs();
     applyWindowState(false, false);
     // A different project must never inherit the previous project's unread
-    // state or animate its updates.
-    resetAmbient();
+    // state.
     store.set({
       projectLogsEntries: [],
       projectLogsSelectedRef: null,
@@ -231,8 +230,11 @@ export function initProjectLogs() {
       projectLogsListScroll: 0,
       projectLogsListRequestId: null,
       projectLogsReadRequestId: null,
-      projectLogsCommentRequestId: null
+      projectLogsCommentRequestId: null,
+      projectLogsUnread: 0,
+      projectLogsSeenRevisions: {}
     });
+    syncUnreadBadge();
   });
 }
 
@@ -243,37 +245,31 @@ export function openProjectLogs() {
   if (!panel) return;
   closeScheduler();
   closeNotesBrowser();
-  hideNotes();
   // Claim the single right workbench slot.
   try { closeFileViewer(); } catch (e) {}
   try { closeTerminal(); } catch (e) {}
   panel.classList.remove("hidden");
-  panel.classList.remove("project-logs-previewing");
   applyWindowState(store.get('projectLogsWide'), false);
   var button = document.getElementById("project-logs-btn");
   if (button) button.classList.add("active");
-  store.set({ projectLogsOpen: true, projectLogsPinned: true, projectLogsPreview: false });
-  // Opening the ledger is the acknowledgement; the ambient cues clear here and
-  // nowhere else.
+  store.set({ projectLogsOpen: true });
+  // Opening through the explicit tool button acknowledges the live badge.
   acknowledgeUpdates();
   showList();
   requestList();
 }
 
 export function closeProjectLogs() {
-  hidePreview();
   if (!store.get('projectLogsOpen')) return;
   if (panel) {
     panel.classList.add("hidden");
-    panel.classList.remove("project-logs-previewing");
   }
   // Fullscreen is always dropped on close so the next open is a bounded pane
   // and never silently hides the conversation.
   applyWindowState(store.get('projectLogsWide'), false);
   var button = document.getElementById("project-logs-btn");
   if (button) button.classList.remove("active");
-  store.set({ projectLogsOpen: false, projectLogsPinned: false });
-  syncAmbient();
+  store.set({ projectLogsOpen: false });
 }
 
 // --- Server messages -----------------------------------------------------
@@ -282,10 +278,13 @@ export function handleProjectLogsState(msg) {
   if (msg.requestId && msg.requestId !== store.get('projectLogsListRequestId')) return;
   store.set({ projectLogsEntries: msg.entries || [] });
   if (!listEl) return;
+  listEl.removeAttribute("aria-busy");
   if (filterEl && Array.isArray(msg.categories)) {
     renderFilter(filterEl, msg.categories, store.get('projectLogsCategory'), applyFilter);
   }
-  renderList(listEl, msg.entries || [], requestEntry);
+  var isFiltered = !!((searchEl && searchEl.value.trim()) || store.get('projectLogsCategory'));
+  renderList(listEl, msg.entries || [], requestEntry,
+    isFiltered ? "No entries match this search or category." : "No logs yet. This project's agent sessions record decisions and work here.");
   if (store.get('projectLogsView') !== "detail") listEl.scrollTop = store.get('projectLogsListScroll') || 0;
 }
 
@@ -309,8 +308,8 @@ export function handleProjectLogCommented(msg) {
   requestList();
 }
 
-// A canonical revision landed. This marks the ambient cues and never opens,
-// focuses, or scrolls anything.
+// A canonical revision landed. This marks the explicit button only; it never
+// opens, reveals, focuses, or scrolls the pane.
 export function handleProjectLogUpdated(msg) {
   noteCanonicalUpdate(msg);
   // Refresh the ledger only when it is already on screen, so the row moves to
@@ -325,5 +324,9 @@ export function handleProjectLogsError(msg) {
     store.get('projectLogsCommentRequestId')
   ];
   if (msg.requestId && pending.indexOf(msg.requestId) === -1) return;
+  if (msg.requestId && msg.requestId === store.get('projectLogsListRequestId') && listEl) {
+    listEl.removeAttribute("aria-busy");
+    renderList(listEl, [], requestEntry, "The ledger could not be loaded. Try opening Logs again.");
+  }
   showToast(msg.message || "Project Logs could not complete the request.", "error");
 }

package/lib/public/modules/split-group-helpers.js

@@ -16,3 +16,11 @@ export function findSplitGroup(groups, memberIds) {
   }
   return null;
 }
+
+export function isConfiguredWorker(groups, sessionId) {
+  var list = groups || [];
+  for (var i = 0; i < list.length; i++) {
+    if (list[i].pair && list[i].pair.workerId === sessionId) return true;
+  }
+  return false;
+}

package/lib/public/modules/split-view.js

@@ -7,7 +7,7 @@ import { iconHtml, refreshIcons } from './icons.js';
 import { detachTuiView } from './session-tui-view.js';
 import { formatTokens } from './app-panels.js';
 import { VENDOR_AVATARS, VENDOR_NAMES } from './app-rendering.js';
-import { groupedSessionIds, findSplitGroup } from './split-group-helpers.js';
+import { groupedSessionIds, findSplitGroup, isConfiguredWorker } from './split-group-helpers.js';
 import { showConfirm } from './app-misc.js';
 import { syncPairChrome } from './split-pair-ui.js';
 import { presentMarkdownEdit } from './filebrowser.js';
@@ -159,7 +159,10 @@ export function syncPaneTitles() {
 function updatePaneFullAccessButton(button, session) {
   if (!button) return;
   var mode = session && (session.runtimeMode || session.mode || "gui");
-  var visible = !!session && !store.get('skipPermsEnabled') && mode === "gui";
+  var worker = !!session && isConfiguredWorker(store.get('splitGroups'), session.id);
+  // Permission policy belongs to the Driver. A configured Worker inherits it
+  // server-side and must not present a second, misleading control.
+  var visible = !!session && !worker && !store.get('skipPermsEnabled') && mode === "gui";
   var enabled = visible && session.permissionMode === "bypassPermissions";
   button.classList.toggle("hidden", !visible);
   button.classList.toggle("active", enabled);

package/lib/public/modules/tools.js

@@ -203,6 +203,23 @@ export function toolActivityText(name, input) {
   return "Running " + name + "...";
 }
 
+// The sublabel for a call that has finished. `toolActivityText` is written in
+// the present progressive for a call in flight, so re-asserting it after a
+// result has arrived leaves a finished card claiming to still be running —
+// which is how a failed custom tool ended up reading "Running
+// send_to_partner..." beside its own error output.
+//
+// Only ever used where a result exists, so a genuinely in-flight call is never
+// relabelled. A failure states so plainly; a success keeps whatever specific
+// description the activity text produced ("Reading foo.js"), because that still
+// describes the call accurately, and only the generic present-progressive
+// fallback is replaced.
+export function toolTerminalText(name, input, isError) {
+  if (isError) return name + " failed";
+  var activity = toolActivityText(name, input);
+  return activity === "Running " + name + "..." ? name : activity;
+}
+
 function shortPath(p) {
   if (!p) return "";
   var parts = p.split("/");
@@ -2136,9 +2153,12 @@ export function updateToolResult(id, content, isError, images) {
   var tool = tools[id];
   if (!tool) return;
 
+  // Re-render the sublabel from the now-complete input (streaming can have
+  // built it from a partial one), but in its terminal form: a result has
+  // arrived, so this call is no longer running.
   var subtitleText = tool.el.querySelector(".tool-subtitle-text");
   if (subtitleText && tool.input) {
-    subtitleText.textContent = toolActivityText(tool.name, tool.input);
+    subtitleText.textContent = toolTerminalText(tool.name, tool.input, isError);
   }
 
   var resultBlock = document.createElement("div");

package/lib/sdk-bridge.js

@@ -12,6 +12,7 @@ var { createMessageQueue } = require("./sdk-message-queue");
 var { attachMessageProcessor } = require("./sdk-message-processor");
 var homeDebateToolPolicy = require("./home-debate-tool-policy");
 var yoke = require("./yoke");
+var sessionTitlePolicy = require("./session-title-policy");
 
 // Extract serializable tool descriptors from MCP server instances.
 // Used for IPC to worker processes (McpSdkServerConfigWithInstance is not serializable).
@@ -1608,24 +1609,17 @@ function createSDKBridge(opts) {
       sessionToolDefs = sessionToolDefs.concat(yoke.userInput.fallbackToolDefs(sessionUserInputHandler));
     }
 
-    // Derive an explicit session title for fresh queries so the SDK records
-    // it at session creation and skips its own auto-generation. This also
-    // lets us short-circuit autoGenerateTitle below for the common case.
+    // Give fresh queries an immediate provisional label. The visible user
+    // message in history wins over `text`, which may contain an internal
+    // provider wrapper rather than what the person typed.
     // Only applied to NEW sessions (no cliSessionId yet) — when resuming,
     // the SDK ignores Options.title in favor of the persisted title.
     var initialTitle = null;
+    var initialTitleProvisional = false;
     if (!session.cliSessionId && !session.titleManuallySet && !session.titleAutoGenerated) {
-      if (session.title) {
-        // Loop / scheduled / mate-seeded sessions arrive with a title already set.
-        initialTitle = session.title;
-      } else if (typeof text === "string") {
-        // Derive a quick first-line snippet from the user's first message.
-        // Skip if too short to be meaningful — fall back to autoGenerateTitle.
-        var firstLine = text.replace(/\s+/g, " ").trim();
-        if (firstLine.length >= 10) {
-          initialTitle = firstLine.length > 60 ? firstLine.substring(0, 60) : firstLine;
-        }
-      }
+      var initialTitleChoice = sessionTitlePolicy.selectInitialTitle(session, text);
+      initialTitle = initialTitleChoice.title;
+      initialTitleProvisional = initialTitleChoice.provisional;
     }
 
     var queryOpts = {
@@ -1720,16 +1714,16 @@ function createSDKBridge(opts) {
     try {
       handle = await sessionAdapter.createQuery(queryOpts);
       console.log("[sdk-bridge] createQuery returned handle, vendor=" + sessionAdapter.vendor);
-      // SDK accepted the explicit title — adopt it locally so the session
-      // list reflects it immediately and autoGenerateTitle skips this
-      // session (titleAutoGenerated gates re-trigger).
+      // SDK accepted the explicit title. Provisional labels remain eligible
+      // for semantic generation after the first Home exchange (or the normal
+      // project threshold); seeded titles remain fixed.
       if (initialTitle && !session.title) {
         session.title = initialTitle;
-        session.titleAutoGenerated = true;
+        session.titleAutoGenerated = !initialTitleProvisional;
         sm.saveSessionFile(session);
         sm.broadcastSessionList();
       } else if (initialTitle && session.title === initialTitle) {
-        session.titleAutoGenerated = true;
+        session.titleAutoGenerated = !initialTitleProvisional;
         sm.saveSessionFile(session);
       }
     } catch (e) {

package/lib/sdk-message-processor.js

@@ -1,6 +1,7 @@
 var usersModule = require("./users");
 var yoke = require("./yoke");
 var backgroundTaskTiming = require("./background-task-timing");
+var sessionTitlePolicy = require("./session-title-policy");
 
 function attachMessageProcessor(ctx) {
   var sm = ctx.sm;
@@ -23,8 +24,6 @@ function attachMessageProcessor(ctx) {
   var saveImageFile = ctx.saveImageFile;
   var getSessionLinuxUser = ctx.getSessionLinuxUser || function () { return null; };
 
-  var AUTO_TITLE_TURN_THRESHOLD = 2;
-
   function getMateIdForNotification() {
     if (!isMate) return null;
     if (typeof slug === "string" && slug.indexOf("mate-") === 0) {
@@ -625,7 +624,7 @@ function attachMessageProcessor(ctx) {
       sm.broadcastSessionList();
 
       // Auto-generate title after N turns (skip if loop or already auto-generated)
-      if (session.turnCount === AUTO_TITLE_TURN_THRESHOLD
+      if (session.turnCount === sessionTitlePolicy.generationTurn(isMate)
           && !session.titleAutoGenerated
           && !session.titleManuallySet
           && !session.loop

package/lib/server-home-chat.js

@@ -9,6 +9,7 @@ var attachHomeMateCreation = require("./server-home-mate-creation").attachHomeMa
 var attachHomeDebates = require("./server-home-debates").attachHomeDebates, attachHomeClayEntry = require("./server-home-clay-entry").attachHomeClayEntry;
 var homeChatEvents = require("./server-home-chat-events");
 var homeCapsuleCreation = require("./server-home-capsule-creation");
+var sessionTitlePolicy = require("./session-title-policy");
 var historyToHomeChat = homeChatEvents.historyToHomeChat;
 var transformEvent = homeChatEvents.transformEvent;
 function attachHomeChat(deps) {
@@ -84,6 +85,10 @@ function attachHomeChat(deps) {
     var result = [];
     sessionManager.sessions.forEach(function (session) {
       if (!ownsSession(session, userId)) return;
+      if (sessionTitlePolicy.repairLegacySearchTitle(session)
+          && typeof sessionManager.saveSessionFile === "function") {
+        sessionManager.saveSessionFile(session);
+      }
       var cliSessionId = sessionString(session.cliSessionId, 512);
       var createdAt = sessionTimestamp(session.createdAt);
       var lastActivity = sessionTimestamp(session.lastActivity) || createdAt;

package/lib/session-pair-factory.js

@@ -9,6 +9,17 @@
 // 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 eligibility and

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

@@ -17,6 +17,7 @@ function getToolDefs(handlers, options) {
         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 || {}); },
     },
@@ -64,6 +65,7 @@ function getToolDefs(handlers, options) {
           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." },
       }),
       handler: function (args) { return handlers.replace(args || {}); },
     },

package/lib/session-pair-prompts.js

@@ -23,9 +23,9 @@ var DRIVER = [
   "the user and without posting any suggestion or approval card. send_to_partner creates and opens a visible",
   "Split Worker when none exists. replace_partner dissolves the current pair and opens a fresh compact Worker in",
   "one step, optionally delivering the next task with it; the replaced Worker keeps its conversation, so nothing",
-  "is lost. Replacing an actively running Worker requires interrupt true, which stops it first. The human may",
-  "still message or stop the Split Worker directly; treat that intervention as authoritative, and use",
-  "close_partner immediately when they ask to close or dismiss the pane.",
+  "is lost. Replacing an actively running Worker requires interrupt true, which stops it first. 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.",
   "",
   "Choose the Worker vendor, model, and effort for the task from what is actually installed and offered; an",
   "unavailable choice is refused rather than silently substituted. After a Worker generation finishes or is",

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

package/lib/session-split-groups.js

@@ -280,7 +280,10 @@ function attachSplitGroups(ctx) {
   });
 
   function sendState(ws) {
-    if (!ws || ws._clayPane) return;
+    if (!ws) return;
+    // Pane clients need the same owner-scoped pair roles as the parent shell.
+    // The Worker composer lock resolves its role from this projection; hiding
+    // the projection from panes leaves a configured Worker looking editable.
     ctx.sendTo(ws, { type: "split_groups", groups: store.listFor(ws) });
   }