clay-server 5.1.0-beta.1 → 5.1.0-beta.3

package/lib/storage-usage.js

@@ -0,0 +1,144 @@
+var fs = require('node:fs/promises');
+var path = require('node:path');
+var execFile = require('node:child_process').execFile;
+var nativeWalk = require('./storage-native-walk');
+
+function resolveIdentity(username) {
+  return new Promise(function (resolve) {
+    if (!/^[a-z_][a-z0-9_-]*[$]?$/.test(username || '')) return resolve(null);
+    execFile('getent', ['passwd', username], { timeout: 3000, maxBuffer: 8192 }, function (error, output) {
+      if (error) return resolve(null);
+      var parts = output.trim().split(':');
+      var uid = Number(parts[2]);
+      resolve(parts.length >= 7 && /^\d+$/.test(parts[2]) && Number.isInteger(uid) && uid >= 0 && path.isAbsolute(parts[5]) ? { uid: uid, home: parts[5] } : null);
+    });
+  });
+}
+
+// Read metadata only. Shared paths and hard links count once across all roots.
+async function scanStorage(options) {
+  var started = Date.now();
+  var deadline = options.maxMs ? started + options.maxMs : Infinity;
+  var maxEntries = options.maxEntries || Infinity;
+  var users = options.users || [];
+  var projectMode = options.attribution === "project";
+  var projects = options.projects || [];
+  var identities = await Promise.all(users.map(function (user) {
+    return !projectMode && options.platform === 'linux' && user.linuxUser ? (options.resolveIdentity || resolveIdentity)(user.linuxUser) : null;
+  }));
+  var rows = users.map(function (user, index) {
+    return { id: user.id, name: user.displayName || user.username, linuxUser: user.linuxUser || null, mapped: projectMode || !!identities[index], projects: 0, bytes: 0, files: 0 };
+  });
+  var owners = new Map();
+  identities.forEach(function (identity, index) {
+    if (!identity) return;
+    // A reused OS identity cannot be split accurately between Clay accounts.
+    owners.set(identity.uid, owners.has(identity.uid) ? null : rows[index]);
+  });
+  identities.forEach(function (identity, index) {
+    if (identity && !owners.get(identity.uid)) rows[index].mapped = false;
+  });
+  var projectRoots = new Map();
+  var projectErrors = 0;
+  for (var project of projects) {
+    try {
+      var projectPath = await fs.realpath(project.path);
+      var row = rows.find(function (item) { return item.id === project.projectOwnerId; }) || null;
+      if (row) row.projects++;
+      if (projectRoots.has(projectPath) && projectRoots.get(projectPath) !== row) row = null;
+      projectRoots.set(projectPath, row);
+    } catch (error) { projectErrors++; }
+  }
+  var orderedProjects = Array.from(projectRoots.keys()).sort(function (a, b) { return b.length - a.length; });
+  function projectOwner(filePath) {
+    var root = orderedProjects.find(function (candidate) { return filePath === candidate || filePath.indexOf(candidate + path.sep) === 0; });
+    return root ? projectRoots.get(root) : null;
+  }
+  var roots = orderedProjects.concat(options.projectPaths || []);
+  identities.forEach(function (identity) { if (identity) roots.push(identity.home); });
+  roots.push(options.configDir);
+  var report = { attribution: projectMode ? "project" : "filesystem", users: rows, totalBytes: 0, totalFiles: 0, unattributedBytes: 0, unattributedFiles: 0,
+    partial: false, errors: projectErrors + users.filter(function (user, index) { return !projectMode && options.platform === 'linux' && user.linuxUser && !identities[index]; }).length, skippedLinks: 0, skippedMounts: 0, scannedEntries: 0, roots: 0, platform: options.platform };
+  var lastProgress = 0;
+  function progress() {
+    if (!options.onProgress || Date.now() - lastProgress < 500) return;
+    lastProgress = Date.now();
+    options.onProgress(Object.assign({}, report, { scanning: true, checkedAt: new Date().toISOString(),
+      users: rows.map(function (row) { return Object.assign({}, row); }) }));
+  }
+  progress();
+  var seen = new Map();
+  var rootPaths = new Set();
+  var completedRoots = [];
+  var useNative = options.native !== false && await nativeWalk.available();
+  for (var root of roots) {
+    if (typeof root !== 'string' || !path.isAbsolute(root)) { report.errors++; continue; }
+    try {
+      root = await fs.realpath(root);
+      // Never turn a misconfigured home/project into a whole-host scan.
+      if (root === path.parse(root).root) { report.errors++; continue; }
+      if (rootPaths.has(root)) continue;
+      rootPaths.add(root);
+      var rootStat = await fs.lstat(root);
+      report.roots++;
+      if (useNative) {
+        if (seen.has(rootStat.dev + ':' + rootStat.ino)) continue;
+        var result = await nativeWalk.walk(root, completedRoots, function (filePath, stat) {
+          if (Date.now() >= deadline || report.scannedEntries >= maxEntries) { report.partial = true; return false; }
+          account(filePath, stat, rootStat.dev);
+        }, deadline - Date.now());
+        report.errors += result.errors;
+        if (result.stopped) report.partial = true;
+        completedRoots.push(root);
+      } else await walk(root, rootStat.dev);
+    } catch (error) { report.errors++; }
+    if (report.partial) break;
+  }
+  report.partial = report.partial || report.errors > 0 || report.skippedMounts > 0;
+  report.scanning = false;
+  report.checkedAt = new Date().toISOString();
+  return report;
+
+  async function walk(filePath, device) {
+    if (Date.now() >= deadline || report.scannedEntries >= maxEntries) { report.partial = true; return; }
+    var stat;
+    try { stat = await fs.lstat(filePath); } catch (error) { report.errors++; return; }
+    if (!account(filePath, stat, device)) return;
+    if (!stat.isDirectory()) return;
+    try {
+      var directory = await fs.opendir(filePath);
+      for await (var entry of directory) {
+        await walk(path.join(filePath, entry.name), device);
+        if (report.partial) break;
+      }
+    } catch (error) { report.errors++; }
+  }
+
+  function account(filePath, stat, device) {
+    if (stat.isSymbolicLink()) { report.skippedLinks++; return; }
+    if (stat.dev !== device) { report.skippedMounts++; return; }
+    var key = stat.dev + ':' + stat.ino;
+    var owner = projectMode ? projectOwner(filePath) : owners.get(stat.uid);
+    if (seen.has(key)) {
+      var previous = seen.get(key);
+      if (projectMode && stat.isFile() && previous.owner && previous.owner !== owner) {
+        previous.owner.bytes -= previous.bytes; previous.owner.files--;
+        report.unattributedBytes += previous.bytes; report.unattributedFiles++;
+        previous.owner = null;
+      }
+      return;
+    }
+    report.scannedEntries++;
+    if (!stat.isDirectory() && !stat.isFile()) return;
+    var bytes = typeof stat.blocks === 'number' ? stat.blocks * 512 : stat.size;
+    // Only directories and multiply-linked files need identity deduplication.
+    if (stat.isDirectory() || stat.nlink > 1) seen.set(key, { owner: owner, bytes: bytes });
+    report.totalBytes += bytes;
+    if (stat.isFile()) report.totalFiles++;
+    if (owner) { owner.bytes += bytes; if (stat.isFile()) owner.files++; }
+    else { report.unattributedBytes += bytes; if (stat.isFile()) report.unattributedFiles++; }
+    progress();
+    return true;
+  }
+}
+module.exports = { scanStorage: scanStorage };

