clay-server 4.3.0 → 4.3.1-beta.2

package/lib/project-file-http.js

@@ -0,0 +1,56 @@
+var fs = require("fs");
+var path = require("path");
+var attachRequestAccess = require("./project-request-access").attachRequestAccess;
+var resolveFilePath = require("./project-file-path").resolveFilePath;
+var fileError = require("./project-file-path").fileError;
+
+var MIME_TYPES = {
+  ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+  ".gif": "image/gif", ".webp": "image/webp", ".svg": "image/svg+xml",
+  ".bmp": "image/bmp", ".ico": "image/x-icon",
+};
+
+function attachFileHTTP(ctx) {
+  var access = ctx.requestAccess || attachRequestAccess(Object.assign({}, ctx, {
+    getOsUserInfoForWs: ctx.getOsUserInfoForReq,
+  }));
+
+  function handleHTTP(req, res, urlPath) {
+    var download = urlPath.startsWith("/api/file/download?");
+    if (req.method !== "GET" || (!download && !urlPath.startsWith("/api/file?"))) return false;
+    try {
+      var scope = access.fileScope(req);
+      var requested = new URLSearchParams(urlPath.substring(urlPath.indexOf("?"))).get("path");
+      var file = resolveFilePath(ctx.cwd, requested, scope);
+      var mime = MIME_TYPES[path.extname(file).toLowerCase()];
+      if (!download && !mime) {
+        res.writeHead(403); res.end("Only image files"); return true;
+      }
+      var content = scope.identity ? ctx.fsAsUser("read_binary", { file: file }, scope.identity).buffer : fs.readFileSync(file);
+      var headers = {
+        "Content-Type": download ? "application/octet-stream" : mime,
+        "Content-Length": content.length,
+        "Cache-Control": "no-store",
+        "X-Content-Type-Options": "nosniff",
+      };
+      if (download) {
+        var name = path.basename(requested).replace(/[\x00-\x1f\x7f"\\]/g, "_") || "download";
+        var ascii = name.replace(/[^\x20-\x7e]/g, "_");
+        var encoded = encodeURIComponent(name).replace(/[!'()*]/g, function (character) {
+          return "%" + character.charCodeAt(0).toString(16).toUpperCase();
+        });
+        headers["Content-Disposition"] = "attachment; filename=\"" + ascii + "\"; filename*=UTF-8''" + encoded;
+      }
+      res.writeHead(200, headers);
+      res.end(content);
+    } catch (error) {
+      var result = fileError(error);
+      res.writeHead(result.status, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" });
+      res.end(result.message);
+    }
+    return true;
+  }
+  return { handleHTTP: handleHTTP };
+}
+
+module.exports = { attachFileHTTP: attachFileHTTP };

package/lib/project-file-path.js

@@ -1,13 +1,49 @@
 var path = require("path");
+var fs = require("fs");
 
-// Resolve a file-browser target in the caller's project namespace. Ordinary
-// mode delegates to safePath, which enforces the realpath/symlink boundary.
-// OS-user mode deliberately returns the project-relative absolute target and
-// leaves access enforcement to the mapped user's filesystem operation.
-function resolveFilePath(cwd, requested, safePath, osUserInfo) {
-  if (typeof requested !== "string" || !requested) return null;
-  if (osUserInfo) return path.resolve(cwd, requested);
-  return typeof safePath === "function" ? safePath(cwd, requested) : null;
+function failure(code, message) {
+  var error = new Error(message);
+  error.code = code;
+  return error;
 }
 
-module.exports = { resolveFilePath: resolveFilePath };
+function inside(base, target) {
+  var relative = path.relative(base, target);
+  return relative !== ".." && !relative.startsWith(".." + path.sep) && !path.isAbsolute(relative);
+}
+
+// Scope is server-derived for each request. In personal and mapped OS-user
+// modes, the actual filesystem operation enforces read/write permissions.
+// Unmapped multi-user deployments retain the project and symlink boundary.
+function resolveFilePath(cwd, requested, scope) {
+  if (typeof requested !== "string" || !requested || requested.indexOf("\0") !== -1) {
+    throw failure("INVALID_PATH", "Invalid file path");
+  }
+  var resolved = path.resolve(cwd, requested);
+  if (scope && scope.projectBound === false) return resolved;
+  if (!inside(path.resolve(cwd), resolved)) {
+    throw failure("FILE_SCOPE", "This file is outside your project's allowed file scope");
+  }
+  var base = fs.realpathSync(cwd);
+  var real = fs.realpathSync(resolved);
+  if (!inside(base, real)) {
+    throw failure("FILE_SCOPE", "This file links outside your project's allowed file scope");
+  }
+  return real;
+}
+
+function fileError(error) {
+  var code = error.code;
+  // OS-user helpers report child-process failures through stderr.
+  if (error.stderr) {
+    var match = String(error.stderr).match(/code: ['"](EACCES|EPERM|ENOENT|ENOTDIR)['"]/);
+    if (match) code = match[1];
+  }
+  if (code === "ENOENT" || code === "ENOTDIR") return { code: code, status: 404, message: "File or folder not found" };
+  if (code === "EACCES" || code === "EPERM") return { code: code, status: 403, message: "The operating system denied access for your account" };
+  if (code === "INVALID_PATH") return { code: code, status: 400, message: error.message };
+  if (code === "FILE_SCOPE" || code === "FILE_FORBIDDEN" || code === "OS_IDENTITY") return { code: code, status: 403, message: error.message };
+  return { code: code || "FILE_ERROR", status: 500, message: error.message || "File operation failed" };
+}
+
+module.exports = { resolveFilePath: resolveFilePath, fileError: fileError, failure: failure };

package/lib/project-file-watch.js

@@ -6,34 +6,28 @@ var resolveFilePath = require("./project-file-path").resolveFilePath;
  * Attach file/directory watcher engine to a project context.
  *
  * ctx fields:
- *   cwd, send, sendTo, safePath, BINARY_EXTS, FS_MAX_SIZE, IGNORED_DIRS, requestAccess, fsAsUser
+ *   cwd, send, sendTo, BINARY_EXTS, FS_MAX_SIZE, IGNORED_DIRS, requestAccess, fsAsUser
  */
 function attachFileWatch(ctx) {
   var cwd = ctx.cwd;
   var send = ctx.send;
   var sendTo = ctx.sendTo;
-  var safePath = ctx.safePath;
   var BINARY_EXTS = ctx.BINARY_EXTS;
   var FS_MAX_SIZE = ctx.FS_MAX_SIZE;
   var IGNORED_DIRS = ctx.IGNORED_DIRS;
   var access = ctx.requestAccess;
   var osUsers = !!ctx.osUsers;
 
-  function identityFor(client) {
+  function scopeFor(client) {
     if (!access) {
       if (osUsers) throw new Error("OS user identity is unavailable");
-      return null;
+      return { identity: null, projectBound: true };
     }
-    if (!access.canUseFiles(client)) throw new Error("File browser access is not permitted");
-    var identity = access.osIdentity(client);
-    if (osUsers && !identity) throw new Error("OS user identity is unavailable");
-    return identity;
+    return access.fileScope(client);
   }
 
-  function checkedPath(relPath, identity) {
-    var resolved = resolveFilePath(cwd, relPath, safePath, osUsers ? identity : null);
-    if (!resolved) throw new Error("Access denied");
-    return resolved;
+  function checkedPath(relPath, scope) {
+    return resolveFilePath(cwd, relPath, scope);
   }
 
   // --- File watcher ---
@@ -68,8 +62,9 @@ function attachFileWatch(ctx) {
   }
 
   function readFileSnapshot(client, relPath) {
-    var identity = identityFor(client);
-    var absPath = checkedPath(relPath, identity);
+    var scope = scopeFor(client);
+    var identity = scope.identity;
+    var absPath = checkedPath(relPath, scope);
     var stat = identity ? ctx.fsAsUser("stat", { file: absPath }, identity) : fs.statSync(absPath);
     var ext = path.extname(absPath).toLowerCase();
     if (stat.size > FS_MAX_SIZE || BINARY_EXTS.has(ext)) return null;
@@ -107,10 +102,8 @@ function attachFileWatch(ctx) {
       relPath = client;
       client = null;
     }
-    var identity;
-    try { identity = identityFor(client); } catch (error) { return Promise.resolve(false); }
-    var absPath = resolveFilePath(cwd, relPath, safePath, osUsers ? identity : null);
-    if (!absPath) return Promise.resolve(false);
+    var absPath;
+    try { absPath = checkedPath(relPath, scopeFor(client)); } catch (error) { return Promise.resolve(false); }
     var key = client || "_legacy";
     var existing = fileWatchers.get(key);
     if (existing && existing.relPath === relPath) return existing.ready;
@@ -186,8 +179,9 @@ function attachFileWatch(ctx) {
   var dirWatchers = new Map();
 
   function readDirectory(client, relPath) {
-    var identity = identityFor(client);
-    var absPath = checkedPath(relPath, identity);
+    var scope = scopeFor(client);
+    var identity = scope.identity;
+    var absPath = checkedPath(relPath, scope);
     var items = identity ? ctx.fsAsUser("list", { dir: absPath }, identity) :
       fs.readdirSync(absPath, { withFileTypes: true }).map(function (item) {
         return { name: item.name, isDir: item.isDirectory() };
@@ -204,12 +198,12 @@ function attachFileWatch(ctx) {
     var subscriptions = dirWatchers.get(client);
     if (!subscriptions) { subscriptions = new Map(); dirWatchers.set(client, subscriptions); }
     if (subscriptions.has(relPath)) return;
-    var identity;
+    var scope;
     try {
-      identity = identityFor(client);
+      scope = scopeFor(client);
       readDirectory(client, relPath);
       var entry = { watcher: null, debounce: null };
-      entry.watcher = fs.watch(checkedPath(relPath, identity), function () {
+      entry.watcher = fs.watch(checkedPath(relPath, scope), function () {
         clearTimeout(entry.debounce);
         entry.debounce = setTimeout(function () {
           try {

package/lib/project-filesystem.js

@@ -3,6 +3,7 @@ var path = require("path");
 var attachRequestAccess = require("./project-request-access").attachRequestAccess;
 var attachFileHistory = require("./project-file-history").attachFileHistory;
 var resolveFilePath = require("./project-file-path").resolveFilePath;
+var fileError = require("./project-file-path").fileError;
 
 /**
  * Attach filesystem-related message handlers to a project context.
@@ -11,7 +12,6 @@ var resolveFilePath = require("./project-file-path").resolveFilePath;
  *   cwd, slug, osUsers
  *   sm (session manager)
  *   send, sendTo
- *   safePath, safeAbsPath (functions)
  *   getOsUserInfoForWs (function)
  *   startFileWatch, stopFileWatch, startDirWatch (from _fileWatch)
  *   usersModule, fsAsUser
@@ -23,8 +23,6 @@ function attachFilesystem(ctx) {
   var cwd = ctx.cwd;
   var slug = ctx.slug;
   var sendTo = ctx.sendTo;
-  var safePath = ctx.safePath;
-  var safeAbsPath = ctx.safeAbsPath;
   var startFileWatch = ctx.startFileWatch;
   var stopFileWatch = ctx.stopFileWatch;
   var startDirWatch = ctx.startDirWatch;
@@ -41,26 +39,26 @@ function attachFilesystem(ctx) {
   var fileHistory = attachFileHistory(ctx, access);
 
   function handleFilesystemMessage(ws, msg) {
-    // Unsubscription must remain available after permission revocation.
+    var fileScope;
+    var fileTarget;
+    // Resolve live authority before every operation; never trust message roles.
     if (/^fs_/.test(msg.type) && msg.type !== "fs_unwatch") {
-      if (!access.canUseFiles(ws)) {
-        sendTo(ws, { type: msg.type + "_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, error: "File browser access is not permitted" });
-        return true;
-      }
-      try { access.osIdentity(ws); } catch (e) {
-        sendTo(ws, { type: msg.type + "_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, error: e.message });
+      try {
+        fileScope = access.fileScope(ws);
+        if (/^fs_(list|read|write|watch)$/.test(msg.type)) {
+          fileTarget = resolveFilePath(cwd, msg.type === "fs_list" ? msg.path || "." : msg.path, fileScope);
+        }
+      } catch (e) {
+        var denied = fileError(e);
+        sendTo(ws, { type: msg.type + "_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, ok: false, error: denied.message, errorCode: denied.code });
         return true;
       }
     }
 
     // --- fs_list ---
     if (msg.type === "fs_list") {
-      var fsListIdentity = access.osIdentity(ws);
-      var fsDir = resolveFilePath(cwd, msg.path || ".", safePath, fsListIdentity);
-      if (!fsDir) {
-        sendTo(ws, { type: "fs_list_result", path: msg.path, entries: [], error: "Access denied" });
-        return true;
-      }
+      var fsListIdentity = fileScope.identity;
+      var fsDir = fileTarget;
       try {
         var fsListUserInfo = fsListIdentity;
         var entries = [];
@@ -92,7 +90,7 @@ function attachFilesystem(ctx) {
         // Auto-watch the directory for changes
         startDirWatch(ws, msg.path || ".");
       } catch (e) {
-        sendTo(ws, { type: "fs_list_result", path: msg.path, entries: [], error: e.message });
+        sendTo(ws, { type: "fs_list_result", path: msg.path, entries: [], error: fileError(e).message, errorCode: fileError(e).code });
       }
       return true;
     }
@@ -138,19 +136,15 @@ function attachFilesystem(ctx) {
         walkDir(cwd, "");
         sendTo(ws, { type: "fs_search_result", query: msg.query, entries: searchResults });
       } catch (e) {
-        sendTo(ws, { type: "fs_search_result", query: msg.query, entries: [], error: e.message });
+        sendTo(ws, { type: "fs_search_result", query: msg.query, entries: [], error: fileError(e).message, errorCode: fileError(e).code });
       }
       return true;
     }
 
     // --- fs_read ---
     if (msg.type === "fs_read") {
-      var fsReadIdentity = access.osIdentity(ws);
-      var fsFile = resolveFilePath(cwd, msg.path, safePath, fsReadIdentity);
-      if (!fsFile) {
-        sendTo(ws, { type: "fs_read_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, error: "Access denied" });
-        return true;
-      }
+      var fsReadIdentity = fileScope.identity;
+      var fsFile = fileTarget;
       try {
         var fsReadUserInfo = fsReadIdentity;
         var ext = path.extname(fsFile).toLowerCase();
@@ -185,19 +179,15 @@ function attachFilesystem(ctx) {
           sendTo(ws, { type: "fs_read_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, content: content, size: stat.size });
         }
       } catch (e) {
-        sendTo(ws, { type: "fs_read_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, error: e.message });
+        sendTo(ws, { type: "fs_read_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, error: fileError(e).message, errorCode: fileError(e).code });
       }
       return true;
     }
 
     // --- fs_write ---
     if (msg.type === "fs_write") {
-      var fsWriteIdentity = access.osIdentity(ws);
-      var fsWriteFile = resolveFilePath(cwd, msg.path, safePath, fsWriteIdentity);
-      if (!fsWriteFile) {
-        sendTo(ws, { type: "fs_write_result", path: msg.path, ok: false, error: "Access denied" });
-        return true;
-      }
+      var fsWriteIdentity = fileScope.identity;
+      var fsWriteFile = fileTarget;
       try {
         var fsWriteUserInfo = fsWriteIdentity;
         if (fsWriteUserInfo) {
@@ -207,7 +197,7 @@ function attachFilesystem(ctx) {
         }
         sendTo(ws, { type: "fs_write_result", path: msg.path, ok: true });
       } catch (e) {
-        sendTo(ws, { type: "fs_write_result", path: msg.path, ok: false, error: e.message });
+        sendTo(ws, { type: "fs_write_result", path: msg.path, ok: false, error: fileError(e).message, errorCode: fileError(e).code });
       }
       return true;
     }

package/lib/project-http.js

@@ -6,24 +6,9 @@ var { execFileSync, spawn } = require("child_process");
 var defaultFsAsUser = require("./os-users").fsAsUser;
 var defaultUsersModule = require("./users");
 var gitCli = require("./git-cli");
-var resolveFilePath = require("./project-file-path").resolveFilePath;
+var attachFileHTTP = require("./project-file-http").attachFileHTTP;
 var sharedSkillDiscovery = require("./yoke/skill-discovery");
 
-var IMAGE_EXTS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".bmp", ".ico"]);
-var MIME_TYPES = {
-  ".html": "text/html",
-  ".css": "text/css",
-  ".js": "application/javascript",
-  ".json": "application/json",
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".svg": "image/svg+xml",
-  ".bmp": "image/bmp",
-  ".ico": "image/x-icon",
-};
 var MAX_UPLOAD_BYTES = 50 * 1024 * 1024; // 50 MB
 
 function parseJsonBody(req) {
@@ -42,7 +27,7 @@ function parseJsonBody(req) {
  *
  * ctx fields:
  *   cwd, slug, project, sm, send, sendTo, imagesDir, osUsers, pushModule,
- *   safePath, safeAbsPath, getOsUserInfoForReq, sendExtensionCommandAny,
+ *   requestAccess, getOsUserInfoForReq, sendExtensionCommandAny,
  *   saveGeneratedImageToProject, _extToken, _browserTabList
  */
 function attachHTTP(ctx) {
@@ -56,8 +41,6 @@ function attachHTTP(ctx) {
   var saveGeneratedImageToProject = ctx.saveGeneratedImageToProject;
   var osUsers = ctx.osUsers;
   var pushModule = ctx.pushModule;
-  var safePath = ctx.safePath;
-  var safeAbsPath = ctx.safeAbsPath;
   var getOsUserInfoForReq = ctx.getOsUserInfoForReq;
   var fsAsUser = ctx.fsAsUser || defaultFsAsUser;
   var usersModule = ctx.usersModule || defaultUsersModule;
@@ -65,6 +48,10 @@ function attachHTTP(ctx) {
   var _extToken = ctx._extToken;
   var _browserTabList = ctx._browserTabList;
 
+  var fileHTTP = attachFileHTTP(Object.assign({}, ctx, {
+    usersModule: usersModule, fsAsUser: fsAsUser,
+  }));
+
   function handleHTTP(req, res, urlPath) {
     // Browser MCP extension bridge: forward commands to Chrome extension
     if (req.method === "POST" && urlPath === "/ext-command") {
@@ -291,92 +278,7 @@ function attachHTTP(ctx) {
       return true;
     }
 
-    // File browser: download project files
-    if (req.method === "GET" && urlPath.startsWith("/api/file/download?")) {
-      if (usersModule.isMultiUser()) {
-        var downloadUser = req._clayUser;
-        var downloadPermissions = downloadUser ? usersModule.getEffectivePermissions(downloadUser, osUsers) : null;
-        if (!downloadPermissions || !downloadPermissions.fileBrowser) {
-          res.writeHead(403, { "Content-Type": "text/plain; charset=utf-8" });
-          res.end("File browser access is not permitted");
-          return true;
-        }
-      }
-
-      var downloadQueryIndex = urlPath.indexOf("?");
-      var downloadParams = new URLSearchParams(urlPath.substring(downloadQueryIndex));
-      var downloadPath = downloadParams.get("path");
-      if (!downloadPath) { res.writeHead(400); res.end("Missing path"); return true; }
-      var downloadUserInfo = getOsUserInfoForReq(req);
-      if (osUsers && !downloadUserInfo) { res.writeHead(403); res.end("OS user identity unavailable"); return true; }
-      var downloadFile = resolveFilePath(cwd, downloadPath, safePath, downloadUserInfo);
-      if (!downloadFile) { res.writeHead(403); res.end("Access denied"); return true; }
-
-      try {
-        var downloadContent;
-        if (downloadUserInfo) {
-          downloadContent = fsAsUser("read_binary", { file: downloadFile }, downloadUserInfo).buffer;
-        } else {
-          downloadContent = fs.readFileSync(downloadFile);
-        }
-        var downloadName = path.basename(downloadPath).replace(/[\x00-\x1f\x7f"\\]/g, "_") || "download";
-        var asciiDownloadName = downloadName.replace(/[^\x20-\x7e]/g, "_");
-        var encodedDownloadName = encodeURIComponent(downloadName).replace(/[!'()*]/g, function (character) {
-          return "%" + character.charCodeAt(0).toString(16).toUpperCase();
-        });
-        var contentDisposition = "attachment; filename=\"" + asciiDownloadName + "\"; filename*=UTF-8''" + encodedDownloadName;
-        res.writeHead(200, {
-          "Content-Type": "application/octet-stream",
-          "Content-Length": downloadContent.length,
-          "Content-Disposition": contentDisposition,
-          "Cache-Control": "no-store",
-          "X-Content-Type-Options": "nosniff",
-        });
-        res.end(downloadContent);
-      } catch (e) {
-        res.writeHead(404);
-        res.end("Not found");
-      }
-      return true;
-    }
-
-    // File browser: serve project images
-    if (req.method === "GET" && urlPath.startsWith("/api/file?")) {
-      var qIdx = urlPath.indexOf("?");
-      var params = new URLSearchParams(urlPath.substring(qIdx));
-      var reqFilePath = params.get("path");
-      if (!reqFilePath) { res.writeHead(400); res.end("Missing path"); return true; }
-      if (usersModule.isMultiUser()) {
-        var imageUser = req._clayUser;
-        var imagePermissions = imageUser ? usersModule.getEffectivePermissions(imageUser, osUsers) : null;
-        if (!imagePermissions || !imagePermissions.fileBrowser) {
-          res.writeHead(403, { "Content-Type": "text/plain; charset=utf-8" });
-          res.end("File browser access is not permitted");
-          return true;
-        }
-      }
-      var fileServeUserInfo = getOsUserInfoForReq(req);
-      if (osUsers && !fileServeUserInfo) { res.writeHead(403); res.end("OS user identity unavailable"); return true; }
-      var absFile = resolveFilePath(cwd, reqFilePath, safePath, fileServeUserInfo);
-      if (!absFile) { res.writeHead(403); res.end("Access denied"); return true; }
-      var fileExt = path.extname(absFile).toLowerCase();
-      if (!IMAGE_EXTS.has(fileExt)) { res.writeHead(403); res.end("Only image files"); return true; }
-      try {
-        var fileContent;
-        if (fileServeUserInfo) {
-          var binResult = fsAsUser("read_binary", { file: absFile }, fileServeUserInfo);
-          fileContent = binResult.buffer;
-        } else {
-          fileContent = fs.readFileSync(absFile);
-        }
-        var fileMime = MIME_TYPES[fileExt] || "application/octet-stream";
-        res.writeHead(200, { "Content-Type": fileMime, "Cache-Control": "no-cache" });
-        res.end(fileContent);
-      } catch (e) {
-        res.writeHead(404); res.end("Not found");
-      }
-      return true;
-    }
+    if (fileHTTP.handleHTTP(req, res, urlPath)) return true;
 
     // Skills permission gate
     if (urlPath === "/api/install-skill" || urlPath === "/api/uninstall-skill" || urlPath === "/api/installed-skills") {

package/lib/project-pair-lifecycle.js

@@ -162,6 +162,15 @@ function attachPairLifecycle(ctx) {
     return null;
   }
   function partnerStatus(caller, args) {
+    var group = caller && store.groupForMember(caller.localId);
+    var roles = splitRoles.normalizePair(group && group.pair, group && group.members);
+    if ((!args || args.workerId == null) && roles.ok && roles.kind !== "adhoc" && roles.workerIds.length > 1) {
+      var workers = roles.workerIds.map(function (workerId) {
+        return partnerStatus(caller, { workerId: workerId });
+      });
+      return { driverId: caller.localId, workerIds: roles.workerIds.slice(), workers: workers,
+        instruction: "Pass the selected workerId to targeted partner tools. Call partner_status without workerId to rediscover current Workers." };
+    }
     var resolved = resolveDriverPair(caller, args, { readOnly: true });
     var worker = resolved.worker;
     var blocked = turnControl.blockedReason(caller) || replaceBlockedReason(worker);

package/lib/project-request-access.js

@@ -1,4 +1,5 @@
 // Shared authorization for project requests and long-lived file subscriptions.
+var fileFailure = require("./project-file-path").failure;
 function attachRequestAccess(ctx) {
   var users = ctx.usersModule;
   var opts = ctx.opts || {};
@@ -9,7 +10,7 @@ function attachRequestAccess(ctx) {
 
   function userFor(ws) {
     var user = ws && ws._clayUser;
-    if (user && users.findUserById) return users.findUserById(user.id);
+    if (user && users && users.findUserById) return users.findUserById(user.id);
     return user || null;
   }
 
@@ -53,14 +54,20 @@ function attachRequestAccess(ctx) {
   function osIdentity(ws) {
     if (!ctx.osUsers) return null;
     var user = userFor(ws);
-    if (!user || !user.linuxUser) throw new Error("OS user identity is unavailable");
+    if (!user || !user.linuxUser) throw fileFailure("OS_IDENTITY", "OS user identity is unavailable");
     var info = ctx.getOsUserInfoForWs({ _clayUser: user });
-    if (!info) throw new Error("OS user identity is unavailable");
+    if (!info) throw fileFailure("OS_IDENTITY", "OS user identity is unavailable");
     return info;
   }
 
+  function fileScope(ws) {
+    if (!canUseFiles(ws)) throw fileFailure("FILE_FORBIDDEN", "File browser access is not permitted");
+    var identity = osIdentity(ws);
+    return { identity: identity, projectBound: isMultiUser() && !identity };
+  }
+
   return { permitMessage: permitMessage, canAccessProject: canAccessProject, hasPermission: hasPermission,
-    canUseFiles: canUseFiles, isAdmin: isAdmin, canReadSession: canReadSession, osIdentity: osIdentity };
+    canUseFiles: canUseFiles, isAdmin: isAdmin, canReadSession: canReadSession, osIdentity: osIdentity, fileScope: fileScope };
 }
 
 module.exports = { attachRequestAccess: attachRequestAccess };

package/lib/project-session-pair-prompt.js

@@ -13,6 +13,11 @@ function attachSessionPairPrompt(ctx) {
     var result = "";
     if (group && group.pair && group.pair.driverId === session.localId) {
       result = prompts.DRIVER_CORE + " " + ctx.workerProposal().getSystemPrompt(session);
+      if (roles && roles.driver === session) {
+        result += " Current configured Worker handles: " + roles.workers.map(function (worker) {
+          return "workerId=" + worker.localId + " (" + (worker.title || "Worker") + ")";
+        }).join(", ") + ". Call partner_status without workerId to rediscover current Workers; pass workerId for targeted operations.";
+      }
       if (driverOrchestration.isHighTierDriverSession(session, ctx.sm)) result += " " + prompts.DRIVER_DELEGATION;
     } else if (!group && !ctx.isMate && driverEligibility.isEligibleDriverSession(session, ctx.sm) &&
         driverOrchestration.isHighTierDriverSession(session, ctx.sm)) {

package/lib/project-worker-proposal-runner.js

@@ -36,6 +36,8 @@ function attachProposalRunner(ctx) {
     } else {
       followup = "[Split Worker execution failed]\nThe existing Split Worker may still be reusable. Inspect partner_status and send a narrower follow-up with send_to_partner when the Worker and pair still exist; do not replace it merely because its task or transport failed. Retry replacement only when the replacement transaction reports that no new Worker was created and the failure is explicitly safe to retry.\n\n" + (result.error || result.response || "Unknown Split Worker error.");
     }
+    followup += "\n\nWorker handle for this execution: workerId=" + proposal.workerId +
+      ". Use this workerId for follow-up operations while it remains configured. Call partner_status without workerId to discover current Worker handles after replacement or reconnect.";
     await resumeDriver(session, followup);
   }
 

package/lib/project-worker-proposal.js

@@ -463,7 +463,7 @@ function attachWorkerProposal(ctx) {
 
   function getSystemPrompt(session) {
     if (creationProposal.canMountProposal(session) && !isEligible(session)) {
-      return "This Driver may configure one additional Split Worker through propose_worker. With two Workers, pass workerId to every targeted partner, queue, interrupt, replacement, close, permission, and status operation. Give each Worker independent file ownership and bounded work. Do not assign simultaneous overlapping file edits unless the work is explicitly separated, such as by distinct paths or worktrees.";
+      return "This Driver may configure one additional Split Worker through propose_worker. With two Workers, pass workerId to every targeted partner, queue, interrupt, replacement, close, permission, and targeted status operation. Call partner_status without workerId to discover current Worker handles. Give each Worker independent file ownership and bounded work. Do not assign simultaneous overlapping file edits unless the work is explicitly separated, such as by distinct paths or worktrees.";
     }
     if (!isEligible(session) || !driverOrchestration.isHighTierDriverSession(session, sm)) return "";
     return "For implementation-heavy work, use propose_worker before substantial execution. Work is implementation-heavy when it spans multiple modules, crosses client/server/data boundaries, requires a migration, or contains independent investigation and execution. Do not skip delegation merely because you can implement it yourself; preserve the Driver for decomposition, runtime selection, judgment, review, and integration. The user's explicit request to work directly takes precedence, and work that must remain sequential in this session stays here. Recommend an exact available vendor, model, and effort, and give a concise recommendationRationale explaining why all three fit the task. Clay always records and shows the runtime configuration card. In full-access mode Clay may auto-accept that exact validated recommendation; otherwise it waits for the user's explicit choice. After posting, end the turn. If accepted, Clay creates the exact Driver/Split Worker pair and delegates the proposed task once. If declined, continue in this Driver session. Do not call send_to_partner while unpaired.";

package/lib/project.js

@@ -2481,6 +2481,7 @@ function createProjectContext(opts) {
 
   // --- HTTP handler (delegated to project-http.js) ---
   var _http = attachHTTP({
+    requestAccess: _requestAccess,
     cwd: cwd,
     slug: slug,
     project: title || project,

package/lib/public/css/pane.css

@@ -73,13 +73,11 @@ body.pane-mode #input-area {
   display: flex;
 }
 
-/* A configured two-Worker group is a deliberate workspace hierarchy: the
-   Driver gets the broad working canvas, while both Workers remain visible as
-   equal-height execution surfaces on the right. Legacy/ad-hoc two-pane
-   splits keep the ordinary equal columns below. */
+/* Keep the same equal columns when adding a second Worker; only the
+   Worker column divides into two equal-height execution surfaces. */
 #split-host:has(.split-pane-role-worker:nth-of-type(3)) {
   display: grid;
-  grid-template-columns: minmax(0, 3fr) minmax(260px, 2fr);
+  grid-template-columns: repeat(2, minmax(0, 1fr));
   grid-template-rows: repeat(2, minmax(0, 1fr));
   gap: 1px;
   background: var(--border-subtle);

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

@@ -63,8 +63,8 @@ function getToolDefs(handlers, options) {
     },
     {
       name: "partner_status",
-      description: "Bounded capacity and continuity report for your Split Worker, for deciding reuse against replacement: context tokens used and the ratio of its window, current task and activity, vendor/model/effort, history size and idle time, whether it is safe to replace right now, and your own recorded results for earlier Worker generations. Returns no transcript. Prefer this over reading turns when you only need to decide.",
-      inputSchema: buildShape({ workerId: { type: "number", description: "Optional exact Worker session id; required when multiple Workers are configured." } }),
+      description: "Bounded capacity and continuity report for your Split Worker, for deciding reuse against replacement: context tokens used and the ratio of its window, current task and activity, vendor/model/effort, history size and idle time, whether it is safe to replace right now, and your own recorded results for earlier Worker generations. Returns no transcript. Prefer this over reading turns when you only need to decide. Omit workerId to discover all configured Workers and their current numeric handles; pass workerId for one Worker.",
+      inputSchema: buildShape({ workerId: { type: "number", description: "Optional exact Worker session id. Omit to list all configured Workers and their current handles." } }),
       handler: function (args) { return handlers.status(args || {}); },
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clay-server",
-  "version": "4.3.0",
+  "version": "4.3.1-beta.2",
   "description": "Self-hosted team workspace for Claude Code and Codex. Multi-user, browser-based, with persistent AI mates.",
   "bin": {
     "clay-server": "./bin/cli.js"