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

package/lib/users-auth.js

@@ -1,4 +1,5 @@
 var crypto = require("crypto");
+var serverPin = require('./users-server-pin');
 
 function attachAuth(deps) {
   var loadUsers = deps.loadUsers;
@@ -80,7 +81,29 @@ function attachAuth(deps) {
   // --- Pin hashing ---
 
   function hashPin(pin) {
-    return crypto.createHash("sha256").update("clay-user:" + pin).digest("hex");
+    var salt = crypto.randomBytes(16).toString("hex");
+    var hash = crypto.scryptSync("clay-user:" + pin, salt, 64, { N: 16384, r: 8, p: 1 }).toString("hex");
+    return "scrypt-v1:" + salt + ":" + hash;
+  }
+
+  function verifyPin(pin, storedHash, user) {
+    // Older JSON clients could submit a numeric PIN; preserve that spelling.
+    if (typeof pin === "number" && Number.isSafeInteger(pin) && pin >= 0) pin = String(pin);
+    if (typeof pin !== "string" || typeof storedHash !== "string") return false;
+    var migratedHash = serverPin.resolve(storedHash, user, deps.loadConfig);
+    if (migratedHash) return serverPin.verify(pin, migratedHash);
+    var expected;
+    var actual;
+    if (/^[a-f0-9]{64}$/.test(storedHash)) {
+      expected = Buffer.from(storedHash, "hex");
+      actual = crypto.createHash("sha256").update("clay-user:" + pin).digest();
+    } else {
+      var parts = /^scrypt-v1:([a-f0-9]{32}):([a-f0-9]{128})$/.exec(storedHash);
+      if (!parts) return false;
+      expected = Buffer.from(parts[2], "hex");
+      actual = crypto.scryptSync("clay-user:" + pin, parts[1], 64, { N: 16384, r: 8, p: 1 });
+    }
+    return crypto.timingSafeEqual(actual, expected);
   }
 
   // Generate a random 6-digit PIN
@@ -96,6 +119,7 @@ function attachAuth(deps) {
   // --- Authentication ---
 
   function authenticateUser(username, pin) {
+    if (typeof username !== "string") return null;
     var data = loadUsers();
     var user = null;
     for (var i = 0; i < data.users.length; i++) {
@@ -105,8 +129,18 @@ function attachAuth(deps) {
       }
     }
     if (!user) return null;
-    var pinH = hashPin(pin);
-    if (user.pinHash !== pinH) return null;
+    if (!verifyPin(pin, user.pinHash, user)) return null;
+    if (user.pinHash.indexOf('scrypt-v1:') !== 0) {
+      var previousHash = user.pinHash;
+      try {
+        user.pinHash = hashPin(pin);
+        saveUsers(data);
+      } catch (e) {
+        // A best-effort upgrade must never reject a verified existing PIN.
+        user.pinHash = previousHash;
+        console.error("[users] PIN hash upgrade could not be saved; it will be retried on login.");
+      }
+    }
     return user;
   }
 
@@ -136,6 +170,7 @@ function attachAuth(deps) {
     clearSetupCode: clearSetupCode,
     validateSetupCode: validateSetupCode,
     hashPin: hashPin,
+    verifyPin: verifyPin,
     generatePin: generatePin,
     authenticateUser: authenticateUser,
     generateUserAuthToken: generateUserAuthToken,

package/lib/users-contextual-clay-preferences.js

@@ -0,0 +1,31 @@
+// Personal geometry is never a canonical product-control operation.
+function validGeometry(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  var keys = Object.keys(value);
+  if (keys.length !== 4 || keys.some(function (key) { return ['left', 'top', 'width', 'height'].indexOf(key) < 0; })) return false;
+  return keys.every(function (key) { return typeof value[key] === 'number' && Number.isFinite(value[key]); }) &&
+    value.left >= 0 && value.left <= 16384 && value.top >= 0 && value.top <= 16384 &&
+    value.width >= 340 && value.width <= 2560 && value.height >= 360 && value.height <= 2160;
+}
+function attachContextualClayPreferences(deps) {
+  function get(userId) {
+    var user = deps.loadUsers().users.find(function (entry) { return entry.id === userId; });
+    var saved = user && user.contextualClayGeometry;
+    if (!user && userId === 'default') saved = require('./config').loadConfig().contextualClayGeometry;
+    return validGeometry(saved) ? Object.assign({}, saved) : null;
+  }
+  function set(userId, geometry) {
+    if (!validGeometry(geometry)) return { error: 'Invalid popover geometry.' };
+    var value = Object.assign({}, geometry);
+    var data = deps.loadUsers();
+    var user = data.users.find(function (entry) { return entry.id === userId; });
+    if (user) { user.contextualClayGeometry = value; deps.saveUsers(data); }
+    else if (userId === 'default') {
+      var config = require('./config');
+      config.saveConfig(Object.assign({}, config.loadConfig(), { contextualClayGeometry: value }));
+    } else return { error: 'Account no longer available.' };
+    return { geometry: value };
+  }
+  return { getContextualClayGeometry: get, setContextualClayGeometry: set };
+}
+module.exports = { attachContextualClayPreferences: attachContextualClayPreferences, validGeometry: validGeometry };

package/lib/users-create.js

@@ -0,0 +1,97 @@
+var crypto = require("crypto");
+var serverPin = require("./users-server-pin");
+
+function attachCreation(deps) {
+  var loadUsers = deps.loadUsers;
+  var saveUsers = deps.saveUsers;
+  var generateUserId = deps.generateUserId;
+  var ensureUserBuiltinMates = deps.ensureUserBuiltinMates;
+  var auth = deps.auth;
+
+  function createUser(opts) {
+    var data = loadUsers();
+    // Check username uniqueness
+    for (var i = 0; i < data.users.length; i++) {
+      if (data.users[i].username.toLowerCase() === opts.username.toLowerCase()) {
+        return { error: "This username is already taken" };
+      }
+    }
+    // Check email uniqueness (when provided)
+    if (opts.email) {
+      for (var i = 0; i < data.users.length; i++) {
+        if (data.users[i].email && data.users[i].email.toLowerCase() === opts.email.toLowerCase()) {
+          return { error: "This email is already registered" };
+        }
+      }
+    }
+    var user = {
+      id: generateUserId(),
+      username: opts.username,
+      email: opts.email || null,
+      displayName: opts.displayName || opts.username,
+      pinHash: auth.hashPin(opts.pin),
+      role: opts.role || "user",
+      mustChangePin: !!opts.mustChangePin,
+      createdAt: Date.now(),
+      linuxUser: opts.linuxUser || null,
+      profile: opts.profile || {
+        name: opts.displayName || opts.username,
+        lang: "en-US",
+        avatarColor: "#5857fc",
+        avatarStyle: "imprint",
+        avatarSeed: crypto.randomBytes(4).toString("hex"),
+      },
+    };
+    data.users.push(user);
+    saveUsers(data);
+
+    // Seed immediately for ordinary multi-user storage. OS-user provisioning
+    // calls this again after the Linux mapping exists, targeting its final home.
+    ensureUserBuiltinMates(user.id);
+
+    return { ok: true, user: user };
+  }
+
+  function createUserWithoutPin(opts, migration) {
+    var data = loadUsers();
+    for (var i = 0; i < data.users.length; i++) {
+      if (data.users[i].username.toLowerCase() === opts.username.toLowerCase()) {
+        return { error: "This username is already taken" };
+      }
+    }
+    if (opts.email) {
+      for (var i = 0; i < data.users.length; i++) {
+        if (data.users[i].email && data.users[i].email.toLowerCase() === opts.email.toLowerCase()) {
+          return { error: "This email is already registered" };
+        }
+      }
+    }
+    var user = {
+      id: generateUserId(),
+      username: opts.username,
+      email: opts.email || null,
+      displayName: opts.displayName || opts.username,
+      pinHash: migration && migration.pinHash ? serverPin.tag(migration.pinHash) : null,
+      role: opts.role || "user",
+      createdAt: Date.now(),
+      profile: opts.profile || {
+        name: opts.displayName || opts.username,
+        lang: "en-US",
+        avatarColor: "#5857fc",
+        avatarStyle: "imprint",
+        avatarSeed: crypto.randomBytes(4).toString("hex"),
+      },
+    };
+    data.users.push(user);
+    if (migration) { data.multiUser = true; data.setupCode = null; }
+    saveUsers(data);
+
+    ensureUserBuiltinMates(user.id);
+
+    return { ok: true, user: user };
+  }
+
+  return { createUser: createUser, createUserWithoutPin: createUserWithoutPin };
+}
+
+module.exports = { attachCreation: attachCreation };

package/lib/users-permissions.js

@@ -64,15 +64,12 @@ function attachPermissions(deps) {
   // --- Project access helpers ---
 
   function canAccessProject(userId, project) {
-    if (!project) return false;
+    if (!project || !userId || !findUserById(userId) || project.ownershipRecovery === "required") return false;
     if (project.isMate === true || (typeof project.slug === "string" && project.slug.indexOf("mate-") === 0)) {
       return !!userId && !!project.ownerId && project.ownerId === userId;
     }
     // Public projects are accessible to all authenticated users
     if (!project.visibility || project.visibility === "public") return true;
-    // Admin always has access
-    var user = findUserById(userId);
-    if (user && user.role === "admin") return true;
     // Owner always has access to their own project
     if (project.ownerId && project.ownerId === userId) return true;
     // Private project -- check allowedUsers
@@ -96,10 +93,7 @@ function attachPermissions(deps) {
       return !!userId && !!session.ownerId && session.ownerId === userId;
     }
     if (session.userKnowledgeOwnerId) return !!userId && session.userKnowledgeOwnerId === userId && session.ownerId === userId;
-    // Resolve the stored user record so client-supplied roles cannot elevate access.
-    var user = findUserById(userId);
-    if (user && user.role === "admin") return true;
-    // Sessions without ownerId are legacy -- only admin can see them
+    // Unowned historical sessions require explicit recovery; role is not ownership.
     if (!session.ownerId) return false;
     // Owner can always see their own sessions
     if (session.ownerId === userId) return true;

package/lib/users-server-pin.js

@@ -0,0 +1,37 @@
+var crypto = require('crypto');
+var PREFIX = 'server-pin-v1:';
+
+function isServerHash(hash) {
+  return typeof hash === 'string' && (/^[a-f0-9]{64}$/.test(hash) || /^[a-f0-9]{32}:[a-f0-9]{128}$/.test(hash));
+}
+
+function tag(hash) {
+  if (!isServerHash(hash)) throw new Error('Invalid legacy server PIN hash');
+  return PREFIX + hash;
+}
+
+function resolve(hash, user, loadConfig) {
+  if (typeof hash !== 'string') return null;
+  if (hash.indexOf(PREFIX) === 0) {
+    var original = hash.slice(PREFIX.length);
+    return isServerHash(original) ? original : null;
+  }
+  if (!user || !isServerHash(hash) || typeof loadConfig !== 'function') return null;
+  // Only the recorded migrated owner may use an untagged server credential.
+  var config;
+  try { config = loadConfig(); } catch (e) { return null; }
+  if (config && config.singleUserMigratedAt && config.singleUserMigratedUserId === user.id && config.pinHash === hash) return hash;
+  return null;
+}
+
+function verify(pin, hash) {
+  if (!isServerHash(hash)) return false;
+  var parts = hash.split(':');
+  var expected = Buffer.from(parts.length === 2 ? parts[1] : hash, 'hex');
+  var actual = parts.length === 2
+    ? crypto.scryptSync('clay:' + pin, parts[0], 64)
+    : crypto.createHash('sha256').update('clay:' + pin).digest();
+  return crypto.timingSafeEqual(actual, expected);
+}
+
+module.exports = { tag: tag, resolve: resolve, verify: verify };

package/lib/users.js

@@ -71,50 +71,6 @@ function ensureUserBuiltinMates(userId) {
   }
 }
 
-function createUser(opts) {
-  var data = loadUsers();
-  // Check username uniqueness
-  for (var i = 0; i < data.users.length; i++) {
-    if (data.users[i].username.toLowerCase() === opts.username.toLowerCase()) {
-      return { error: "This username is already taken" };
-    }
-  }
-  // Check email uniqueness (when provided)
-  if (opts.email) {
-    for (var i = 0; i < data.users.length; i++) {
-      if (data.users[i].email && data.users[i].email.toLowerCase() === opts.email.toLowerCase()) {
-        return { error: "This email is already registered" };
-      }
-    }
-  }
-  var user = {
-    id: generateUserId(),
-    username: opts.username,
-    email: opts.email || null,
-    displayName: opts.displayName || opts.username,
-    pinHash: auth.hashPin(opts.pin),
-    role: opts.role || "user",
-    mustChangePin: !!opts.mustChangePin,
-    createdAt: Date.now(),
-    linuxUser: opts.linuxUser || null,
-    profile: opts.profile || {
-      name: opts.displayName || opts.username,
-      lang: "en-US",
-      avatarColor: "#5857fc",
-      avatarStyle: "imprint",
-      avatarSeed: crypto.randomBytes(4).toString("hex"),
-    },
-  };
-  data.users.push(user);
-  saveUsers(data);
-
-  // Seed immediately for ordinary multi-user storage. OS-user provisioning
-  // calls this again after the Linux mapping exists, targeting its final home.
-  ensureUserBuiltinMates(user.id);
-
-  return { ok: true, user: user };
-}
-
 function createAdmin(opts) {
   return createUser({
     username: opts.username,
@@ -188,7 +144,7 @@ function getSoloNoPinUser() {
   var data = loadUsers();
   if (!data.users || data.users.length !== 1) return null;
   var u = data.users[0];
-  if (u.pinHash) return null;
+  if (u.pinHash || u.passwordHash || data.accountAuthMethod === 'password') return null;
   return u;
 }
 
@@ -199,6 +155,10 @@ function getOtherUsers(excludeUserId) {
 }
 
 function removeUser(userId) {
+  var registered = require("./config").loadConfig();
+  if (registered && (registered.projects || []).some(function (project) {
+    return !require("./project-ownership").isPersonal(project) && project.ownerId === userId;
+  })) return { error: "Transfer ordinary owned projects before deleting this account." };
   var data = loadUsers();
   var before = data.users.length;
   data.users = data.users.filter(function (u) { return u.id !== userId; });
@@ -224,6 +184,11 @@ function updateUserPin(userId, newPin) {
   for (var i = 0; i < data.users.length; i++) {
     if (data.users[i].id === userId) {
       data.users[i].pinHash = auth.hashPin(newPin);
+      if (data.accountAuthMethod === 'password') {
+        delete data.users[i].passwordHash;
+        delete data.users[i].passkeys;
+        delete data.users[i].passkeyUserHandle;
+      }
       data.users[i].mustChangePin = false;
       saveUsers(data);
       return { ok: true };
@@ -306,44 +271,6 @@ function createInvite(createdByUserId, targetEmail) {
   return invite;
 }
 
-function createUserWithoutPin(opts) {
-  var data = loadUsers();
-  for (var i = 0; i < data.users.length; i++) {
-    if (data.users[i].username.toLowerCase() === opts.username.toLowerCase()) {
-      return { error: "This username is already taken" };
-    }
-  }
-  if (opts.email) {
-    for (var i = 0; i < data.users.length; i++) {
-      if (data.users[i].email && data.users[i].email.toLowerCase() === opts.email.toLowerCase()) {
-        return { error: "This email is already registered" };
-      }
-    }
-  }
-  var user = {
-    id: generateUserId(),
-    username: opts.username,
-    email: opts.email || null,
-    displayName: opts.displayName || opts.username,
-    pinHash: null,
-    role: opts.role || "user",
-    createdAt: Date.now(),
-    profile: opts.profile || {
-      name: opts.displayName || opts.username,
-      lang: "en-US",
-      avatarColor: "#5857fc",
-      avatarStyle: "imprint",
-      avatarSeed: crypto.randomBytes(4).toString("hex"),
-    },
-  };
-  data.users.push(user);
-  saveUsers(data);
-
-  ensureUserBuiltinMates(user.id);
-
-  return { ok: true, user: user };
-}
-
 function findInvite(code) {
   var data = loadUsers();
   for (var i = 0; i < data.invites.length; i++) {
@@ -400,8 +327,12 @@ function removeExpiredInvites() {
 
 // --- Wire extracted modules ---
 
-var auth = attachAuth({ loadUsers: loadUsers, saveUsers: saveUsers, findAdmin: findAdmin });
+var auth = attachAuth({ loadUsers: loadUsers, saveUsers: saveUsers, findAdmin: findAdmin, loadConfig: require('./config').loadConfig });
+var creation = require("./users-create").attachCreation({ loadUsers: loadUsers, saveUsers: saveUsers, generateUserId: generateUserId, ensureUserBuiltinMates: ensureUserBuiltinMates, auth: auth });
+var createUser = creation.createUser;
+var createUserWithoutPin = creation.createUserWithoutPin;
 var permissions = attachPermissions({ loadUsers: loadUsers, saveUsers: saveUsers, findUserById: findUserById });
+var contextualClayPreferences = require("./users-contextual-clay-preferences").attachContextualClayPreferences({ loadUsers: loadUsers, saveUsers: saveUsers });
 var preferences = attachPreferences({ loadUsers: loadUsers, saveUsers: saveUsers });
 var projectMateFilterPreferences = attachProjectMateFilterPreferences({ loadUsers: loadUsers, saveUsers: saveUsers });
 var homeDockPreferences = attachHomeDockPreferences({ loadUsers: loadUsers, saveUsers: saveUsers });
@@ -489,6 +420,7 @@ module.exports = {
   validateSetupCode: validateSetupCode,
   generateUserId: generateUserId,
   hashPin: hashPin,
+  verifyPin: auth.verifyPin,
   createUser: createUser,
   createAdmin: createAdmin,
   findAdmin: findAdmin,
@@ -547,6 +479,8 @@ module.exports = {
   setToolPalette: setToolPalette,
   getTerminalFont: getTerminalFont,
   setTerminalFont: setTerminalFont,
+  getContextualClayGeometry: contextualClayPreferences.getContextualClayGeometry,
+  setContextualClayGeometry: contextualClayPreferences.setContextualClayGeometry,
   getHomeDockPreference: getHomeDockPreference,
   setHomeDockPreference: setHomeDockPreference,
   getHomeSurfacePreference: getHomeSurfacePreference,

package/lib/vendor-login-browser.js

@@ -7,17 +7,7 @@ var spawn = require("child_process").spawn;
 var buildUserEnv = require("./build-user-env").buildUserEnv;
 var wrapSpawnAsUser = require("./os-users").wrapSpawnAsUser;
 
-function loginUrl(value, vendor) {
-  try {
-    var url = new URL(value);
-    var hosts = vendor === "codex" ? ["auth.openai.com"] : ["claude.ai", "claude.com", "console.anthropic.com", "platform.claude.com"];
-    if (url.protocol !== "https:" || url.username || url.password || hosts.indexOf(url.hostname) < 0) return null;
-    if (!url.searchParams.get("state") || !url.searchParams.get("code_challenge")) return null;
-    var callback = new URL(url.searchParams.get("redirect_uri"));
-    if (callback.protocol !== "http:" || ["localhost", "127.0.0.1", "[::1]"].indexOf(callback.hostname) < 0) return null;
-    return url.href;
-  } catch (e) { return null; }
-}
+var loginUrl = require("./yoke/login-protocol").loginUrl;
 
 function createLoginBrowser(options) {
   var initial = null;

package/lib/workspace-assignment-service.js

@@ -19,6 +19,8 @@ function attachWorkspaceAssignmentService(ctx) {
   var records = [];
   var unsubscribers = {};
   var pendingRestartReplay = {};
+  var presentations = new WeakMap();
+  var presentationTargets = new WeakMap();
 
   function recordFile(userId) {
     return storageDir ? path.join(storageDir, userStorageKey(userId)) : null;
@@ -130,7 +132,27 @@ function attachWorkspaceAssignmentService(ctx) {
     return { project: project, manager: manager, session: session };
   }
 
+  function present(record, principal) {
+    try {
+      var display = ctx.getPresentation && ctx.getPresentation(principal), project = exactTarget(record);
+      if (!display || !project) return;
+      var view = { project: project, session: null, origin: null }; presentationTargets.set(record, view);
+      if (record.delivery === 'follow_up') project.getSessionManager().sessions.forEach(function (session) { if (ctx.sessionRef(record.targetProjectSlug, session) === record.targetSessionRef) { view.session = session; view.origin = session.sessionOriginId; } });
+      var projection = require('./clay-control-target-projection');
+      var target = view.session ? { kind: 'session', projectSlug: record.targetProjectSlug, sessionId: view.session.localId, sessionOriginId: view.origin } : { kind: 'project', projectSlug: record.targetProjectSlug, runtimeId: projection.runtime(project.getSessionManager()) };
+      var observer = display.track('assignment', record.delivery === 'follow_up' ? 'follow_up' : 'assign', target, function () {
+        if (exactTarget(record) !== project || view.session && (project.getSessionManager().sessions.get(view.session.localId) !== view.session || view.session.sessionOriginId !== view.origin || (view.session.ownerId || null) !== (record.userId || null))) throw new Error('Assignment target changed.');
+      }, 'review');
+      if (observer) { presentations.set(record, observer); var expiry = setTimeout(function () { presentations.delete(record); }, 300000); expiry.unref(); }
+    } catch (error) { /* Presentation never changes the assignment decision. */ }
+  }
   function emit(record, eventType) {
+    var observer = presentations.get(record);
+    if (observer) {
+      if (record.status === 'starting') observer.phase('queued');
+      else if (record.status === 'running') observer.phase('running');
+      else if (record.status !== 'proposed') { observer.finish({ status: record.status === 'interrupted' ? 'failed' : record.status, outcome: record.status === 'interrupted' ? 'uncertain' : undefined }); presentations.delete(record); }
+    }
     var source = exactSource(record);
     if (!source) return;
     source.manager.sendAndRecord(source.session, {
@@ -193,6 +215,7 @@ function attachWorkspaceAssignmentService(ctx) {
     if (!exactSource(record)) throw new Error("Source conversation is no longer available.");
     records.push(record);
     saveUser(record.userId);
+    present(record, principal);
     emit(record, "project_assignment_proposal");
     return publicRecord(record);
   }
@@ -229,6 +252,7 @@ function attachWorkspaceAssignmentService(ctx) {
     if (!exactSource(record)) throw new Error("Source conversation is no longer available.");
     records.push(record);
     saveUser(record.userId);
+    present(record, principal);
     emit(record, "project_assignment_proposal");
     return publicRecord(record);
   }
@@ -267,6 +291,7 @@ function attachWorkspaceAssignmentService(ctx) {
   }
 
   function watch(record, manager, session) {
+    var view = presentationTargets.get(record); if (view) { view.session = session; view.origin = session.sessionOriginId; var observer = presentations.get(record); if (observer && observer.target) observer.target({ kind: 'session', projectSlug: record.targetProjectSlug, sessionId: session.localId, sessionOriginId: session.sessionOriginId }); }
     var unsubscribe = manager.subscribeSession(session.localId, function (event) {
       if (event.type === "session_id") {
         record.targetSessionRef = ctx.sessionRef(record.targetProjectSlug, session);

package/lib/workspace-query-access.js

@@ -96,7 +96,10 @@ function attachWorkspaceQueryAccess(deps) {
     // as ownership would let a stale status skip the authoritative record.
     var access = record(status);
     if (!access) return denied;
-    if (access.ownerId && access.ownerId === principal.userId) return { owned: true, accessible: true };
+    if (access.ownerId && access.ownerId === principal.userId) {
+      var ownerPermitted = permitted(principal.userId, access);
+      return { owned: ownerPermitted, accessible: ownerPermitted };
+    }
     return { owned: false, accessible: permitted(principal.userId, access) };
   }
 

package/lib/workspace-query-mcp-server.js

@@ -32,7 +32,7 @@ function handler(bound, method) {
   };
 }
 
-var SESSION_CITATION = " When citing a returned session in user-visible text, write [clayos/<sessionRef> — short label] so Clay Studio renders an owner-validated session control.";
+var SESSION_CITATION = " Cite returned sessions as Markdown links: [short human label](session:OPAQUE_REFERENCE), replacing the entire target with the exact returned sessionRef. Do not prepend a project name, change the opaque reference, or wrap citations in backticks/code. For a specific returned entry, append #entry-<entryIndex> using its exact returned entry index. Legacy [clayos/<sessionRef> — short label] remains supported. Labels are presentation only; Clay Studio resolves the exact reference with the authenticated owner's permissions.";
 
 function commonTools(bound) {
   return [

package/lib/workspace-query-service.js

@@ -168,6 +168,13 @@ function attachWorkspaceQueryService(ctx) {
     } else if (source.session.ownerId) {
       return null;
     }
+    if (source.viewerId !== undefined) {
+      var viewerPrincipal = {
+        userId: isMultiUser() ? source.viewerId : null,
+        singleUserOwnerId: isMultiUser() ? null : source.viewerId,
+      };
+      if (!ownsSession(viewerPrincipal, source.session)) return null;
+    }
     return createBound({
       userId: isMultiUser() ? source.session.ownerId : null,
       sourceProjectSlug: source.projectSlug,
@@ -366,11 +373,13 @@ function attachWorkspaceQueryService(ctx) {
 
   function resolveSessionNavigation(principal, ref) {
     if (typeof ref !== "string" || !/^session:[A-Za-z0-9_-]{24}$/.test(ref)) throw new Error("Invalid session reference.");
+    var entryIndex = arguments.length > 2 ? arguments[2] : null;
+    if (entryIndex !== null && entryIndex !== undefined && (!Number.isSafeInteger(entryIndex) || entryIndex < 0)) throw new Error("Invalid session entry reference.");
     var projects = collect(principal);
     for (var p = 0; p < projects.length; p++) {
       var session = findSession(projects[p], ref);
       if (!session) continue;
-      return {
+      var target = {
         projectSlug: projects[p].projectSlug,
         projectTitle: projects[p].projectTitle,
         isMate: projects[p].isMate,
@@ -379,6 +388,8 @@ function attachWorkspaceQueryService(ctx) {
         homeSessionId: session.cliSessionId || "local:" + session.localId,
         title: cleanMetadata(session.title || "New Session", 160),
       };
+      if (entryIndex !== null && entryIndex !== undefined) target.entryIndex = entryIndex;
+      return target;
     }
     throw new Error("Session not found in the owned workspace.");
   }
@@ -450,7 +461,7 @@ function attachWorkspaceQueryService(ctx) {
         if (!principal.isClay) throw new Error("Workspace-wide activity is available only to builtin Clay.");
         return workspaceActivity(principal, args || {});
       },
-      resolveSessionNavigation: function (args) { return resolveSessionNavigation(principal, args && args.sessionRef); },
+      resolveSessionNavigation: function (args) { return resolveSessionNavigation(principal, args && args.sessionRef, args && args.entryIndex); },
       listRecentDecisions: function (args) {
         if (!principal.isClay) throw new Error("Workspace decisions are available only to builtin Clay.");
         return recentDecisions(principal, args || {});

package/lib/ws-request.js

@@ -8,6 +8,7 @@ function parseWsRequestUrl(requestUrl) {
     path: parsed.pathname || "/",
     pane: parsed.query.pane === "1",
     paneSession: paneSession,
+    contextual: parsed.query.pane === "1" && parsed.query.contextual === "1",
   };
 }
 

package/lib/ws-schema.js

@@ -11,6 +11,11 @@
  * Use it as a reference when adding new message types.
  */
 
+// message.contextualSnapshot: version=1, viewId, nullable projectTitle,
+// conversationTitle/projectSlug (160 characters), nullable positive sessionId,
+// screen=Home|Project|Direct message. Private canonical owner delivery only.
+// Persisted user_message metadata is echoed in message_ack only after recording;
+// queued admission ACK has no snapshot. Never part of user text/pastes or authority.
 var schema = {
 
   // -----------------------------------------------------------------------
@@ -62,6 +67,7 @@ var schema = {
   "project_assignment_response": { direction: "c2s", handler: "lib/workspace-assignment-service.js", description: "Approve or cancel an exact-session cross-project assignment proposal" },
   "home_clay_session_resolve": { direction: "c2s", handler: "lib/server-home-chat.js", description: "Resolve an opaque Mate session reference through the exact bound source session" },
   "home_clay_session_target": { direction: "s2c", handler: "lib/public/modules/command-palette.js", description: "Return an owner-validated navigation target for a rendered Mate session reference" },
+  "home_clay_contextual_session": { direction: "s2c", handler: "lib/public/modules/contextual-search.js", description: "Return the exact fresh canonical session for an idempotent contextual Ask request; does not submit or execute a message" },
   "issues_list": { direction: "c2s", handler: "lib/project-issues.js", description: "Project Issues issues list" },
   "issue_read": { direction: "c2s", handler: "lib/project-issues.js", description: "Project Issues issue read" },
   "issue_create": { direction: "c2s", handler: "lib/project-issues.js", description: "Project Issues issue create" },
@@ -482,6 +488,7 @@ var schema = {
   "term_resized":             { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Terminal was resized" },
   "term_exited":              { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Terminal process exited" },
   "term_closed":              { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Terminal session was closed" },
+  "term_control_projection": { direction: "s2c", handler: "lib/public/modules/terminal.js", description: "Authoritative terminal identity/revision after owner resize without echoing resize input" },
   "term_list":                { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Full list of open terminals" },
   "term_error":               { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Terminal error (e.g. access denied)" },
   "shell_command":            { direction: "c2s", handler: "lib/project-shell-command.js", description: "Run a one-shot shell command for agent context" },
@@ -495,10 +502,11 @@ var schema = {
   "note_written":             { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Agent created or updated a sticky note" },
   "note_update":              { direction: "c2s", handler: "lib/project-user-message.js", description: "Update a sticky note" },
   "note_updated":             { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Sticky note was updated" },
-  "note_close":               { direction: "c2s", handler: "lib/project-user-message.js", description: "Close a sticky note (reversible; never deletes)" },
+  "note_update_result":        { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Correlated sticky note update result" },
+  "note_close":               { direction: "c2s", handler: "lib/project-user-message.js", description: "Close a sticky note; human draft-aware requests remove empty notes, tool and legacy closes stay reversible" },
   "note_reopen":              { direction: "c2s", handler: "lib/project-user-message.js", description: "Reopen a closed sticky note" },
   "note_delete":              { direction: "c2s", handler: "lib/project-user-message.js", description: "Retired: older clients still send this; handled as a non-destructive close" },
-  "note_deleted":             { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Retired: never sent. Closing broadcasts note_updated instead" },
+  "note_deleted":             { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "A sticky note was permanently removed after a human-authorized storage transaction" },
   "note_list_request":        { direction: "c2s", handler: "lib/project-user-message.js", description: "Request the full notes list" },
   "note_bring_front":         { direction: "c2s", handler: "lib/project-user-message.js", description: "Bring a note to front (update z-order)" },
   "notes_list":               { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Full list of sticky notes" },
@@ -784,6 +792,7 @@ var schema = {
   // -----------------------------------------------------------------------
   "home_mate_open":           { direction: "c2s", handler: "lib/server-home-chat.js", description: "Open or restore the selected mate's embedded chat session" },
   "home_clay_ask":            { direction: "c2s", handler: "lib/server-home-chat.js", description: "Start a fresh builtin Clay conversation from the global search drawer" },
+  "contextual_mate_sessions_result": { direction: "s2c", handler: "lib/public/modules/contextual-mate-sessions.js", description: "Exact owner-private saved Mate conversation list or selection receipt; no transcript tap or underlying navigation" },
   "home_mate_sessions_list":  { direction: "c2s", handler: "lib/server-home-chat.js", description: "List the current user's conversations with the selected mate" },
   "home_mate_session_open":   { direction: "c2s", handler: "lib/server-home-chat.js", description: "Open one explicit conversation with the selected mate" },
   "home_mate_send":           { direction: "c2s", handler: "lib/server-home-chat.js", description: "Send a message to the selected mate from the home hub" },
@@ -809,6 +818,13 @@ var schema = {
   "default_vendor_get":       { direction: "c2s", handler: "lib/server-default-vendor.js", description: "Read the authenticated user's New session vendor preference" },
   "default_vendor_set":       { direction: "c2s", handler: "lib/server-default-vendor.js", description: "Validate and persist the authenticated user's New session vendor preference" },
   "default_vendor_state":     { direction: "s2c", handler: "lib/public/modules/default-vendor.js", description: "Correlated or same-user-broadcast New session vendor preference" },
+  "clay_ui_ready":            { direction: "c2s", handler: "lib/server-owner-ui.js", description: "Advertise exact owner UI navigation support on this socket" },
+  "clay_navigation_offer":    { direction: "s2c", handler: "lib/public/modules/clay-owner-navigation.js", description: "Offer one exact reviewed navigation to a selected owner connection" },
+  "clay_navigation_claim":    { direction: "c2s", handler: "lib/server-owner-ui.js", description: "Claim an offered navigation with live source/target revalidation" },
+  "clay_navigation_apply":    { direction: "s2c", handler: "lib/public/modules/clay-owner-navigation.js", description: "Invoke the shared conversation navigator after live claim" },
+  "clay_studio_rendered": { direction: "c2s", handler: "lib/project-studio-presentation.js", description: "Exact source-viewer workbench render receipt; no product effects" },
+  "clay_navigation_rendered": { direction: "c2s", handler: "lib/server-owner-ui.js", description: "Bounded exact-viewer rendered conversation evidence; acceptance alone remains separate" },
+  "clay_navigation_ack":      { direction: "c2s", handler: "lib/server-owner-ui.js", description: "Client invocation acknowledgement; never proof of visible rendering" },
   "context_view_get":         { direction: "c2s", handler: "lib/server-context-view.js", description: "Read the authenticated user's context display preference" },
   "context_view_set":         { direction: "c2s", handler: "lib/server-context-view.js", description: "Persist the authenticated user's context display preference" },
   "context_view_state":       { direction: "s2c", handler: "lib/public/modules/context-view-preference.js", description: "Correlated or same-user-broadcast context display preference" },