package/lib/user-knowledge-service.js

@@ -0,0 +1,167 @@
+// Owner-private user knowledge. Only canonical Clay sessions curate records.
+var crypto = require('crypto');
+var canUsePersonalConnections = require('./mcp-session-access').canUsePersonalConnections;
+var createRecordStore = require('./knowledge-record-store').createRecordStore;
+
+function attachUserKnowledgeService(deps) {
+  var stores = new Map();
+  function owner(id) {
+    if (deps.isMultiUser() && (!id || !deps.findUser(id))) throw new Error('User knowledge requires an authenticated owner.');
+    return deps.isMultiUser() ? id : 'default';
+  }
+  function storage(id) {
+    var key = crypto.createHash('sha256').update(owner(id)).digest('hex');
+    if (!stores.has(key)) stores.set(key, createRecordStore({scopeId:'user/' + key + '/you',baseDir:deps.baseDir}));
+    return stores.get(key);
+  }
+  function snapshot(id) {
+    var result = {entries:{},reports:{},activity:[],seen:{},version:0};
+    storage(id).all().forEach(function (record) {
+      if (record.kind !== 'user-knowledge') return;
+      result.version++;
+      if (record.seen) result.seen[record.seen.ref] = Math.max(result.seen[record.seen.ref] || 0, record.seen.revision);
+      if (record.entry) result.entries[record.entry.ref] = record.entry;
+      if (record.report) result.reports[record.report.ref] = record.report;
+      if (record.activity) result.activity.push(record.activity);
+    });
+    return result;
+  }
+  function text(value, max, required) {
+    if (typeof value !== 'string' || value.length > max || (required && !value.trim())) throw new Error('Invalid or oversized knowledge text.');
+    return value.trim();
+  }
+  function page(items, args) {
+    args = args || {};
+    var offset = Math.max(0, Number(args.offset) || 0);
+    offset = Number.isFinite(offset) ? Math.floor(offset) : 0;
+    var limit = Math.min(50, Math.max(1, Number(args.limit) || 30));
+    return {items:items.slice(offset,offset+limit),total:items.length,nextOffset:offset+limit < items.length ? offset+limit:null};
+  }
+  function unread(entry,state) { return !entry.archived && entry.revisions > (state.seen[entry.ref] || 0); }
+  function attention(id) {
+    var state = snapshot(id);
+    return { unread: Object.values(state.entries).filter(function (entry) { return unread(entry,state); }).length, version: state.version };
+  }
+  function acknowledge(id,args) {
+    var state = snapshot(id);
+    var entry = state.entries[args.ref];
+    if (!entry || entry.archived) throw new Error('User knowledge not found.');
+    if (!Number.isInteger(args.revision) || args.revision < 1 || args.revision > entry.revisions) throw new Error('Invalid memory revision.');
+    if ((state.seen[args.ref] || 0) < args.revision) {
+      storage(id).append({kind:'user-knowledge',seen:{ref:args.ref,revision:args.revision,at:Date.now()}});
+      try { deps.onChange(owner(id),{seen:true}); } catch (error) { /* Acknowledgement survives notification failures. */ }
+    }
+    return attention(id);
+  }
+  function list(id,args) {
+    var state = snapshot(id);
+    args = args || {};
+    var query = String(args.query || '').toLowerCase().slice(0,300);
+    var entries = Object.values(state.entries).filter(function (entry) {
+      return !entry.archived && (!args.category || entry.category === args.category) &&
+        (!query || (entry.title+' '+entry.summary+' '+entry.body).toLowerCase().indexOf(query)!==-1);
+    }).map(function(entry){return Object.assign({},entry,{unread:unread(entry,state)});}).sort(function (a,b) {return Number(b.unread)-Number(a.unread) || b.updatedAt-a.updatedAt;});
+    return Object.assign(page(entries,args),{categories:Array.from(new Set(Object.values(state.entries).filter(function (e) {return !e.archived;}).map(function(e){return e.category;}))).sort(),pending:Object.values(state.reports).filter(function(r){return r.status==='pending';}).length});
+  }
+  function read(id,ref) {
+    var entry = snapshot(id).entries[ref];
+    if (!entry || entry.archived) throw new Error('User knowledge not found.');
+    var comments = Object.values(snapshot(id).reports).filter(function (item) { return item.commentEntryRef === ref; }).map(function (item) {
+      return { id: item.ref, body: item.observation, at: item.createdAt, author: { type: 'user', displayName: 'You' },
+        status: item.status === 'accepted' ? 'incorporated' : item.status,
+        review: item.reviewedAt ? { response: item.reason, at: item.reviewedAt, author: { displayName: 'Clay' } } : null };
+    });
+    return Object.assign({}, entry, { comments: comments, commentCount: comments.length });
+  }
+  function comment(id,args,source) {
+    var entry = read(id,args.ref);
+    return report(id,{observation:args.body,evidence:'Comment on '+entry.ref+': '+args.body,evidenceType:'explicit'},source,entry.ref);
+  }
+  function report(id,args,source,commentEntryRef) {
+    var state = snapshot(id);
+    var observation = text(args.observation,4000,true);
+    var evidence = text(args.evidence,4000,true);
+    var evidenceType = args.evidenceType || 'explicit';
+    if (['explicit','inferred'].indexOf(evidenceType)===-1) throw new Error('Invalid evidence type.');
+    var existing = Object.values(state.reports).find(function (r) {return r.observation===observation && r.evidence===evidence && r.source.session===source.session && r.source.project===source.project && r.status==='pending';});
+    if (existing) return existing;
+    if (Object.values(state.reports).filter(function (r) {return r.status==='pending';}).length>=200) throw new Error('Clay has 200 pending observations. Review those before reporting more.');
+    var record = {ref:'observation:'+crypto.randomBytes(12).toString('hex'),observation:observation,evidence:evidence,evidenceType:evidenceType,source:source,commentEntryRef:commentEntryRef || null,status:'pending',createdAt:Date.now()};
+    storage(id).append({kind:'user-knowledge',report:record});
+    try {deps.onReport(owner(id));} catch (error) { /* Durable pending report remains available for retry. */ }
+    return record;
+  }
+  function bind(binding) {
+    var originalOwner = binding.session && binding.session.ownerId;
+    function principal() {
+      var project = deps.getProject(binding.projectSlug);
+      var session = binding.session;
+      if (!project || !session || project.sm.sessions.get(session.localId)!==session || session.destroying) throw new Error('A live owner-bound session is required.');
+      if (session.ownerId !== originalOwner) throw new Error('Session ownership changed.');
+      if (deps.isMultiUser() && session.sessionVisibility === 'shared') throw new Error('Private User Knowledge is unavailable in shared conversations.');
+      if (deps.isMultiUser() && !canUsePersonalConnections(session, project.sm.sessions)) throw new Error('User Knowledge requires an owner-only conversation and Driver.');
+      var id = owner(session.ownerId);
+      var status = project.getStatus();
+      if (deps.isMultiUser() && !deps.canAccess(id,binding.projectSlug)) throw new Error('Project access was revoked.');
+      var mate = status.isMate && deps.resolveMate(id,status.mateId);
+      var clay = !!(mate && mate.builtinKey==='clay' && (!deps.isMultiUser() || mate.createdBy===id));
+      return {id:id,clay:clay,source:{project:binding.projectSlug,session:session.cliSessionId || 'local:'+session.localId,mateId:status.mateId || null}};
+    }
+    function protect(p) {
+      if (!deps.isMultiUser()) return;
+      var session = binding.session;
+      var manager = deps.getProject(binding.projectSlug).sm;
+      function mark(target) {
+        if (target.userKnowledgeOwnerId === p.id) return;
+        var previous = target.userKnowledgeOwnerId;
+        target.userKnowledgeOwnerId = p.id;
+        try { manager.saveSessionFile(target); } catch (error) { target.userKnowledgeOwnerId = previous; throw error; }
+      }
+      var provenance = session.sessionProvenance;
+      if (provenance && provenance.kind === 'worker') manager.sessions.forEach(function (parent) {
+        if (parent.sessionOriginId === provenance.parentSessionOriginId) mark(parent);
+      });
+      mark(session);
+    }
+    function curator() {var p=principal();if(!p.clay) throw new Error('Only your canonical Clay can curate User Knowledge.');return p;}
+    return {
+      isClay:function () {return principal().clay;},
+      list:function(args){var p=principal();var result=list(p.id,args);if(result.items.length)protect(p);return result;},
+      read:function(args){var p=principal();var result=read(p.id,args.ref);protect(p);return result;},
+      report:function(args){var p=principal();return report(p.id,args,p.source);},
+      pending:function(args){var p=curator();return page(Object.values(snapshot(p.id).reports).filter(function(r){return r.status==='pending';}),args);},
+      curate:function(args) {
+        var p=curator();
+        var state=snapshot(p.id);
+        var observation=state.reports[args.reportRef];
+        if (!observation) throw new Error('Observation not found.');
+        if (observation.status!=='pending') return {report:observation,entry:observation.entryRef ? state.entries[observation.entryRef]:null};
+        var action=args.action;
+        if (['save','decline','archive'].indexOf(action)===-1) throw new Error('Invalid curation action.');
+        var reason=text(args.reason,2000,true);
+        var previous=args.ref ? state.entries[args.ref]:null;
+        if (args.ref && !previous) throw new Error('User knowledge not found.');
+        if (previous && args.expectedRevision!==previous.revisions) throw new Error('Knowledge changed. Read it again before updating.');
+        var entry=null;
+        var now=Date.now();
+        if (action!=='decline') {
+          if(action==='archive' && !previous) throw new Error('Choose an existing entry to archive.');
+          var category=action==='archive' ? previous.category:text(args.category,32,true);
+          if(!/^[a-z][a-z0-9-]*$/.test(category)) throw new Error('Use a lowercase category.');
+          entry=Object.assign({},previous || {},{ref:previous ? previous.ref:'you:'+crypto.randomBytes(12).toString('hex'),category:category,kind:category,
+            title:action==='archive' ? previous.title:text(args.title,160,true),summary:action==='archive' ? previous.summary:text(args.summary,600,true),
+            body:action==='archive' ? previous.body:text(args.body,8000,true),archived:action==='archive',
+            createdAt:previous ? previous.createdAt:now,updatedAt:now,revisions:previous ? previous.revisions+1:1,
+            updatedBy:{type:'system',displayName:'Clay'},source:observation.source,evidence:observation.evidence,evidenceType:observation.evidenceType,reason:reason});
+        }
+        var reviewed=Object.assign({},observation,{status:action==='decline'?'declined':'accepted',reviewedAt:now,reason:reason,entryRef:entry && entry.ref});
+        var activity=entry ? {id:crypto.randomBytes(12).toString('hex'),ref:entry.ref,title:entry.title,summary:entry.summary,at:now,action:action==='archive'?'archive':(previous?'update':'create'),revision:entry.revisions}:null;
+        storage(p.id).append({kind:'user-knowledge',entry:entry,report:reviewed,activity:activity});
+        if(activity) {try {deps.onChange(p.id,activity);} catch(error) { /* Saved record survives notification failures. */ }}
+        return {entry:entry,report:reviewed};
+      }
+    };
+  }
+  return {bind:bind,list:list,read:read,report:report,comment:comment,attention:attention,acknowledge:acknowledge,activity:function(id,args){return page(snapshot(id).activity.slice().reverse(),args);},pendingCount:function(id){return Object.values(snapshot(id).reports).filter(function(r){return r.status==='pending';}).length;}};
+}
+module.exports={attachUserKnowledgeService:attachUserKnowledgeService};

