clay-server 5.2.0-beta.1 → 5.2.0-beta.10

package/lib/project-notifications.js

@@ -154,6 +154,21 @@ function attachNotifications(ctx) {
     return notifications.length;
   }
 
+  function controlProjection(item) { var value = Object.assign({}, item); delete value.controlRevision; return Object.assign(value, { controlRevision: require('./clay-control-target-projection').digest(value) }); }
+  function visible(ws) {
+    return notifications.filter(function (notification) { return !ctx.canView || ctx.canView(ws, notification); }).map(controlProjection);
+  }
+
+  function publish(payload) {
+    if (!ctx.forEachClient) return broadcastAll(payload);
+    ctx.forEachClient(function (ws) {
+      if (ws.readyState !== 1) return;
+      if (payload.notification && !ctx.canView(ws, payload.notification)) return;
+      var list = visible(ws);
+      ws.send(JSON.stringify(Object.assign({}, payload, { notification: payload.notification ? controlProjection(payload.notification) : undefined, unreadCount: list.length })));
+    });
+  }
+
   // --- Core API ---
 
   function notify(event, data) {
@@ -183,12 +198,13 @@ function attachNotifications(ctx) {
     saveNotifications();
     var payload = {
       type: "notification_created",
-      notification: notif,
+      notification: controlProjection(notif),
       unreadCount: getUnreadCount(),
     };
-    // If targeted at a specific user, deliver only to that user's connections.
-    // Otherwise broadcast to everyone (existing behavior).
-    if (notif.targetUserId && typeof sendToUser === "function") {
+    // Project/session previews are projected for each authenticated viewer.
+    if (ctx.forEachClient) {
+      publish(payload);
+    } else if (notif.targetUserId && typeof sendToUser === "function") {
       sendToUser(notif.targetUserId, payload);
     } else {
       broadcastAll(payload);
@@ -196,12 +212,14 @@ function attachNotifications(ctx) {
     return notif;
   }
 
-  function dismiss(ids) {
+  function dismiss(ids, ws) {
+    var permitted = visible(ws).map(function (notification) { return notification.id; });
+    ids = ids.filter(function (id) { return permitted.indexOf(id) !== -1; });
     var before = notifications.length;
     notifications = notifications.filter(function(n) { return ids.indexOf(n.id) === -1; });
     if (notifications.length !== before) {
       saveNotifications();
-      broadcastAll({
+      publish({
         type: "notification_dismissed",
         ids: ids,
         unreadCount: getUnreadCount(),
@@ -209,12 +227,41 @@ function attachNotifications(ctx) {
     }
   }
 
-  function dismissAll() {
-    if (notifications.length > 0) {
-      notifications = [];
-      saveNotifications();
-      broadcastAll({ type: "notification_dismissed_all", unreadCount: 0 });
-    }
+  function canReadOwned(principal, item) {
+    var owner = principal.userId || null;
+    return (owner ? (item.targetUserId === owner || item.ownerId === owner) && (!item.targetUserId || item.targetUserId === owner) : !item.ownerId && !item.targetUserId) &&
+      (!ctx.canViewPrincipal || ctx.canViewPrincipal(principal, item));
+  }
+  function authorizeOwned(principal, items) {
+    if (items.some(function (item) { return !canReadOwned(principal, item); })) throw new Error('Owned notification access changed.');
+  }
+  function listOwned(principal) {
+    return notifications.filter(function (item) { return canReadOwned(principal, item); }).slice(0, 100).map(function (item) { return JSON.parse(JSON.stringify(controlProjection(item))); });
+  }
+  function inspectOwned(principal, ids) {
+    var owned = listOwned(principal);
+    return ids.map(function (id) {
+      var item = owned.find(function (entry) { return entry.id === id; });
+      if (!item) throw new Error('The exact owned notification is absent or inaccessible.');
+      return item;
+    });
+  }
+  function dismissOwned(principal, ids, revalidate) {
+    revalidate(); inspectOwned(principal, ids);
+    var previous = notifications;
+    notifications = notifications.filter(function (item) { return ids.indexOf(item.id) < 0; });
+    var tmp = NOTIF_FILE + '.tmp';
+    try { fs.writeFileSync(tmp, JSON.stringify(notifications, null, 2)); fs.renameSync(tmp, NOTIF_FILE); }
+    catch (error) { notifications = previous; throw error; }
+    // Use the ordinary per-viewer notification state; no private IDs are broadcast.
+    var published = true;
+    if (ctx.forEachClient) ctx.forEachClient(function (ws) { try { sendConnectionState(ws, function (client, payload) { if (client.readyState === 1) client.send(JSON.stringify(payload)); }); } catch (error) { published = false; } });
+    try { revalidate(); } catch (error) { return { status: 'failed', persisted: true, dismissedIds: ids, error: error.message, retrySafe: false }; }
+    return { status: published ? 'completed' : 'failed', persisted: true, dismissedIds: ids, viewerPublication: published ? 'sent' : 'partial', retrySafe: false };
+  }
+
+  function dismissAll(ws) {
+    dismiss(visible(ws).map(function (notification) { return notification.id; }), ws);
   }
 
   // --- Periodic reminder ---
@@ -222,8 +269,15 @@ function attachNotifications(ctx) {
   function startReminder() {
     if (reminderTimer) return;
     reminderTimer = setInterval(function () {
+      if (ctx.canView && ctx.getUsers && pushModule && pushModule.sendPushToUser) {
+        ctx.getUsers().forEach(function (user) {
+          var count = visible({ _clayUser: user }).length;
+          if (count) pushModule.sendPushToUser(user.id, { type: "reminder", title: "Clay", body: count + " unread notification" + (count > 1 ? "s" : ""), tag: "clay-notif-reminder" });
+        });
+        return;
+      }
       var count = getUnreadCount();
-      if (count > 0 && pushModule) {
+      if (count > 0 && pushModule && !ctx.canView) {
         pushModule.sendPush({
           type: "reminder",
           title: "Clay",
@@ -244,10 +298,11 @@ function attachNotifications(ctx) {
 
   function sendConnectionState(ws, sendTo) {
     if (!sendTo) return;
+    var list = visible(ws);
     sendTo(ws, {
       type: "notifications_state",
-      notifications: notifications,
-      unreadCount: getUnreadCount(),
+      notifications: list,
+      unreadCount: list.length,
     });
   }
 
@@ -255,17 +310,21 @@ function attachNotifications(ctx) {
 
   function handleNotificationMessage(ws, msg) {
     if (msg.type === "notification_dismiss") {
-      dismiss(msg.ids || []);
+      dismiss(msg.ids || [], ws);
       return true;
     }
     if (msg.type === "notification_dismiss_all") {
-      dismissAll();
+      dismissAll(ws);
       return true;
     }
     return false;
   }
 
   return {
+    authorizeOwned: authorizeOwned,
+    listOwned: listOwned,
+    inspectOwned: inspectOwned,
+    dismissOwned: dismissOwned,
     notify: notify,
     getUnreadCount: getUnreadCount,
     sendConnectionState: sendConnectionState,

package/lib/project-ownership.js

@@ -0,0 +1,77 @@
+// Ownership recovery changes project metadata only; session owners stay intact.
+var fs = require("fs");
+var path = require("path");
+
+function isPersonal(project) {
+  return project.isMate === true || /^mate-/.test(project.slug || "");
+}
+
+function verifiedPrivateOwner(project, accounts, resolveIdentity) {
+  var root;
+  var stat;
+  try {
+    root = fs.realpathSync(project.path);
+    if (root !== path.resolve(project.path)) return null;
+    stat = fs.statSync(root);
+  } catch (e) { return null; }
+  var matches = [];
+  var identities = [];
+  for (var i = 0; i < accounts.length; i++) {
+    var account = accounts[i];
+    if (!account.linuxUser) continue;
+    try {
+      var identity = resolveIdentity(account.linuxUser);
+      var home = fs.realpathSync(identity.home);
+      if (!Number.isInteger(identity.uid) || identity.uid < 0 || fs.statSync(home).uid !== identity.uid || home !== path.resolve(identity.home) || home === path.parse(home).root) continue;
+      identities.push({ account: account, uid: identity.uid, home: home });
+    } catch (e) { return null; }
+  }
+  for (var j = 0; j < identities.length; j++) {
+    var candidate = identities[j];
+    var relative = path.relative(candidate.home, root);
+    if (candidate.uid !== stat.uid || relative === ".." || relative.indexOf(".." + path.sep) === 0 || path.isAbsolute(relative)) continue;
+    // A shared UID or overlapping home is never authoritative evidence.
+    var ambiguous = identities.some(function (other) {
+      if (other === candidate) return false;
+      var overlap = path.relative(other.home, root);
+      return other.uid === candidate.uid || (!path.isAbsolute(overlap) && overlap !== ".." && overlap.indexOf(".." + path.sep) !== 0);
+    });
+    if (!ambiguous) matches.push(candidate.account.id);
+  }
+  return matches.length === 1 ? matches[0] : null;
+}
+
+function repair(config, accounts, persist, resolveIdentity) {
+  var next = JSON.parse(JSON.stringify(config));
+  var valid = Object.create(null);
+  accounts.forEach(function (user) { if (typeof user.id === "string" && user.id) valid[user.id] = user; });
+  if (!accounts.length) return config; // Pre-account setup is repaired after bootstrap.
+  var admins = accounts.filter(function (user) { return user.role === "admin" && valid[user.id]; }).sort(function (a, b) { return a.id.localeCompare(b.id); });
+  var preferred = next.ownershipRecoveryAdminId || next.singleUserMigratedUserId;
+  var designated = valid[preferred] && valid[preferred].role === "admin" ? preferred : (admins[0] && admins[0].id);
+  if (designated) next.ownershipRecoveryAdminId = designated;
+  (next.projects || []).forEach(function (project) {
+    if (isPersonal(project) || project.slug.indexOf("--") !== -1) return;
+    if (valid[project.ownerId]) { delete project.ownershipRecovery; return; }
+    var visibility = project.visibility || (next.osUsers ? "private" : "public");
+    var recovered = visibility === "public" ? designated : verifiedPrivateOwner(project, accounts, resolveIdentity);
+    if (recovered) {
+      project.ownerId = recovered;
+      delete project.ownershipRecovery;
+    } else project.ownershipRecovery = "required";
+  });
+  if (JSON.stringify(next) === JSON.stringify(config)) return config;
+  persist(next); // Publish only after atomic persistence succeeds; failures abort boot.
+  return next;
+}
+
+function register(config, project, accounts, persist, resolveIdentity) {
+  var next = JSON.parse(JSON.stringify(config));
+  if (!next.projects) next.projects = [];
+  next.projects.push(project);
+  next = repair(next, accounts, function () {}, resolveIdentity);
+  persist(next);
+  return next;
+}
+
+module.exports = { repair: repair, register: register, verifiedPrivateOwner: verifiedPrivateOwner, isPersonal: isPersonal };

package/lib/project-pair-result-delivery.js

@@ -113,15 +113,26 @@ function attachPairResultDelivery(ctx) {
         if (sdk.pushMessage(caller, message) === true) {
           return accepted(caller, partner, token, attemptId);
         }
-        return retry(caller, partner, token, attemptId, "Driver query rejected the result");
+        // The production bridge clears a stale input on false. Resume in this
+        // attempt instead of spending the bounded retries on a dead handle.
+        if (caller.queryInstance || caller._queryStarting) return retry(caller, partner, token, attemptId, "Driver query rejected the result");
       }
       token._deliveryStartupAttemptId = attemptId;
       var beforePush = function () { return token._deliveryStartupAttemptId === attemptId && currentAttempt(caller, partner, token, attemptId); };
       var onAccepted = function () { accepted(caller, partner, token, attemptId); };
       var timeoutMs = Number(ctx.acceptanceTimeoutMs || DEFAULT_ACCEPTANCE_TIMEOUT_MS);
-      token._deliveryTimer = { attemptId: attemptId, timer: setTimeout(function () {
+      function acceptanceTimeout() {
+        if (!currentAttempt(caller, partner, token, attemptId)) return;
+        // A known, cancellable provider admission wait has not sent input.
+        // Keep the correlated completion eligible until admission or Stop.
+        if (caller._queryStarting && Number(caller._providerRecoveryWaiting) > 0
+            && caller._providerRecoveryWaiting === caller._sdkQueryGeneration) {
+          token._deliveryTimer = { attemptId: attemptId, timer: setTimeout(acceptanceTimeout, timeoutMs) };
+          return;
+        }
         uncertain(caller, partner, token, attemptId, "delivery acceptance timed out");
-      }, timeoutMs) };
+      }
+      token._deliveryTimer = { attemptId: attemptId, timer: setTimeout(acceptanceTimeout, timeoutMs) };
       var startup = sdk.startQuery(caller, message, undefined, ctx.getLinuxUserForSession(caller), beforePush, onAccepted);
       Promise.resolve(startup).then(function (result) {
         if (!currentAttempt(caller, partner, token, attemptId)) return;

package/lib/project-pair-usage.js

@@ -16,16 +16,14 @@ function contextStatus(session) {
   var used = null;
   var window = null;
   var source = "unavailable";
+  var measurement = "unavailable";
   if (snapshot && typeof snapshot === "object") {
-    if (session.vendor === "claude") {
-      used = firstNumber(snapshot.totalTokens);
-      window = firstNumber(snapshot.maxTokens);
-      if (used !== null || window !== null) source = "claude_sdk_context_usage";
-    } else {
-      used = firstNumber(snapshot.input_tokens);
-      window = firstNumber(snapshot.contextWindow);
-      if (used !== null || window !== null) source = "adapter_context_usage";
-    }
+    var current = require("./yoke/usage").context(snapshot, session.vendor || "claude").context;
+    measurement = current.measurement;
+    used = firstNumber(current.usedTokens);
+    window = firstNumber(current.windowTokens);
+    if (used !== null || window !== null) source = current.source;
+
   }
   var history = session.history || [];
   var cumulativeInput = 0;
@@ -46,9 +44,9 @@ function contextStatus(session) {
       if (typeof item._ts === "number") lastCompactionAt = item._ts;
     }
     if (item.type !== "result") continue;
-    var usage = item.usage || {};
-    var input = firstNumber(usage.input_tokens, usage.inputTokens);
-    var output = firstNumber(usage.output_tokens, usage.outputTokens);
+    var usage = require("./yoke/usage").accounting(item.usage) || {};
+    var input = firstNumber(usage.inputTokens);
+    var output = firstNumber(usage.outputTokens);
     if (input !== null) { cumulativeInput += input; observedInput = true; }
     if (output !== null) { cumulativeOutput += output; observedOutput = true; }
     results++;
@@ -59,13 +57,14 @@ function contextStatus(session) {
   if (used !== null && window !== null && used > window) {
     used = null;
     source = "unavailable";
+    measurement = "unavailable";
   }
   // Older result records contain lastStreamInputTokens, but that field was
   // populated from adapter snapshots that could be cumulative or inflated by
   // cache accounting. It is not safe evidence of current context occupancy.
   var ratio = used !== null && window !== null && window > 0 ? Math.min(1, Math.round((used / window) * 1000) / 1000) : null;
   return {
-    current: { source: source, usedTokens: used, windowTokens: window, usedRatio: ratio,
+    current: { source: source, measurement: measurement, usedTokens: used, windowTokens: window, usedRatio: ratio,
       scope: used === null && window === null ? "unknown" : (used !== null && window !== null ? "current_context" : "partial_current_context") },
     cumulative: { inputTokens: observedInput ? cumulativeInput : null, outputTokens: observedOutput ? cumulativeOutput : null, tasksObserved: results, scope: "loaded_session_history", complete: false },
     lastTask: lastTask,

package/lib/project-pending-message-queue.js

@@ -141,6 +141,7 @@ function createPendingMessageQueue(opts) {
     delete item.message._scheduledJobId;
     delete item.message._scheduledRevision;
     delete item.message._scheduledNotBefore;
+    if (session._pendingMessageDrainPaused || session.taskStopRequested) data.paused[targetKey(session)] = true;
     data.items.push(item);
     data.revision++;
     try { persist(); } catch (e) { restore(before); return result(false, "Queue storage failed", session, actor); }
@@ -248,7 +249,8 @@ function createPendingMessageQueue(opts) {
     return true;
   }
   function consumeOne(session, dispatch) {
-    if (loadError || !session || session._pendingMessageClaimId || isPaused(session) || session._pendingMessageDrainPaused || session.taskStopRequested || session._queryStarting || session._awaitingTurnResult || session.isProcessing) return null;
+    var foreground = require('./sdk-foreground-admission');
+    if (loadError || !session || session._pendingMessageClaimId || isPaused(session) || session._pendingMessageDrainPaused || session.taskStopRequested || session._queryStarting || (session._awaitingTurnResult || session.isProcessing) && !foreground.available(session)) return null;
     if (session.rateLimitResetsAt && session.rateLimitResetsAt > Date.now()) return null;
     for (var i = 0; i < data.items.length; i++) {
       var item = data.items[i];
@@ -261,6 +263,7 @@ function createPendingMessageQueue(opts) {
       data.revision++;
       try { persist(); } catch (e) { restore(before); return null; }
       session._pendingMessageClaimId = item.id;
+      foreground.take(session);
       broadcast(session, { type: "pending_message_claimed", sessionId: session.localId, projectSlug: opts.slug, paused: isPaused(session), id: item.id, revision: data.revision });
       var completed = false;
       function complete(ok, error) { if (completed) return false; completed = true; return finishClaim(session, item.id, ok, error); }

package/lib/project-product-control.js

@@ -0,0 +1,89 @@
+var userInput = require("./yoke/user-input");
+var provenance = require("./session-provenance");
+var deletion = require("./project-session-delete");
+function attachProjectProductControl(ctx) {
+  var queues = require("./project-product-session-queue").attachProductSessionQueue({ queue: ctx.queue, sm: ctx.sm, users: ctx.users, requestDrain: ctx.requestQueueDrain });
+  function inspectQueue(principal, session) {
+    owned(principal, session);
+    if (ctx.isMate || provenance.isWorker(session) || session.spawn || ctx.isDriverOperatedSession(session)) throw new Error("Queues are controlled through their project Driver.");
+    return queues.inspect(principal, session);
+  }
+  function owned(principal, session) {
+    if (!session || ctx.sm.sessions.get(session.localId) !== session) throw new Error("Target session was deleted or replaced.");
+    if (ctx.users.isMultiUser()) {
+      var user = ctx.users.findUserById(principal.userId);
+      if (!user || session.ownerId !== user.id || !ctx.users.canAccessProject(user.id, ctx.getProjectAccess())) throw new Error("Live target ownership or access denied.");
+      return user;
+    }
+    if (session.ownerId && session.ownerId !== principal.singleUserOwnerId) throw new Error("Live target ownership denied.");
+    return null;
+  }
+  function review(session, question, revalidate, presentation) {
+    var owner = session.ownerId || null;
+    return userInput.dispatchUserInput(function (request, respond) {
+      // Presentation comes only from the bound product service, after normalization.
+      if (presentation) request.questions[0].review = presentation;
+      request.authorizeResponse = function (ws) {
+        try {
+          revalidate();
+          if (ctx.users.isMultiUser() && (!ws || !ws._clayUser || ws._clayUser.id !== owner || !ctx.users.findUserById(owner))) return false;
+          var tap = ws && ws._homeChatTap;
+          return !!ws && ((ctx.clients.has(ws) && ws._clayActiveSession === session.localId) || (tap && tap.mateSlug === ctx.slug && tap.sessionId === session.localId));
+        } catch (error) { return false; }
+      };
+      ctx.userInput(session)(request, respond);
+    }, { questions: [{ id: "control", header: "Review change", question: question, options: [{ label: "Keep unchanged" }, { label: "Apply exact change" }], allowOther: false }] }, { source: "product-control", signal: session.abortController && session.abortController.signal });
+  }
+  async function apply(principal, session, action, value, revalidate, control) {
+    var user = owned(principal, session);
+    function current() {
+      owned(principal, session);
+      if (typeof revalidate !== "function") throw new Error("An exact product control revision is required.");
+      revalidate();
+    }
+    current();
+    if (ctx.isMate || provenance.isWorker(session) || session.spawn || ctx.isDriverOperatedSession(session)) throw new Error("This target is not a project Driver.");
+    if (action.indexOf("queue_") === 0) return queues.apply(principal, session, control.args, current, control.requestKey);
+    if (action === "vendor") return ctx.vendor.setVendor(session, value, current);
+    if (action === "vendor_new_session") return ctx.vendor.newSession(session, value, current);
+    if (action === "runtime") return ctx.runtime.change(session, value, current);
+    if (action === "rename") return ctx.actions.rename(session, value);
+    if (action === "stop") return ctx.actions.stop(session, user);
+    if (session.taskStopRequested && action !== "delete") throw new Error("Target was stopped; explicit Driver resumption is required.");
+    if (action === "model") {
+      var models = (ctx.sm.modelsByVendor || {})[session.vendor || ctx.sm.defaultVendor || "claude"] || [];
+      if (!models.length) throw new Error("Provider model catalog is unavailable; no model was changed.");
+      var result = await ctx.selectModel(session, value, { revalidate: current });
+      if (!result) throw new Error("Model change failed.");
+      if (result.ok !== true && result.status !== "failed") throw new Error(result.error || "Model change failed.");
+      return result;
+    }
+    if (action === "effort") return ctx.actions.effort(session, value, current);
+    if (action === "permission") return ctx.actions.permission(session, value, null, current);
+    if (action === "fork" || action === "rewind") {
+      if (session.isProcessing || session._queryStarting || Object.keys(session.pendingPermissions || {}).length || Object.keys(session.pendingAskUser || {}).length) throw new Error("History changes require an idle Driver without pending approvals.");
+      if (!session.cliSessionId || !(session.messageUUIDs || []).some(function (entry) { return entry.uuid === value; })) throw new Error("Choose an exact recorded checkpoint from inspection.");
+      var vendor = session.vendor || ctx.sm.defaultVendor || "claude";
+      var caps = (ctx.sm.capabilitiesByVendor || {})[vendor] || {};
+      if (action === "fork" && !caps.fork || action === "rewind" && !caps.rollback && !caps.rewind) throw new Error("This provider does not support that history operation.");
+      if (action === "fork") {
+        var forked = await ctx.history.fork(session, value, null, revalidate);
+        if (!forked) throw new Error("The provider did not produce a forked session.");
+        return { forkedSessionRef: require("./workspace-query-service").sessionRef(ctx.slug, forked) };
+      }
+      return ctx.history.rewind(session, value, "chat", null, revalidate);
+    }
+    if (action === "delete") {
+      if (user && !ctx.users.getEffectivePermissions(user, ctx.osUsers).sessionDelete) throw new Error("You do not have permission to delete sessions.");
+      var plan = deletion.resolveDeletionScope(ctx.sm.sessions, [session], function (candidate) { return (candidate.ownerId || null) === (session.ownerId || null); });
+      if (!plan.ok) throw new Error(plan.error);
+      // A live Driver or Worker must be stopped and settled before deletion.
+      if (plan.ids.some(function (id) { var item = ctx.sm.sessions.get(id); return item.isProcessing || item._queryStarting; })) throw new Error("Stop the Driver and its Workers and wait for completion before deleting them.");
+      ctx.deletePlan(plan);
+      return { deletedCount: plan.ids.length };
+    }
+    throw new Error("Unsupported product control action.");
+  }
+  return { requestProductControlReview: review, applyProductSessionAction: apply, inspectProductSessionQueue: inspectQueue };
+}
+module.exports = { attachProjectProductControl: attachProjectProductControl };

package/lib/project-product-session-queue.js

@@ -0,0 +1,46 @@
+var crypto = require('crypto');
+function attachProductSessionQueue(ctx) {
+  var queue = ctx.queue;
+  function actor(principal) {
+    if (!ctx.users.isMultiUser()) return null;
+    var user = ctx.users.findUserById(principal.userId);
+    if (!user) throw new Error('Queue owner is no longer available.');
+    return user;
+  }
+  function inspect(principal, session) {
+    var user = actor(principal), state = queue.hydrate(session, user);
+    if (!state.ok) throw new Error(state.error || 'Queue inspection failed.');
+    return { revision: state.revision, paused: state.paused || !!session._pendingMessageDrainPaused || !!session.taskStopRequested,
+      items: state.items.filter(function (item) { return item.actorId === (user ? user.id : 'default'); }).filter(function (item, index, all) { return item.state === 'pending' || item.state === 'claimed' || index >= all.length - 20; }).map(function (item) {
+        return { id: item.id, state: item.state, text: String(item.message.text || '').slice(0, 1600), textTruncated: String(item.message.text || '').length > 1600,
+          imageCount: (item.message.images || []).length, pasteCount: (item.message.pastes || []).length, scheduled: !!item.schedule, failure: item.failure ? String(item.failure).slice(0, 500) : null };
+      }) };
+  }
+  function apply(principal, session, args, revalidate, requestKey) {
+    revalidate();
+    var user = actor(principal), before = queue.getRevision(), result;
+    try {
+      if (args.action === 'queue_add') {
+        var clientId = 'clay-control:' + crypto.createHash('sha256').update(requestKey).digest('hex');
+        var existing = queue.inspect(session, user, clientId);
+        var digest = crypto.createHash('sha256').update(args.text).digest('hex');
+        if (existing && (existing.message._clayControlDigest || crypto.createHash('sha256').update(existing.message.text).digest('hex')) !== digest) throw new Error('This requestId already identifies a different durable queue message.');
+        result = queue.admit(session, { type: 'message', text: args.text, clientMessageId: clientId, _clayControlDigest: digest }, user);
+      } else if (args.action === 'queue_edit') result = queue.edit(session, user, args.messageId, before, session.localId, { text: args.text });
+      else if (args.action === 'queue_cancel') result = queue.cancel(session, user, args.messageId, before, session.localId);
+      else if (args.action === 'queue_reorder') result = queue.reorder(session, user, args.ids, before, session.localId);
+      else throw new Error('Unsupported queue action.');
+    } catch (error) {
+      return { status: 'failed', outcome: queue.getRevision() !== before ? 'partial' : 'failed', persisted: queue.getRevision() !== before, error: error.message, queue: inspect(principal, session) };
+    }
+    if (!result || !result.ok) return { status: 'failed', persisted: false, error: result && result.error || 'Queue operation failed.', messageId: result && result.item && result.item.id, deliveryState: result && result.item && result.item.state, queue: inspect(principal, session) };
+    var state = inspect(principal, session);
+    if (args.action === 'queue_add') {
+      if (result.item && result.item.state === 'pending' && !state.paused) setImmediate(function () { if (ctx.sm.sessions.get(session.localId) === session) ctx.requestDrain(session); });
+      return { status: result.item && result.item.state === 'consumed' ? 'completed' : 'queued', persisted: true, messageId: result.item && result.item.id, deliveryState: result.item && result.item.state, queue: state };
+    }
+    return { status: 'completed', persisted: true, queue: state };
+  }
+  return { inspect: inspect, apply: apply };
+}
+module.exports = { attachProductSessionQueue: attachProductSessionQueue };

package/lib/project-push-access.js

@@ -0,0 +1,28 @@
+// Project push payloads carry session content and use the same live authority
+// as HTTP and WebSocket snapshots. Unscoped account/system pushes stay separate.
+function scopedPush(push, ctx) {
+  if (!push) return null;
+  function permitted(userId, payload) {
+    var data = payload.data || payload;
+    var slug = data.slug || ctx.slug;
+    var project = ctx.getProject(slug);
+    if (!project || !data.sessionId || !ctx.canAccessProject(userId, slug)) return false;
+    var session = project.getSessionManager().sessions.get(data.sessionId);
+    var status = project.getStatus();
+    var access = status.isMate ? { isMate: true, visibility: "private", ownerId: status.projectOwnerId } : ctx.getAccess(slug);
+    return !!session && ctx.users.canAccessSession(userId, session, access);
+  }
+  return Object.assign({}, push, {
+    sendPush: function (payload) {
+      if (!ctx.users.isMultiUser()) return push.sendPush(payload);
+      if (!push.sendPushToUser) return;
+      ctx.users.getAllUsers().forEach(function (user) {
+        if (permitted(user.id, payload)) push.sendPushToUser(user.id, payload);
+      });
+    },
+    sendPushToUser: function (userId, payload) {
+      if ((!ctx.users.isMultiUser() || permitted(userId, payload)) && push.sendPushToUser) push.sendPushToUser(userId, payload);
+    },
+  });
+}
+module.exports = { scopedPush: scopedPush };

package/lib/project-scheduled-message-queue.js

@@ -0,0 +1,30 @@
+function attachScheduledMessageQueue(ctx) {
+  var users = ctx.users;
+  var pendingMessageQueue = ctx.pendingMessageQueue;
+  function queueActor(actorId) {
+    return users.isMultiUser() ? users.findUserById(actorId) : { id: "default" };
+  }
+  function queueItemForJob(session, job, actorId) {
+    if (!pendingMessageQueue || !session || !job) return null;
+    var actor = queueActor(actorId || (job.payload && job.payload.actorId));
+    var items = pendingMessageQueue.list(session, actor);
+    for (var i = 0; i < items.length; i++) {
+      if (items[i].schedule && items[i].schedule.jobId === job.id && items[i].schedule.revision === job.payload.revision) return items[i];
+    }
+    return null;
+  }
+  function validateQueueControl(session, job, actorId, correlation, requireQueueRevision) {
+    if (!pendingMessageQueue) return null;
+    if (requireQueueRevision && (!correlation || correlation.queueRevision == null || Number(correlation.queueRevision) !== pendingMessageQueue.getRevision())) {
+      throw new Error("The scheduled-message queue is stale.");
+    }
+    var actor = queueActor(actorId || (job.payload && job.payload.actorId));
+    var item = queueItemForJob(session, job, actorId);
+    if (!item || item.actorId !== actor.id || ["cancelled", "consumed", "failed"].indexOf(item.state) >= 0) {
+      throw new Error("The scheduled queue item is no longer available.");
+    }
+    return item;
+  }
+  return { actor: queueActor, item: queueItemForJob, validate: validateQueueControl };
+}
+module.exports = { attachScheduledMessageQueue: attachScheduledMessageQueue };