clay-server 5.2.0-beta.3 → 5.2.0-beta.5

package/lib/project-debate.js

@@ -774,6 +774,7 @@ function attachDebate(ctx) {
       var identityMate = matesModule.getMate(debate.mateCtx, msg.mateId);
       var identityProfile = identityMate && identityMate.profile ? identityMate.profile : (identityMate || {});
       if (!msg.mateName) msg.mateName = identity.name;
+      if (!msg.avatarCatalogId) msg.avatarCatalogId = identityProfile.avatarCatalogId || "";
       if (!msg.avatarStyle) msg.avatarStyle = identity.avatarStyle;
       if (!msg.avatarSeed) msg.avatarSeed = identity.avatarSeed;
       if (!msg.avatarColor) msg.avatarColor = identity.avatarColor;

package/lib/project-delegated-follow-up.js

@@ -12,7 +12,7 @@ function unsafeReason(session, isPaired) {
   if (session.homeDebatePlanning || session.homeDebatePhase || session.debateSetupMode || session.debateState || session._debate) return "Debate sessions cannot receive project follow-ups.";
   if (session.loop || session.spawn || session.handoff || session.assignment || session.singleTurn || session._pairDelegation || isPaired) return "Orchestrated sessions cannot receive project follow-ups.";
   if (session.dangerouslySkipPermissions || session.permissionMode === "bypassPermissions") return "Full-access sessions cannot receive project follow-ups.";
-  if (session.destroying || session.scheduledMessage || session.rateLimitAutoContinuePending || session.taskStopRequested || session._runtimeRefreshRequested || session.pendingPush && session.pendingPush.length) return "Target session is not safely resumable right now.";
+  if (session.destroying || session.scheduledMessage || session.rateLimitAutoContinuePending || session.taskStopRequested || session._pendingMessageDrainPaused || session._runtimeRefreshRequested || session.pendingPush && session.pendingPush.length) return "Target session is not safely resumable right now.";
   return "";
 }
 
@@ -36,6 +36,7 @@ function attachDelegatedFollowUp(ctx) {
     var paired = !!(ctx.isPairedSession && ctx.isPairedSession(session));
     var reason = unsafeReason(session, paired);
     if (reason) throw new Error(reason);
+    if (ctx.isPendingQueuePaused && ctx.isPendingQueuePaused(session)) throw new Error("The Driver queue is stopped; explicit owner resume is required.");
     if (!ctx.canResumeVendor(session.vendor)) throw new Error("Target session provider cannot safely resume this conversation.");
     return { session: session, sessionRef: targetSessionRef, title: session.title || "Existing session" };
   }

package/lib/project-directory-claim.js

@@ -0,0 +1,65 @@
+// Reserve a new project directory before running Git or changing ownership.
+// Filesystem identity checks also keep failed attempts from deleting targets
+// replaced by another actor. Hostile OS/root mutation is outside this boundary.
+var fs = require("fs");
+var path = require("path");
+
+function canonical(candidate) {
+  var current = path.resolve(candidate);
+  var missing = [];
+  while (true) {
+    try { return path.join.apply(path, [fs.realpathSync(current)].concat(missing)); }
+    catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      // A dangling symlink is an existing object, not a missing directory.
+      try { fs.lstatSync(current); throw new Error("A project path contains a dangling symlink."); }
+      catch (statError) { if (statError.code !== "ENOENT") throw statError; }
+      var parent = path.dirname(current);
+      if (parent === current) throw error;
+      missing.unshift(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
+function inside(root, candidate) {
+  var relative = path.relative(root, candidate);
+  return relative !== ".." && relative.indexOf(".." + path.sep) !== 0 && !path.isAbsolute(relative);
+}
+
+function rejectIntersection(target, projects, userId) {
+  (projects || []).forEach(function (project) {
+    var root = canonical(project.path);
+    if (target === root || inside(target, root) || (project.ownerId !== userId && inside(root, target))) {
+      throw new Error("The destination intersects a registered project.");
+    }
+  });
+}
+
+function claim(options) {
+  var slug = options.slug;
+  if (!slug || slug === "." || slug === ".." || path.basename(slug) !== slug) throw new Error("Invalid project directory name.");
+  var base = canonical(options.baseDir);
+  var target = path.join(base, slug);
+  rejectIntersection(target, options.projects, options.userId);
+  fs.mkdirSync(base, { recursive: true });
+  if (fs.realpathSync(options.baseDir) !== base) throw new Error("The project base directory changed.");
+  rejectIntersection(target, options.projects, options.userId);
+  // EEXIST rejects directories, files, symlinks and concurrent claims alike.
+  fs.mkdirSync(target, { mode: 0o700 });
+  var identity = fs.lstatSync(target);
+  function assertOwned() {
+    var current = fs.lstatSync(target);
+    if (!current.isDirectory() || current.isSymbolicLink() || current.dev !== identity.dev || current.ino !== identity.ino || fs.realpathSync(base) !== base) {
+      throw new Error("The claimed project directory changed.");
+    }
+  }
+  function cleanup() {
+    try { assertOwned(); } catch (error) { return false; }
+    fs.rmSync(target, { recursive: true });
+    return true;
+  }
+  return { path: target, assertOwned: assertOwned, cleanup: cleanup };
+}
+
+module.exports = { claim: claim, canonical: canonical };

package/lib/project-file-operations.js

@@ -0,0 +1,61 @@
+// Shared file-viewer effects. Authority and scope are derived by each caller.
+var fs = require('fs'), path = require('path'), crypto = require('crypto');
+var resolve = require('./project-file-path').resolveFilePath;
+function hash(content) { return crypto.createHash('sha256').update(content).digest('hex'); }
+function attachFileOperations(ctx) {
+  function list(scope, requested) {
+    var dir = resolve(ctx.cwd, requested || '.', scope);
+    var items = scope.identity ? ctx.fsAsUser('list', { dir: dir }, scope.identity) : fs.readdirSync(dir, { withFileTypes: true }).map(function (item) { return { name: item.name, isDir: item.isDirectory() }; });
+    return items.filter(function (item) { return !item.isDir || !ctx.IGNORED_DIRS.has(item.name); }).map(function (item) { return { name: item.name, type: item.isDir ? 'dir' : 'file', path: path.relative(ctx.cwd, path.join(dir, item.name)).split(path.sep).join('/') }; });
+  }
+  function read(scope, requested) {
+    var file = resolve(ctx.cwd, requested, scope), identity = scope.identity;
+    var stat = identity ? ctx.fsAsUser('stat', { file: file }, identity) : fs.statSync(file);
+    if (stat.size > ctx.FS_MAX_SIZE) return { binary: true, size: stat.size, error: 'File too large (' + (stat.size / 1024 / 1024).toFixed(1) + ' MB)' };
+    var ext = path.extname(file).toLowerCase();
+    if (ctx.BINARY_EXTS.has(ext)) {
+      var binary = { binary: true, size: stat.size };
+      if (ctx.IMAGE_EXTS.has(ext)) binary.imageUrl = 'api/file?path=' + encodeURIComponent(requested);
+      return binary;
+    }
+    return { content: identity ? ctx.fsAsUser('read', { file: file, readContent: true }, identity).content : fs.readFileSync(file, 'utf8'), size: stat.size };
+  }
+  function snapshot(scope, requested) {
+    var file = resolve(ctx.cwd, requested, scope), stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 65536) throw new Error('Select a regular, singly linked text file of at most 64 KB.');
+    var result = read(scope, requested);
+    if (result.binary || typeof result.content !== 'string' || result.content.indexOf('\0') >= 0) throw new Error('Binary files are unavailable for canonical editing.');
+    return { dev: stat.dev, ino: stat.ino, mode: stat.mode, uid: stat.uid, gid: stat.gid, size: stat.size, mtime: stat.mtimeMs, hash: hash(result.content) };
+  }
+  function write(scope, requested, content, control) {
+    var file = resolve(ctx.cwd, requested, scope), attempted = false;
+    if (!control) {
+      if (scope.identity) ctx.fsAsUser('write', { file: file, content: content }, scope.identity);
+      else fs.writeFileSync(file, content, 'utf8');
+      return { ok: true };
+    }
+    if (typeof fs.constants.O_NOFOLLOW !== 'number') throw new Error('Canonical editing requires no-follow file descriptors on this platform.');
+    control.revalidate();
+    if (JSON.stringify(snapshot(scope, requested)) !== JSON.stringify(control.expected)) throw new Error('The exact file revision changed.');
+    try {
+      attempted = true;
+      if (scope.identity) ctx.fsAsUser('write_exact', { file: file, content: content, expected: control.expected, root: fs.realpathSync(ctx.cwd) }, scope.identity);
+      else {
+        var fd = fs.openSync(file, fs.constants.O_RDWR | fs.constants.O_NOFOLLOW);
+        try {
+          var stat = fs.fstatSync(fd), expected = control.expected;
+          if (!stat.isFile() || stat.nlink !== 1 || stat.dev !== expected.dev || stat.ino !== expected.ino || stat.mode !== expected.mode || stat.uid !== expected.uid || stat.gid !== expected.gid || stat.size !== expected.size || stat.mtimeMs !== expected.mtime || hash(fs.readFileSync(fd, 'utf8')) !== expected.hash) throw new Error('The open file revision changed.');
+          control.revalidate();
+          fs.ftruncateSync(fd, 0);
+          var bytes = Buffer.from(content, 'utf8'), offset = 0;
+          while (offset < bytes.length) { var written = fs.writeSync(fd, bytes, offset, bytes.length - offset, offset); if (!written) throw new Error('File write made no progress.'); offset += written; }
+          fs.fsyncSync(fd);
+        } finally { fs.closeSync(fd); }
+      }
+      control.revalidate();
+      return { status: 'completed', persisted: true, path: requested };
+    } catch (error) { error.productControlResult = { persisted: attempted ? 'unknown' : false, retrySafe: false, error: error.message }; throw error; }
+  }
+  return { list: list, read: read, write: write, snapshot: snapshot };
+}
+module.exports = { attachFileOperations: attachFileOperations };

package/lib/project-filesystem.js

@@ -37,6 +37,7 @@ function attachFilesystem(ctx) {
 
   var access = ctx.requestAccess || attachRequestAccess(ctx);
   var fileHistory = attachFileHistory(ctx, access);
+  var operations = require("./project-file-operations").attachFileOperations(ctx);
 
   function handleFilesystemMessage(ws, msg) {
     var fileScope;
@@ -57,40 +58,11 @@ function attachFilesystem(ctx) {
 
     // --- fs_list ---
     if (msg.type === "fs_list") {
-      var fsListIdentity = fileScope.identity;
-      var fsDir = fileTarget;
       try {
-        var fsListUserInfo = fsListIdentity;
-        var entries = [];
-        if (fsListUserInfo) {
-          // Run as target OS user to respect Linux file permissions
-          var rawEntries = fsAsUser("list", { dir: fsDir }, fsListUserInfo);
-          for (var fi = 0; fi < rawEntries.length; fi++) {
-            var re = rawEntries[fi];
-            if (re.isDir && IGNORED_DIRS.has(re.name)) continue;
-            entries.push({
-              name: re.name,
-              type: re.isDir ? "dir" : "file",
-              path: path.relative(cwd, path.join(fsDir, re.name)).split(path.sep).join("/"),
-            });
-          }
-        } else {
-          var items = fs.readdirSync(fsDir, { withFileTypes: true });
-          for (var fi = 0; fi < items.length; fi++) {
-            var item = items[fi];
-            if (item.isDirectory() && IGNORED_DIRS.has(item.name)) continue;
-            entries.push({
-              name: item.name,
-              type: item.isDirectory() ? "dir" : "file",
-              path: path.relative(cwd, path.join(fsDir, item.name)).split(path.sep).join("/"),
-            });
-          }
-        }
-        sendTo(ws, { type: "fs_list_result", path: msg.path || ".", entries: entries });
-        // Auto-watch the directory for changes
-        startDirWatch(ws, msg.path || ".");
+        sendTo(ws, { type: 'fs_list_result', path: msg.path || '.', entries: operations.list(fileScope, msg.path || '.') });
+        startDirWatch(ws, msg.path || '.');
       } catch (e) {
-        sendTo(ws, { type: "fs_list_result", path: msg.path, entries: [], error: fileError(e).message, errorCode: fileError(e).code });
+        sendTo(ws, { type: 'fs_list_result', path: msg.path, entries: [], error: fileError(e).message, errorCode: fileError(e).code });
       }
       return true;
     }
@@ -143,62 +115,15 @@ function attachFilesystem(ctx) {
 
     // --- fs_read ---
     if (msg.type === "fs_read") {
-      var fsReadIdentity = fileScope.identity;
-      var fsFile = fileTarget;
-      try {
-        var fsReadUserInfo = fsReadIdentity;
-        var ext = path.extname(fsFile).toLowerCase();
-        if (fsReadUserInfo) {
-          // Run stat and read as target OS user
-          var statResult = fsAsUser("stat", { file: fsFile }, fsReadUserInfo);
-          if (statResult.size > FS_MAX_SIZE) {
-            sendTo(ws, { type: "fs_read_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, binary: true, size: statResult.size, error: "File too large (" + (statResult.size / 1024 / 1024).toFixed(1) + " MB)" });
-            return true;
-          }
-          if (BINARY_EXTS.has(ext)) {
-            var result = { type: "fs_read_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, binary: true, size: statResult.size };
-            if (IMAGE_EXTS.has(ext)) result.imageUrl = "api/file?path=" + encodeURIComponent(msg.path);
-            sendTo(ws, result);
-            return true;
-          }
-          var readResult = fsAsUser("read", { file: fsFile, readContent: true }, fsReadUserInfo);
-          sendTo(ws, { type: "fs_read_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, content: readResult.content, size: statResult.size });
-        } else {
-          var stat = fs.statSync(fsFile);
-          if (stat.size > FS_MAX_SIZE) {
-            sendTo(ws, { type: "fs_read_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, binary: true, size: stat.size, error: "File too large (" + (stat.size / 1024 / 1024).toFixed(1) + " MB)" });
-            return true;
-          }
-          if (BINARY_EXTS.has(ext)) {
-            var result = { type: "fs_read_result", path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId, binary: true, size: stat.size };
-            if (IMAGE_EXTS.has(ext)) result.imageUrl = "api/file?path=" + encodeURIComponent(msg.path);
-            sendTo(ws, result);
-            return true;
-          }
-          var content = fs.readFileSync(fsFile, "utf8");
-          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: fileError(e).message, errorCode: fileError(e).code });
-      }
+      var metadata = { type: 'fs_read_result', path: msg.path, requestId: msg.requestId, projectSlug: msg.projectSlug, sessionId: msg.sessionId, accountId: msg.accountId };
+      try { sendTo(ws, Object.assign(metadata, operations.read(fileScope, msg.path))); }
+      catch (e) { sendTo(ws, Object.assign(metadata, { error: fileError(e).message, errorCode: fileError(e).code })); }
       return true;
     }
 
-    // --- fs_write ---
-    if (msg.type === "fs_write") {
-      var fsWriteIdentity = fileScope.identity;
-      var fsWriteFile = fileTarget;
-      try {
-        var fsWriteUserInfo = fsWriteIdentity;
-        if (fsWriteUserInfo) {
-          fsAsUser("write", { file: fsWriteFile, content: msg.content || "" }, fsWriteUserInfo);
-        } else {
-          fs.writeFileSync(fsWriteFile, msg.content || "", "utf8");
-        }
-        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: fileError(e).message, errorCode: fileError(e).code });
-      }
+    if (msg.type === 'fs_write') {
+      try { sendTo(ws, Object.assign({ type: 'fs_write_result', path: msg.path }, operations.write(fileScope, msg.path, msg.content || ''))); }
+      catch (e) { sendTo(ws, { type: 'fs_write_result', path: msg.path, ok: false, error: fileError(e).message, errorCode: fileError(e).code }); }
       return true;
     }
 
@@ -239,8 +164,8 @@ function attachFilesystem(ctx) {
         var setResult;
         try { setResult = opts.onSetProjectEnv(targetSlug, msg.envrc || ""); }
         catch (error) { sendTo(ws, { type: "set_project_env_result", slug: targetSlug, requestId: msg.requestId, ok: false, error: error.message }); return true; }
-        if (setResult.ok) onEnvironmentChanged();
-        sendTo(ws, { type: "set_project_env_result", ok: setResult.ok, slug: targetSlug, requestId: msg.requestId, error: setResult.error, timing: setResult.ok ? "Applies to newly created coding-agent processes. Active processes keep their current environment." : undefined });
+        if (setResult.ok && !setResult.runtimeRefreshed) onEnvironmentChanged();
+        sendTo(ws, Object.assign({}, setResult, { type: "set_project_env_result", slug: targetSlug, requestId: msg.requestId, timing: setResult.ok ? "Applies to newly created coding-agent processes. Active processes keep their current environment." : undefined }));
       } else {
         sendTo(ws, { type: "set_project_env_result", slug: targetSlug, requestId: msg.requestId, ok: false, error: "Not supported" });
       }
@@ -297,6 +222,7 @@ function attachFilesystem(ctx) {
 
   return {
     handleFilesystemMessage: handleFilesystemMessage,
+    productOperations: operations,
   };
 }
 

package/lib/project-full-access.js

@@ -16,7 +16,7 @@ function createFullAccessService(ctx) {
       enabled: session.permissionMode === "bypassPermissions" };
   }
   function persist(session) {
-    sm.saveSessionFile(session);
+    if (sm.saveSessionFile(session) === false) throw new Error("Could not persist permission mode.");
     sm.broadcastSessionList();
     if (typeof sm.sendToSession === "function") sm.sendToSession(session, { type: "session_full_access_changed", id: session.localId,
       enabled: session.permissionMode === "bypassPermissions", permissionMode: session.permissionMode });
@@ -55,7 +55,28 @@ function createFullAccessService(ctx) {
       throw error;
     }
   }
-  function setMode(session, mode) { return serialize(session, function () { return applyMode(session, mode); }); }
+  function setMode(session, mode, options) {
+    return serialize(session, function () {
+      if (!options || typeof options.revalidate !== "function") return applyMode(session, mode);
+      options.revalidate();
+      var observed = { revision: Number(session._permissionObservationRevision || 0), mode: session.effectivePermissionMode, reason: session.permissionModeFallbackReason };
+      return require("./session-config-transition").applySessionConfig({
+        sm: sm, session: session, revalidate: options.revalidate, method: "setPermissionMode", nativeValue: mode === "bypassPermissions" ? "default" : mode,
+        changes: function () {
+          var newer = Number(session._permissionObservationRevision || 0) !== observed.revision || session.effectivePermissionMode !== observed.mode || session.permissionModeFallbackReason !== observed.reason;
+          return { permissionMode: mode, permissionModeBeforeFullAccess: mode === "bypassPermissions" ? (session.permissionMode || sm.currentPermissionMode || "default") : null,
+            effectivePermissionMode: newer ? session.effectivePermissionMode : null, permissionModeFallbackReason: newer ? session.permissionModeFallbackReason : null };
+        },
+        publish: function () {
+          sm.broadcastSessionList();
+          if (typeof sm.sendToSession === "function") {
+            sm.sendToSession(session, { type: "session_full_access_changed", id: session.localId, enabled: mode === "bypassPermissions", permissionMode: mode });
+            sm.sendToSession(session, { type: "config_state", sessionId: session.localId, mode: mode, effectivePermissionMode: session.effectivePermissionMode || null, vendor: session.vendor || sm.defaultVendor || "claude" });
+          }
+        },
+      });
+    });
+  }
   function setEnabled(session, enabled) {
     return serialize(session, function () {
       return applyMode(session, enabled ? "bypassPermissions" : (session.permissionModeBeforeFullAccess || "default"));

package/lib/project-knowledge.js

@@ -44,21 +44,30 @@ function attachKnowledge(ctx) {
     return { type: user ? "user" : "system", userId: user ? user.id : null, displayName: user ? (user.displayName || user.username) : null };
   }
 
-  function mirror(ws, name) {
+  function mirrorActor(who, name) {
     if (!isMate) return { ok: true, names: [] };
-    var summary = mateSync.syncMateSource({ mateDir: cwd, fileName: name, baseDir: ctx.knowledgeBaseDir, actor: actor(ws) });
+    var summary = mateSync.syncMateSource({ mateDir: cwd, fileName: name, baseDir: ctx.knowledgeBaseDir, actor: who });
     return { ok: !!summary && summary.failed === 0, names: [name], error: summary && summary.errors[0] ? summary.errors[0].message : "Knowledge index synchronization failed." };
   }
 
-  function mirrorMany(ws, names) {
+  function mirror(ws, name) { return mirrorActor(actor(ws), name); }
+
+  function mirrorManyActor(who, names) {
     var failures = [];
     for (var i = 0; i < names.length; i++) {
-      var mirrored = mirror(ws, names[i]);
+      var mirrored = mirrorActor(who, names[i]);
       if (!mirrored.ok) failures.push(mirrored.error);
     }
     return { ok: failures.length === 0, names: names.slice(), error: failures[0] || null };
   }
 
+  function mirrorMany(ws, names) { return mirrorManyActor(actor(ws), names); }
+
+  function controlMirror(who, names) {
+    try { var state = mirrorManyActor(who, names); return { indexSyncPending: !state.ok, syncNames: names, syncError: state.ok ? null : state.error }; }
+    catch (error) { return { indexSyncPending: true, syncNames: names, syncError: error.message }; }
+  }
+
   function addSyncState(payload, sync) {
     if (sync.ok) return payload;
     return Object.assign(payload, { indexSyncPending: true, syncNames: sync.names, syncError: sync.error });
@@ -188,6 +197,22 @@ function attachKnowledge(ctx) {
     return databaseReady.then(function () { return combineSearch(databases.listCached({})); });
   }
 
+  function renameDocument(msg, who) {
+    var beforeMoveState = documentIndex(); var beforeMove = beforeMoveState.documents; var moveTarget = findDocument(beforeMove, msg.from, msg.documentId); var linkChanges = moveTarget ? rewriteMoveLinks(beforeMove, moveTarget, msg.name) : [];
+    var renamed = files.rename(msg.from, msg.name, msg.expectedRevision || null); var linkUpdateFailures = []; var updatedLinks = 0;
+    var updatedDocuments = []; var mirrorNames = [msg.from, renamed.name];
+    for (var u = 0; u < linkChanges.length; u++) {
+      var change = linkChanges[u]; var writeName = change.id === renamed.id ? renamed.name : change.name; var expected = change.id === renamed.id ? renamed.revision : change.revision;
+      try { var rewritten = files.save(writeName, change.content, expected); updatedLinks += change.count; updatedDocuments.push(rewritten); mirrorNames.push(rewritten.name); }
+      catch (linkError) { linkUpdateFailures.push({ name: writeName, error: linkError.message }); }
+    }
+    renamed = files.read(renamed.name);
+    var uniqueMirrorNames = mirrorNames.filter(function (name, at) { return mirrorNames.indexOf(name) === at; }); var renameSync = mirrorManyActor(who, uniqueMirrorNames);
+    return addSyncState({ type: "knowledge_renamed", id: renamed.id, from: msg.from, name: renamed.name, revision: renamed.revision,
+      content: renamed.content, updatedLinks: updatedLinks, linkUpdateFailures: linkUpdateFailures,
+      updatedDocuments: updatedDocuments.map(function (item) { return { id: item.id, name: item.name, content: item.content, revision: item.revision }; }) }, renameSync);
+  }
+
   function handleKnowledgeMessage(ws, msg) {
     if (msg.type === "knowledge_list") {
       try { var listed = listKnowledgeItems(ws); if (listed && typeof listed.then === "function") listed.then(function (items) { response(ws, msg, { type: "knowledge_list", files: items, drafts: drafts.list(ws && ws._clayUser && ws._clayUser.id || "system") }); }).catch(function (error) { failure(ws, msg, error); }); else response(ws, msg, { type: "knowledge_list", files: listed, drafts: drafts.list(ws && ws._clayUser && ws._clayUser.id || "system") }); } catch (error) { failure(ws, msg, error); }
@@ -236,19 +261,7 @@ function attachKnowledge(ctx) {
     if (msg.type === "knowledge_rename") {
       if (!requireWrite(ws, msg)) return true;
       try {
-        var beforeMoveState = documentIndex(); var beforeMove = beforeMoveState.documents; var moveTarget = findDocument(beforeMove, msg.from, msg.documentId); var linkChanges = moveTarget ? rewriteMoveLinks(beforeMove, moveTarget, msg.name) : [];
-        var renamed = files.rename(msg.from, msg.name, msg.expectedRevision || null); var linkUpdateFailures = []; var updatedLinks = 0;
-        var updatedDocuments = []; var mirrorNames = [msg.from, renamed.name];
-        for (var u = 0; u < linkChanges.length; u++) {
-          var change = linkChanges[u]; var writeName = change.id === renamed.id ? renamed.name : change.name; var expected = change.id === renamed.id ? renamed.revision : change.revision;
-          try { var rewritten = files.save(writeName, change.content, expected); updatedLinks += change.count; updatedDocuments.push(rewritten); mirrorNames.push(rewritten.name); }
-          catch (linkError) { linkUpdateFailures.push({ name: writeName, error: linkError.message }); }
-        }
-        renamed = files.read(renamed.name);
-        var uniqueMirrorNames = mirrorNames.filter(function (name, at) { return mirrorNames.indexOf(name) === at; }); var renameSync = mirrorMany(ws, uniqueMirrorNames);
-        response(ws, msg, addSyncState({ type: "knowledge_renamed", id: renamed.id, from: msg.from, name: renamed.name, revision: renamed.revision,
-          content: renamed.content, updatedLinks: updatedLinks, linkUpdateFailures: linkUpdateFailures,
-          updatedDocuments: updatedDocuments.map(function (item) { return { id: item.id, name: item.name, content: item.content, revision: item.revision }; }) }, renameSync));
+        response(ws, msg, renameDocument(msg, actor(ws)));
         sendTo(ws, { type: "knowledge_list", files: listKnowledgeFiles() });
       } catch (error) { failure(ws, msg, error); }
       return true;
@@ -357,7 +370,8 @@ function attachKnowledge(ctx) {
     return false;
   }
 
-  return { handleKnowledgeMessage: handleKnowledgeMessage, listKnowledgeFiles: listKnowledgeFiles, databases: databases };
+  var productOperations = require('./knowledge-product-operations').createKnowledgeProductOperations({ files: files, mirror: controlMirror, rename: renameDocument });
+  return { productOperations: productOperations, handleKnowledgeMessage: handleKnowledgeMessage, listKnowledgeFiles: listKnowledgeFiles, databases: databases };
 }
 
 module.exports = { attachKnowledge: attachKnowledge };

package/lib/project-lifecycle-operations.js

@@ -0,0 +1,98 @@
+// Durable operation identities and independent closure proofs survive config-save failures.
+var fs = require('fs');
+var path = require('path');
+var crypto = require('crypto');
+function attachLifecycleOperations(ctx) {
+  function operations() { return ctx.config().projectLifecycleOperations || {}; }
+  function proofFile(id) {
+    if (!/^[a-f0-9-]{36}$/.test(id)) throw new Error('Invalid lifecycle operation identity.');
+    return path.join(ctx.storageDir, 'project-lifecycle-operations', id + '.json');
+  }
+  function closed(op) {
+    try { var proof = JSON.parse(fs.readFileSync(proofFile(op.id), 'utf8')); return proof.id === op.id && proof.targets === JSON.stringify(op.targets); }
+    catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+  }
+  function confirmClosed(op) {
+    var file = proofFile(op.id); fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file + '.tmp', JSON.stringify({ id: op.id, targets: JSON.stringify(op.targets) }), { mode: 0o600 });
+    fs.renameSync(file + '.tmp', file);
+  }
+  function partial(op, error) {
+    return { ok: false, status: 'failed', action: op.action, outcome: op.restoration ? 'restoration_publication_pending' : op.action === 'remove' ? 'removal_reserved_runtime_pending' : 'publication_pending', persisted: true,
+      retrySafe: false, recoveryAction: 'reconcile', operationId: op.id, slug: op.slug, error: error || 'The saved operation needs explicit owner-reviewed reconciliation.' };
+  }
+  function begin(next, project, action, result, correlation, targets) {
+    var id = crypto.randomUUID();
+    if (action === 'remove') { project.lifecycleState = 'removing'; project.lifecycleOperationId = id; }
+    var op = { id: id, action: action, slug: project.slug, projectKnowledgeId: project.projectKnowledgeId, ownerId: correlation ? correlation.ownerId : project.ownerId || null,
+      sourceKey: correlation && correlation.sourceKey || null, expected: JSON.stringify(project), directory: ctx.directory(project.path), targets: targets || [], result: result,
+      correlation: correlation ? { key: correlation.key, fingerprint: correlation.fingerprint, ownerId: correlation.ownerId, sourceKey: correlation.sourceKey } : null, phase: 'pending' };
+    var all = Object.assign({}, next.projectLifecycleOperations || {});
+    if (Object.keys(all).length >= 5000) throw new Error('Lifecycle operation capacity reached.');
+    all[id] = op; next.projectLifecycleOperations = all;
+    ctx.record(next, correlation, partial(op), project, action); return op;
+  }
+  function exact(op) {
+    var project = ctx.find(op.slug);
+    if (!project || project.projectKnowledgeId !== op.projectKnowledgeId || JSON.stringify(project) !== op.expected || JSON.stringify(ctx.directory(project.path)) !== JSON.stringify(op.directory)) throw new Error('The exact saved registration changed. Recovery will not overwrite or delete it.');
+    return project;
+  }
+  function inspect(slug, id, principal) {
+    var op = id ? operations()[id] : Object.values(operations()).reverse().find(function (item) { return item.slug === slug && item.phase === 'pending'; });
+    var current = ctx.find(slug);
+    if (!op || op.slug !== slug || (op.ownerId !== (principal.userId || null) && (!current || current.ownerId !== principal.userId))) throw new Error('No owned lifecycle operation is available.');
+    var conflict = op.phase !== 'completed' && JSON.stringify(current) !== op.expected;
+    return { registrationTitle: current && current.ownerId === principal.userId ? current.title || current.slug : undefined, conflict: conflict, operationId: op.id, action: op.action, phase: op.phase, runtimeClosureConfirmed: op.action === 'remove' && closed(op), revision: JSON.stringify([op, current]) };
+  }
+  function complete(next, op, project) {
+    var all = Object.assign({}, next.projectLifecycleOperations);
+    all[op.id] = Object.assign({}, op, { phase: 'completed' }); next.projectLifecycleOperations = all;
+    ctx.record(next, op.correlation, Object.assign({}, op.result, { operationId: op.id }), project, op.action);
+  }
+  async function reconcile(slug, id, principal, authorize, validate, restore) {
+    var info = inspect(slug, id, principal), op = operations()[info.operationId];
+    if (op.phase === 'completed') return Object.assign({}, op.result, { operationId: op.id });
+    if (validate) validate();
+    try {
+      if (op.action === 'remove' && !op.restoration) {
+        await ctx.relay().closeProjectLifecycle(op.targets, closed(op));
+        if (ctx.relay().getProjectLifecycleTargets(slug).length) throw new Error('A live project or worktree runtime appeared during closure.');
+        confirmClosed(op);
+        authorize();
+        var registration = ctx.find(slug);
+        if (restore) {
+          if (!registration || registration.ownerId !== principal.userId || registration.projectKnowledgeId !== op.projectKnowledgeId || registration.lifecycleOperationId !== op.id) throw new Error('The saved registration no longer belongs to this recovery operation or owner.');
+        } else exact(op);
+        var next = ctx.snapshot();
+        var project = next.projects.find(function (item) { return item.slug === op.slug; });
+        if (restore) {
+          delete project.lifecycleState; delete project.lifecycleOperationId; project.lifecycleExecutionPaused = true;
+          if (JSON.stringify(ctx.directory(project.path)) !== JSON.stringify(op.directory)) throw new Error('The project directory identity changed; restoration was refused.');
+          var restored = Object.assign({}, op, { restoration: true, expected: JSON.stringify(project), result: { ok: true, status: 'superseded', originalAction: 'remove', slug: op.slug, registrationRestored: true, executionPaused: true, semantics: 'Registration restored. Queued and scheduled execution stays paused until the owner explicitly sends a new message.' } });
+          next.projectLifecycleOperations = Object.assign({}, next.projectLifecycleOperations); next.projectLifecycleOperations[op.id] = restored; ctx.save(next); op = restored;
+          ctx.publishRuntime(project, 'recovered'); authorize(); exact(op);
+          next = ctx.snapshot(); complete(next, op, project); ctx.save(next); ctx.publish();
+          return Object.assign({}, restored.result, { status: 'completed', action: 'recover_registration', originalOutcome: 'superseded', operationId: op.id });
+        }
+        next.projects = next.projects.filter(function (item) { return item.slug !== op.slug; });
+        next.removedProjects = (next.removedProjects || []).filter(function (item) { return item.path !== project.path; }).concat([{ path: project.path, title: project.title || null, icon: project.icon || null, userId: op.ownerId, projectKnowledgeId: project.projectKnowledgeId, removedAt: Date.now() }]).slice(-20);
+        complete(next, op, project); ctx.save(next);
+      } else {
+        if (restore && !op.restoration) throw new Error('Only a pending removal can restore its registration.');
+        authorize(); var current = ctx.find(op.slug), currentRevision = JSON.stringify(current);
+        if (currentRevision !== op.expected) {
+          if (!current || current.projectKnowledgeId !== op.projectKnowledgeId || current.ownerId !== principal.userId || JSON.stringify(ctx.directory(current.path)) !== JSON.stringify(op.directory)) throw new Error('The saved publication target was replaced or transferred.');
+          ctx.publishRuntime(current, 'recovered'); authorize();
+          if (JSON.stringify(ctx.find(op.slug)) !== currentRevision) throw new Error('Registration changed during publication reconciliation.');
+          op = Object.assign({}, op, { result: { ok: true, status: 'superseded', slug: op.slug, persisted: true, currentRegistrationRetained: true } });
+        } else {
+          exact(op); ctx.publishRuntime(current, op.restoration ? 'recovered' : op.action); authorize(); exact(op);
+        }
+        var updated = ctx.snapshot(); complete(updated, op, current); ctx.save(updated);
+      }
+      ctx.publish(); return Object.assign({}, op.result, { operationId: op.id });
+    } catch (error) { error.lifecycleResult = Object.assign({}, error.lifecycleResult || {}, partial(op, error.message)); throw error; }
+  }
+  return { begin: begin, partial: partial, exact: exact, closed: closed, confirmClosed: confirmClosed, inspect: inspect, complete: complete, reconcile: reconcile };
+}
+module.exports = { attachLifecycleOperations: attachLifecycleOperations };

package/lib/project-lifecycle-process-witness.js

@@ -0,0 +1,32 @@
+// Bounded, content-free process identities for closure reconciliation after host exit.
+var cp = require('child_process');
+function table() {
+  var output = cp.execFileSync('ps', ['-axo', 'pid=,ppid=,lstart='], { encoding: 'utf8', timeout: 5000, maxBuffer: 8 * 1024 * 1024, env: Object.assign({}, process.env, { LC_ALL: 'C', TZ: 'UTC' }) });
+  var rows = new Map();
+  output.split('\n').forEach(function (line) {
+    var match = /^\s*(\d+)\s+(\d+)\s+(.+?)\s*$/.exec(line);
+    if (match) rows.set(Number(match[1]), { pid: Number(match[1]), parent: Number(match[2]), start: match[3] });
+  });
+  if (!rows.has(process.pid)) throw new Error("The process identity census was incomplete.");
+  return rows;
+}
+function capture() {
+  try {
+    var rows = table(), host = rows.get(process.pid), children = [], parents = new Set([process.pid]);
+    if (!host) return null;
+    for (var pass = 0; pass < rows.size; pass++) {
+      var changed = false;
+      rows.forEach(function (row) { if (parents.has(row.parent) && !parents.has(row.pid)) { parents.add(row.pid); children.push(row); changed = true; } });
+      if (!changed) break;
+    }
+    return { host: host, children: children };
+  } catch (error) { return null; }
+}
+function confirmsExit(witness) {
+  if (!witness || !witness.host || !Array.isArray(witness.children)) return false;
+  var rows = table();
+  return [witness.host].concat(witness.children).every(function (previous) {
+    var current = rows.get(previous.pid); return !current || current.start !== previous.start;
+  });
+}
+module.exports = { capture: capture, confirmsExit: confirmsExit };

package/lib/project-lifecycle-runtime.js

@@ -0,0 +1,50 @@
+// Retain failed shutdown handles so an explicitly reviewed recovery can retry them.
+var crypto = require('crypto');
+var witnesses = require('./project-lifecycle-process-witness');
+function attachLifecycleRuntime(ctx) {
+  var epoch = crypto.randomUUID(), retired = new Map();
+  function target(slug, project) {
+    var status = project.getStatus();
+    return { slug: slug, path: status.path, projectKnowledgeId: status.projectKnowledgeId || null, epoch: epoch };
+  }
+  function key(item) { return JSON.stringify([item.slug, item.path, item.projectKnowledgeId]); }
+  function matches(item, project) { return key(item) === key(target(item.slug, project)); }
+  function targets(slug) {
+    var out = [], witness = witnesses.capture();
+    ctx.projects.forEach(function (project, candidate) {
+      if (candidate === slug || candidate.indexOf(slug + '--') === 0) out.push(Object.assign(target(candidate, project), { witness: witness }));
+    });
+    return out;
+  }
+  function stop(item, project) {
+    var id = key(item), previous = retired.get(id);
+    if (previous && previous.project !== project) {
+      if (!previous.closed) throw new Error('An earlier runtime with this identity has not confirmed closure.');
+      previous = null;
+    }
+    if (previous && previous.running) return previous.running;
+    if (previous && previous.closed) return Promise.resolve(true);
+    var state = previous || { project: project, target: item, closed: false };
+    retired.set(id, state);
+    state.running = Promise.resolve().then(function () { return state.project.destroy(); }).then(function (result) {
+      if (result !== true) throw new Error('Project runtime closure was not acknowledged: ' + item.slug);
+      state.closed = true; return true;
+    }).finally(function () { state.running = null; });
+    return state.running;
+  }
+  async function close(items, proof) {
+    for (var item of items) {
+      var live = ctx.projects.get(item.slug), previous = retired.get(key(item));
+      if (live) {
+        if (!matches(item, live)) throw new Error('A replacement runtime occupies this registration.');
+        ctx.projects.delete(item.slug);
+        await stop(item, live);
+      } else if (previous) await stop(item, previous.project);
+      else if (!proof && !witnesses.confirmsExit(item.witness)) throw new Error('Runtime closure evidence is unavailable on this host. Keep the operation pending until its original host confirms closure.');
+    }
+    return true;
+  }
+  function shutdown() { return Promise.all(Array.from(retired.values()).filter(function (item) { return !item.closed; }).map(function (item) { return stop(item.target, item.project); })); }
+  return { targets: targets, close: close, shutdown: shutdown };
+}
+module.exports = { attachLifecycleRuntime: attachLifecycleRuntime };

package/lib/project-linux-access.js

@@ -0,0 +1,22 @@
+// Fail closed on unmapped identities, aliases, foreign ownership or unacknowledged ACLs.
+var fs = require('fs');
+var path = require('path');
+var cp = require('child_process');
+var osUsers = require('./os-users');
+function verify(projectPath, user, resolveIdentity) {
+  if (!user || !user.linuxUser) throw new Error('A provisioned Linux account is required.');
+  var identity = resolveIdentity(user.linuxUser), canonical = fs.realpathSync(projectPath), stat = fs.statSync(canonical);
+  if (!Number.isInteger(identity.uid) || identity.uid < 0 || !Number.isInteger(identity.gid) || identity.gid < 0) throw new Error('Linux identity is unavailable.');
+  if (canonical !== path.resolve(projectPath) || !stat.isDirectory() || stat.uid !== identity.uid) throw new Error('Registration requires a canonical directory owned by the mapped Linux account.');
+  if (osUsers.grantProjectAccess(canonical, user.linuxUser, { force: true }) !== true) {
+    var grantError = new Error('Linux filesystem access grant was not acknowledged.'); grantError.lifecycleResult = { persisted: false, retrySafe: true, filesystemAccess: 'grant_unconfirmed' }; throw grantError;
+  }
+  var script = "var fs = require('fs'); if (process.getuid() !== Number(process.argv[2]) || process.getgid() !== Number(process.argv[3])) throw new Error('Execution identity mismatch'); fs.accessSync(process.argv[1], fs.constants.R_OK | fs.constants.W_OK | fs.constants.X_OK); fs.readdirSync(process.argv[1]);";
+  var wrapped = osUsers.wrapSpawnAsUser(process.execPath, ['-e', script, canonical, String(identity.uid), String(identity.gid)], { uid: identity.uid, gid: identity.gid, stdio: 'pipe', timeout: 10000 });
+  try { cp.execFileSync(wrapped.command, wrapped.args, wrapped.options); }
+  catch (error) { error.lifecycleResult = { persisted: false, retrySafe: true, filesystemAccess: 'verification_failed' }; throw error; }
+  var after = fs.statSync(canonical);
+  if (after.dev !== stat.dev || after.ino !== stat.ino || after.uid !== identity.uid || fs.realpathSync(projectPath) !== canonical) throw new Error('The Linux project directory changed during access verification.');
+  return true;
+}
+module.exports = { verify: verify };