package/lib/users-permissions.js

@@ -65,6 +65,9 @@ function attachPermissions(deps) {
 
   function canAccessProject(userId, project) {
     if (!project) 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
@@ -89,6 +92,10 @@ function attachPermissions(deps) {
   function canAccessSession(userId, session, project) {
     // Must have project access first
     if (!canAccessProject(userId, project)) return false;
+    if (session.isMate === true || project.isMate === true || (typeof project.slug === "string" && project.slug.indexOf("mate-") === 0)) {
+      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;

package/lib/users-preferences.js

@@ -218,78 +218,6 @@ function attachPreferences(deps) {
     return { error: "User not found" };
   }
 
-  // --- Per-user Claude open mode ---
-  //
-  // Decides how Claude sessions are rendered when the user clicks into one:
-  //   'gui' - Clay's custom chat UI driven by the Claude Agent SDK.
-  //   'tui' - Embedded xterm running the real `claude` CLI. Keeps usage in
-  //           the Interactive billing bucket post Agent SDK split.
-  //
-  // Cutover moment: midnight 2026-06-15 in UTC+14 (Line Islands - the
-  // earliest timezone on Earth in June, 14h ahead of UTC). On that instant
-  // two things happen at once:
-  //   1. The default flips from 'gui' to 'tui' (so usage lands in the
-  //      Interactive billing bucket).
-  //   2. Any previously-stored per-user preference is treated as cleared
-  //      so the new default applies to everyone. Toggles made on or after
-  //      the cutover persist normally.
-  //
-  // The preference applies on the next session open. Currently displayed
-  // sessions are not re-rendered retroactively. The cross-mode click
-  // logic in project-sessions.js handles both directions in-place
-  // (prepareTuiSessionForGuiView for tui->gui rendering, claude --resume
-  // PTY respawn for gui->tui rendering on a born-tui session).
-
-  // Single cutover instant for both default flip and one-time reset:
-  // 2026-06-15 00:00 in UTC+14 = 2026-06-14 10:00 UTC.
-  var CLAUDE_OPEN_MODE_CUTOVER_MS = Date.UTC(2026, 5, 14, 10, 0, 0);
-  var CLAUDE_OPEN_MODE_RESET_MS = CLAUDE_OPEN_MODE_CUTOVER_MS;
-
-  function defaultClaudeOpenMode() {
-    // Reverted to GUI: the TUI default was a hedge against the (since-cancelled)
-    // Agent SDK separate-credit billing. Users who explicitly picked TUI after
-    // the cutover keep it (isStoredPreferenceLive); everyone else gets GUI.
-    return "gui";
-  }
-
-  // A stored preference counts only if it was set on or after the reset
-  // moment (or we haven't reached the reset moment yet). Older preferences
-  // are ignored so the new default applies once.
-  function isStoredPreferenceLive(user) {
-    if (Date.now() < CLAUDE_OPEN_MODE_RESET_MS) return true;
-    var setAt = user && user.claudeOpenModeSetAt;
-    return typeof setAt === "number" && setAt >= CLAUDE_OPEN_MODE_RESET_MS;
-  }
-
-  function getClaudeOpenMode(userId) {
-    var data = loadUsers();
-    var fallback = defaultClaudeOpenMode();
-    for (var i = 0; i < data.users.length; i++) {
-      if (data.users[i].id === userId) {
-        var m = data.users[i].claudeOpenMode;
-        if ((m === "gui" || m === "tui") && isStoredPreferenceLive(data.users[i])) return m;
-        return fallback;
-      }
-    }
-    return fallback;
-  }
-
-  function setClaudeOpenMode(userId, mode) {
-    // GUI is the default in every other resolution path, so an unrecognized
-    // value must land on GUI too. Only an explicit "tui" opts into terminal.
-    var normalized = (mode === "tui") ? "tui" : "gui";
-    var data = loadUsers();
-    for (var i = 0; i < data.users.length; i++) {
-      if (data.users[i].id === userId) {
-        data.users[i].claudeOpenMode = normalized;
-        data.users[i].claudeOpenModeSetAt = Date.now();
-        saveUsers(data);
-        return { ok: true, claudeOpenMode: normalized };
-      }
-    }
-    return { error: "User not found" };
-  }
-
   // --- Per-user cursor sharing preference ---
 
   function getCursorSharing(userId) {
@@ -512,8 +440,6 @@ function attachPreferences(deps) {
     setChatLayout: setChatLayout,
     getAutoContinue: getAutoContinue,
     setAutoContinue: setAutoContinue,
-    getClaudeOpenMode: getClaudeOpenMode,
-    setClaudeOpenMode: setClaudeOpenMode,
     getCursorSharing: getCursorSharing,
     setCursorSharing: setCursorSharing,
     getClaudeUserAllowList: getClaudeUserAllowList,

package/lib/users-project-mate-filter-preferences.js

@@ -0,0 +1,39 @@
+function attachProjectMateFilterPreferences(deps) {
+  var loadUsers = deps.loadUsers;
+  var saveUsers = deps.saveUsers;
+  var configModule = deps.config || require("./config");
+
+  function normalize(mode) {
+    return mode === "projects" || mode === "mates" ? mode : "all";
+  }
+
+  function get(userId) {
+    var data = loadUsers();
+    for (var i = 0; i < data.users.length; i++) {
+      if (data.users[i].id === userId) return normalize(data.users[i].projectMateFilterMode);
+    }
+    var current = configModule.loadConfig() || {};
+    return normalize(current.projectMateFilterMode);
+  }
+
+  function set(userId, mode) {
+    if (mode !== "all" && mode !== "projects" && mode !== "mates") {
+      return { error: "Invalid project and Mate filter mode" };
+    }
+    var data = loadUsers();
+    for (var i = 0; i < data.users.length; i++) {
+      if (data.users[i].id === userId) {
+        data.users[i].projectMateFilterMode = mode;
+        saveUsers(data);
+        return { ok: true, projectMateFilterMode: mode };
+      }
+    }
+    var current = configModule.loadConfig() || {};
+    configModule.saveConfig(Object.assign({}, current, { projectMateFilterMode: mode }));
+    return { ok: true, projectMateFilterMode: mode };
+  }
+
+  return { get: get, set: set };
+}
+
+module.exports = { attachProjectMateFilterPreferences: attachProjectMateFilterPreferences };

package/lib/users.js

@@ -6,6 +6,7 @@ var { CONFIG_DIR } = require("./config");
 var { attachAuth } = require("./users-auth");
 var { DEFAULT_PERMISSIONS, ALL_PERMISSIONS, attachPermissions } = require("./users-permissions");
 var { attachPreferences } = require("./users-preferences");
+var { attachProjectMateFilterPreferences } = require("./users-project-mate-filter-preferences");
 var { attachHomeDockPreferences } = require("./users-home-dock-preferences");
 var { attachHomeSurfacePreferences } = require("./users-home-surface-preferences");
 var { attachSessionFolderPreferences } = require("./users-session-folder-preferences");
@@ -402,6 +403,7 @@ function removeExpiredInvites() {
 var auth = attachAuth({ loadUsers: loadUsers, saveUsers: saveUsers, findAdmin: findAdmin });
 var permissions = attachPermissions({ loadUsers: loadUsers, saveUsers: saveUsers, findUserById: findUserById });
 var preferences = attachPreferences({ loadUsers: loadUsers, saveUsers: saveUsers });
+var projectMateFilterPreferences = attachProjectMateFilterPreferences({ loadUsers: loadUsers, saveUsers: saveUsers });
 var homeDockPreferences = attachHomeDockPreferences({ loadUsers: loadUsers, saveUsers: saveUsers });
 var homeSurfacePreferences = attachHomeSurfacePreferences({ loadUsers: loadUsers, saveUsers: saveUsers });
 var sessionFolderPreferences = attachSessionFolderPreferences({ loadUsers: loadUsers, saveUsers: saveUsers });
@@ -445,8 +447,8 @@ var getChatLayout = preferences.getChatLayout;
 var setChatLayout = preferences.setChatLayout;
 var getAutoContinue = preferences.getAutoContinue;
 var setAutoContinue = preferences.setAutoContinue;
-var getClaudeOpenMode = preferences.getClaudeOpenMode;
-var setClaudeOpenMode = preferences.setClaudeOpenMode;
+var getProjectMateFilterMode = projectMateFilterPreferences.get;
+var setProjectMateFilterMode = projectMateFilterPreferences.set;
 var getCursorSharing = preferences.getCursorSharing;
 var setCursorSharing = preferences.setCursorSharing;
 var getClaudeUserAllowList = preferences.getClaudeUserAllowList;
@@ -531,8 +533,8 @@ module.exports = {
   setMateOnboarded: setMateOnboarded,
   getAutoContinue: getAutoContinue,
   setAutoContinue: setAutoContinue,
-  getClaudeOpenMode: getClaudeOpenMode,
-  setClaudeOpenMode: setClaudeOpenMode,
+  getProjectMateFilterMode: getProjectMateFilterMode,
+  setProjectMateFilterMode: setProjectMateFilterMode,
   getCursorSharing: getCursorSharing,
   setCursorSharing: setCursorSharing,
   getClaudeUserAllowList: getClaudeUserAllowList,

package/lib/workspace-query-access.js

@@ -87,7 +87,10 @@ function attachWorkspaceQueryAccess(deps) {
       return { owned: owned, accessible: owned };
     }
     if (!principal.userId) return denied;
-    if (ownsMateProject(principal, status)) return { owned: true, accessible: true };
+    if (status.isMate === true) {
+      var ownsMate = ownsMateProject(principal, status);
+      return { owned: ownsMate, accessible: ownsMate };
+    }
     // status.projectOwnerId is never trusted on its own in multi-user mode: it
     // is a snapshot that can outlive a transfer or a revocation, so treating it
     // as ownership would let a stale status skip the authoritative record.

package/lib/ws-schema.js

@@ -346,6 +346,8 @@ var schema = {
   // -----------------------------------------------------------------------
   // Updates
   // -----------------------------------------------------------------------
+  "update_check_failed": { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Update check failure" },
+  "set_update_channel_result": { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Release channel save acknowledgement" },
   "set_update_channel":       { direction: "c2s", handler: "lib/project-sessions.js", description: "Set the update channel (stable/beta)" },
   "check_update":             { direction: "c2s", handler: "lib/project-sessions.js", description: "Check if an update is available" },
   "update_now":               { direction: "c2s", handler: "lib/project-sessions.js", description: "Start the update process" },
@@ -454,10 +456,6 @@ var schema = {
   "project_env_result":       { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Project .envrc content" },
   "set_project_env":          { direction: "c2s", handler: "lib/project-filesystem.js", description: "Write the project .envrc" },
   "set_project_env_result":   { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Project .envrc write result" },
-  "read_global_claude_md":    { direction: "c2s", handler: "lib/project-filesystem.js", description: "Read the global CLAUDE.md" },
-  "global_claude_md_result":  { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Global CLAUDE.md content" },
-  "write_global_claude_md":   { direction: "c2s", handler: "lib/project-filesystem.js", description: "Write the global CLAUDE.md" },
-  "write_global_claude_md_result": { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Global CLAUDE.md write result" },
   "get_shared_env":           { direction: "c2s", handler: "lib/project-filesystem.js", description: "Read the shared .envrc" },
   "shared_env_result":        { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Shared .envrc content" },
   "set_shared_env":           { direction: "c2s", handler: "lib/project-filesystem.js", description: "Write the shared .envrc" },
@@ -572,6 +570,9 @@ var schema = {
   "mate_delete":              { direction: "c2s", handler: "lib/server-mates.js", description: "Delete a mate" },
   "mate_deleted":             { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Mate was deleted" },
   "mate_update":              { direction: "c2s", handler: "lib/server-mates.js", description: "Update a mate's properties" },
+  "mate_instructions_get":   { direction: "c2s", handler: "lib/server-mate-instructions.js", description: "Read the owner-scoped Mate identity prompt" },
+  "mate_instructions_set":   { direction: "c2s", handler: "lib/server-mate-instructions.js", description: "Save a Mate identity prompt with revision checking" },
+  "mate_instructions_result": { direction: "s2c", handler: "lib/public/modules/home-mate-instructions.js", description: "Correlated prompt read or save result" },
   "mate_updated":             { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Mate was updated" },
   "mate_readd_builtin":       { direction: "c2s", handler: "lib/server-mates.js", description: "Re-add a previously deleted built-in mate" },
   "mate_list_available_builtins": { direction: "c2s", handler: "lib/server-mates.js", description: "List built-in mates available for re-adding" },
@@ -658,16 +659,63 @@ var schema = {
   // Knowledge (mate knowledge files)
   // -----------------------------------------------------------------------
   "knowledge_list":           { direction: "both", handler: "lib/project-knowledge.js", description: "Request (c2s) or receive (s2c) knowledge file list" },
+  "knowledge_search":         { direction: "c2s", handler: "lib/project-knowledge.js", description: "Search bounded project Knowledge filenames and document content" },
+  "knowledge_search_results": { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Correlated bounded Knowledge document search results" },
   "knowledge_read":           { direction: "c2s", handler: "lib/project-knowledge.js", description: "Read a knowledge file" },
   "knowledge_content":        { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Knowledge file content" },
   "knowledge_save":           { direction: "c2s", handler: "lib/project-knowledge.js", description: "Save a knowledge file" },
   "knowledge_saved":          { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Knowledge file was saved" },
+  "knowledge_rename":         { direction: "c2s", handler: "lib/project-knowledge.js", description: "Rename a knowledge Markdown document with a revision precondition" },
+  "knowledge_renamed":        { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge document was renamed" },
+  "knowledge_error":          { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Correlated Knowledge operation error or stale-write conflict" },
+  "knowledge_sync":           { direction: "c2s", handler: "lib/project-knowledge.js", description: "Retry common Knowledge record synchronization after a canonical file mutation" },
+  "knowledge_synced":         { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge record synchronization retry completed" },
   "knowledge_delete":         { direction: "c2s", handler: "lib/project-knowledge.js", description: "Delete a knowledge file" },
   "knowledge_deleted":        { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Knowledge file was deleted" },
+  "knowledge_draft_save":     { direction: "c2s", handler: "lib/project-knowledge.js", description: "Persist a versioned user- and workspace-bound Knowledge draft" },
+  "knowledge_draft_saved":    { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge draft persistence acknowledgement" },
+  "knowledge_draft_delete":   { direction: "c2s", handler: "lib/project-knowledge.js", description: "Remove a Knowledge draft through a submitted client version" },
+  "knowledge_draft_deleted":  { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge draft removal acknowledgement" },
+  "knowledge_discard_draft":  { direction: "c2s", handler: "lib/project-knowledge.js", description: "Discard a bounded draft version and read a guarded disk revision" },
+  "knowledge_draft_discarded":{ direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Guarded disk content returned after draft discard" },
+  "knowledge_history":        { direction: "both", handler: "lib/project-knowledge.js", description: "Request or receive bounded document history" },
+  "knowledge_history_read":   { direction: "c2s", handler: "lib/project-knowledge.js", description: "Read one explicit bounded document history version" },
+  "knowledge_history_version":{ direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Content for one explicit document history version" },
+  "knowledge_restore":        { direction: "c2s", handler: "lib/project-knowledge.js", description: "Restore an explicit history version with a revision precondition" },
+  "knowledge_restored":       { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge history version was restored" },
+  "knowledge_deleted_list":   { direction: "both", handler: "lib/project-knowledge.js", description: "Request or receive recoverable deleted Knowledge documents" },
   "knowledge_promote":        { direction: "c2s", handler: "lib/project-knowledge.js", description: "Promote a knowledge file to always-active" },
   "knowledge_promoted":       { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Knowledge file was promoted" },
   "knowledge_depromote":      { direction: "c2s", handler: "lib/project-knowledge.js", description: "Depromote a knowledge file from always-active" },
   "knowledge_depromoted":     { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Knowledge file was depromoted" },
+  "knowledge_db_create":      { direction: "c2s", handler: "lib/project-knowledge.js", description: "Create a first-class Mate Knowledge database" },
+  "knowledge_db_created":     { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge database creation result" },
+  "knowledge_db_read":        { direction: "c2s", handler: "lib/project-knowledge.js", description: "Read Knowledge database schema and views" },
+  "knowledge_db_content":     { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge database schema and views" },
+  "knowledge_db_rename":      { direction: "c2s", handler: "lib/project-knowledge.js", description: "Rename a Knowledge database with a revision precondition" },
+  "knowledge_db_renamed":     { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge database rename result" },
+  "knowledge_db_archive":     { direction: "c2s", handler: "lib/project-knowledge.js", description: "Recoverably archive a Knowledge database" },
+  "knowledge_db_archived":    { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge database archive result" },
+  "knowledge_db_recover":     { direction: "c2s", handler: "lib/project-knowledge.js", description: "Recover an archived Knowledge database" },
+  "knowledge_db_recovered":   { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge database recovery result" },
+  "knowledge_db_schema_save": { direction: "c2s", handler: "lib/project-knowledge.js", description: "Save a validated Knowledge database schema" },
+  "knowledge_db_schema_saved":{ direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge database schema result" },
+  "knowledge_db_view_save":   { direction: "c2s", handler: "lib/project-knowledge.js", description: "Save a validated table view" },
+  "knowledge_db_view_saved":  { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge database table view result" },
+  "knowledge_db_record_create": { direction: "c2s", handler: "lib/project-knowledge.js", description: "Create a typed Knowledge database record" },
+  "knowledge_db_record_created": { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge database record creation result" },
+  "knowledge_db_record_read": { direction: "c2s", handler: "lib/project-knowledge.js", description: "Read one Knowledge database record and history" },
+  "knowledge_db_record_content": { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge database record detail" },
+  "knowledge_db_record_update": { direction: "c2s", handler: "lib/project-knowledge.js", description: "Update a typed Knowledge database record" },
+  "knowledge_db_record_updated": { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge database record update result" },
+  "knowledge_db_record_archive": { direction: "c2s", handler: "lib/project-knowledge.js", description: "Recoverably archive a Knowledge database record" },
+  "knowledge_db_record_archived": { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge database record archive result" },
+  "knowledge_db_record_recover": { direction: "c2s", handler: "lib/project-knowledge.js", description: "Recover an archived Knowledge database record" },
+  "knowledge_db_record_recovered": { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge database record recovery result" },
+  "knowledge_db_query":       { direction: "c2s", handler: "lib/project-knowledge.js", description: "Run a bounded validated deterministic Knowledge database query" },
+  "knowledge_db_query_results": { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge database query page and totals" },
+  "knowledge_db_sync":        { direction: "c2s", handler: "lib/project-knowledge.js", description: "Retry Knowledge database summary projection" },
+  "knowledge_db_synced":      { direction: "s2c", handler: "lib/public/modules/mate-knowledge-workbench.js", description: "Knowledge database summary projection retry result" },
 
   // -----------------------------------------------------------------------
   // Memory (mate memory)

package/lib/yoke/acp-process-manager.js

@@ -46,7 +46,7 @@ AcpProcessManager.prototype.start = function() {
       var args = self.opts.args ? self.opts.args.slice() : [];
       var env = Object.assign({}, process.env, self.opts.env || {});
 
-      self._log("Spawning:", self.executablePath, args.join(" "));
+      self._log("Spawning:", self.executablePath, "(" + args.length + " arguments; values omitted)");
       self.proc = spawn(self.executablePath, args, {
         stdio: ["pipe", "pipe", "pipe"],
         env: env,
@@ -82,7 +82,7 @@ AcpProcessManager.prototype.start = function() {
         try {
           self._handleMessage(JSON.parse(line));
         } catch (e) {
-          self._error("Failed to parse line:", line.substring(0, 200));
+          self._error("Failed to parse protocol message (content omitted)");
         }
       });
       self.rl.on("close", function() {