clay-server 5.2.0-beta.4 → 5.2.0-beta.6

package/lib/cli-sessions.js

@@ -1,300 +1 @@
-var fs = require("fs");
-var path = require("path");
-var readline = require("readline");
-var utils = require("./utils");
-var { REAL_HOME } = require("./config");
-
-var encodeCwd = utils.encodeCwd;
-
-/**
- * Parse the first ~20 lines of a CLI session JSONL file to extract metadata.
- * Returns null if the file can't be parsed or has no user messages.
- */
-function parseSessionFile(filePath, maxLines) {
-  if (maxLines == null) maxLines = 20;
-  return new Promise(function (resolve) {
-    var sessionId = path.basename(filePath, ".jsonl");
-    var result = {
-      sessionId: sessionId,
-      firstPrompt: "",
-      model: null,
-      gitBranch: null,
-      startTime: null,
-      lastActivity: null,
-    };
-
-    var lineCount = 0;
-    var foundUser = false;
-    var stream;
-    try {
-      stream = fs.createReadStream(filePath, { encoding: "utf8" });
-    } catch (e) {
-      return resolve(null);
-    }
-
-    var rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
-
-    rl.on("line", function (line) {
-      lineCount++;
-      if (lineCount > maxLines) {
-        rl.close();
-        stream.destroy();
-        return;
-      }
-
-      var obj;
-      try { obj = JSON.parse(line); } catch (e) { return; }
-
-      // Skip file-history-snapshot, queue-operation, and other non-message records
-      if (obj.type === "user" && obj.message && obj.message.role === "user") {
-        if (!foundUser) {
-          foundUser = true;
-          result.sessionId = obj.sessionId || sessionId;
-          result.gitBranch = obj.gitBranch || null;
-          if (obj.timestamp) result.startTime = obj.timestamp;
-          var content = obj.message.content || "";
-          if (typeof content === "string") {
-            result.firstPrompt = content.substring(0, 100);
-          } else if (Array.isArray(content)) {
-            for (var i = 0; i < content.length; i++) {
-              if (content[i].type === "text" && content[i].text) {
-                result.firstPrompt = content[i].text.substring(0, 100);
-                break;
-              }
-            }
-          }
-        }
-        // Track latest user timestamp for lastActivity
-        if (obj.timestamp) result.lastActivity = obj.timestamp;
-      }
-
-      // Extract model from first assistant message
-      if (!result.model && obj.message && obj.message.role === "assistant" && obj.message.model) {
-        result.model = obj.message.model;
-      }
-    });
-
-    rl.on("close", function () {
-      if (!foundUser) return resolve(null);
-
-      // Use file mtime as fallback for lastActivity, or as a better proxy
-      // since we only read the first ~20 lines
-      try {
-        var stat = fs.statSync(filePath);
-        var mtime = stat.mtime.toISOString();
-        // File mtime is always more accurate for "last activity" since we
-        // don't read the entire file
-        result.lastActivity = mtime;
-      } catch (e) {}
-
-      resolve(result);
-    });
-
-    rl.on("error", function () {
-      resolve(null);
-    });
-
-    stream.on("error", function () {
-      rl.close();
-      resolve(null);
-    });
-  });
-}
-
-/**
- * List CLI sessions for a given project directory.
- * Reads ~/.claude/projects/{encoded-cwd}/ and parses JSONL metadata.
- * Returns array sorted by lastActivity descending (most recent first).
- */
-function listCliSessions(cwd) {
-  var encoded = encodeCwd(cwd);
-  var projectDir = path.join(REAL_HOME, ".claude", "projects", encoded);
-
-  return new Promise(function (resolve) {
-    fs.readdir(projectDir, { withFileTypes: true }, function (err, entries) {
-      if (err) return resolve([]);
-
-      var jsonlFiles = [];
-      for (var i = 0; i < entries.length; i++) {
-        if (entries[i].isFile() && entries[i].name.endsWith(".jsonl")) {
-          jsonlFiles.push(path.join(projectDir, entries[i].name));
-        }
-      }
-
-      if (jsonlFiles.length === 0) return resolve([]);
-
-      var pending = jsonlFiles.length;
-      var results = [];
-
-      for (var j = 0; j < jsonlFiles.length; j++) {
-        parseSessionFile(jsonlFiles[j]).then(function (session) {
-          if (session) results.push(session);
-          pending--;
-          if (pending === 0) {
-            results.sort(function (a, b) {
-              var ta = a.lastActivity || "";
-              var tb = b.lastActivity || "";
-              return ta < tb ? 1 : ta > tb ? -1 : 0;
-            });
-            resolve(results);
-          }
-        });
-      }
-    });
-  });
-}
-
-/**
- * Get the most recent CLI session for a given project directory.
- * Returns the session object or null if none found.
- */
-function getMostRecentCliSession(cwd) {
-  return listCliSessions(cwd).then(function (sessions) {
-    return sessions.length > 0 ? sessions[0] : null;
-  });
-}
-
-/**
- * Extract user message text from a CLI JSONL content field.
- * Content can be a string or an array of content blocks.
- */
-function extractText(content) {
-  if (typeof content === "string") return content;
-  if (!Array.isArray(content)) return "";
-  var parts = [];
-  for (var i = 0; i < content.length; i++) {
-    if (content[i].type === "text" && content[i].text) {
-      parts.push(content[i].text);
-    }
-  }
-  return parts.join("");
-}
-
-/**
- * Read a full CLI session JSONL file and convert it to relay-compatible
- * history entries (user_message, delta, tool_start, tool_executing, tool_result).
- * Returns a Promise that resolves to an array of history entries.
- */
-// Convert one parsed CLI jsonl record into client history entries. Shared by
-// the streaming (async) and synchronous readers so the format stays in lockstep.
-// `state.toolCounter` carries across lines to mint unique tool ids.
-function appendCliRecord(obj, state, history) {
-  if (!obj || !obj.message) return;
-
-  // User prompt
-  if (obj.type === "user" && obj.message.role === "user") {
-    // Skip tool_result records (they have type "user" but content is tool results)
-    var content = obj.message.content;
-    if (Array.isArray(content) && content.length > 0 && content[0].type === "tool_result") {
-      return;
-    }
-    var text = extractText(content);
-    if (text) history.push({ type: "user_message", text: text });
-    return;
-  }
-
-  // Assistant message
-  if (obj.message.role === "assistant" && Array.isArray(obj.message.content)) {
-    for (var i = 0; i < obj.message.content.length; i++) {
-      var block = obj.message.content[i];
-
-      if (block.type === "text" && block.text) {
-        history.push({ type: "delta", text: block.text });
-      }
-
-      if (block.type === "tool_use") {
-        var toolId = "cli-tool-" + (++state.toolCounter);
-        var toolName = block.name || "Tool";
-        history.push({ type: "tool_start", id: toolId, name: toolName });
-        history.push({
-          type: "tool_executing",
-          id: toolId,
-          name: toolName,
-          input: block.input || {},
-        });
-        // Emit ask_user_answered so the client re-enables input after replaying AskUserQuestion
-        if (toolName === "AskUserQuestion") {
-          history.push({ type: "ask_user_answered", toolId: toolId });
-        }
-        history.push({ type: "tool_result", id: toolId, content: "" });
-      }
-    }
-  }
-}
-
-function readCliSessionHistory(home, cwd, sessionId) {
-  var encoded = encodeCwd(cwd);
-  var filePath = path.join(home || REAL_HOME, ".claude", "projects", encoded, sessionId + ".jsonl");
-
-  return new Promise(function (resolve) {
-    var history = [];
-    var stream;
-    try {
-      stream = fs.createReadStream(filePath, { encoding: "utf8" });
-    } catch (e) {
-      return resolve([]);
-    }
-
-    var rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
-    var state = { toolCounter: 0 };
-
-    rl.on("line", function (line) {
-      var obj;
-      try { obj = JSON.parse(line); } catch (e) { return; }
-      appendCliRecord(obj, state, history);
-    });
-
-    rl.on("close", function () {
-      resolve(history);
-    });
-
-    rl.on("error", function () {
-      resolve([]);
-    });
-
-    stream.on("error", function () {
-      rl.close();
-      resolve([]);
-    });
-  });
-}
-
-// Synchronous variant for callers that run inside a synchronous request
-// handler (e.g. switch_session, which must populate session.history before
-// the session_switched broadcast). Reads the whole jsonl - these transcripts
-// are small enough that blocking on a local read is fine.
-// Modified-time (ms) of a CLI session's jsonl, or 0 if missing. Lets callers
-// cheaply detect that the transcript grew (e.g. after a TUI turn) and re-read.
-function cliSessionFileMtime(home, cwd, sessionId) {
-  var encoded = encodeCwd(cwd);
-  var filePath = path.join(home || REAL_HOME, ".claude", "projects", encoded, sessionId + ".jsonl");
-  try { return fs.statSync(filePath).mtimeMs; } catch (e) { return 0; }
-}
-
-function readCliSessionHistorySync(home, cwd, sessionId) {
-  var encoded = encodeCwd(cwd);
-  var filePath = path.join(home || REAL_HOME, ".claude", "projects", encoded, sessionId + ".jsonl");
-  var raw;
-  try { raw = fs.readFileSync(filePath, "utf8"); } catch (e) { return []; }
-  var history = [];
-  var state = { toolCounter: 0 };
-  var lines = raw.split("\n");
-  for (var i = 0; i < lines.length; i++) {
-    if (!lines[i]) continue;
-    var obj;
-    try { obj = JSON.parse(lines[i]); } catch (e) { continue; }
-    appendCliRecord(obj, state, history);
-  }
-  return history;
-}
-
-module.exports = {
-  listCliSessions: listCliSessions,
-  getMostRecentCliSession: getMostRecentCliSession,
-  readCliSessionHistory: readCliSessionHistory,
-  readCliSessionHistorySync: readCliSessionHistorySync,
-  cliSessionFileMtime: cliSessionFileMtime,
-  parseSessionFile: parseSessionFile,
-  encodeCwd: encodeCwd,
-  extractText: extractText,
-};
+module.exports = require("./yoke/cli-sessions");

package/lib/codex-defaults.js

@@ -1,28 +1 @@
-var CODEX_DEFAULTS = {
-  approval: "on-request",
-  sandbox: "danger-full-access",
-  webSearch: "live",
-};
-
-var CODEX_APPROVAL_POLICIES = ["untrusted", "on-request", "granular", "never"];
-
-function normalizeCodexApproval(value) {
-  if (value === "on-failure") return CODEX_DEFAULTS.approval;
-  if (CODEX_APPROVAL_POLICIES.indexOf(value) === -1) return CODEX_DEFAULTS.approval;
-  return value;
-}
-
-function getCodexConfig(sm) {
-  return {
-    approval: normalizeCodexApproval(sm && sm.codexApproval),
-    sandbox: (sm && sm.codexSandbox) || CODEX_DEFAULTS.sandbox,
-    webSearch: (sm && sm.codexWebSearch) || CODEX_DEFAULTS.webSearch,
-  };
-}
-
-module.exports = {
-  CODEX_DEFAULTS: CODEX_DEFAULTS,
-  CODEX_APPROVAL_POLICIES: CODEX_APPROVAL_POLICIES,
-  normalizeCodexApproval: normalizeCodexApproval,
-  getCodexConfig: getCodexConfig,
-};
+module.exports = require("./yoke/options/codex-defaults");

package/lib/context-usage.js

@@ -16,8 +16,9 @@ function readUsage(session, detail) {
     return query.getContextUsage({ detail: level });
   }).then(function(data) {
     if (!data || session.queryInstance !== query || requests.get(session) !== state || state.sequence !== sequence) return null;
-    session.lastContextUsage = data;
-    return data;
+    var normalized = require("./yoke/usage").context(data, session.vendor || "claude");
+    session.lastContextUsage = normalized;
+    return normalized;
   }).finally(function() { delete state.pending[level]; });
   state.pending[level] = request;
   return request;

package/lib/daemon-project-access.js

@@ -27,6 +27,12 @@ function uniqueUsers(values) {
   return out;
 }
 
+function pendingLifecycleOperation(config, project) {
+  return Object.values(config.projectLifecycleOperations || {}).find(function (operation) {
+    return operation.phase === 'pending' && operation.slug === project.slug && operation.projectKnowledgeId === project.projectKnowledgeId && operation.expected === JSON.stringify(project);
+  });
+}
+
 function getProjectAccess(config, slug, osUsers) {
   var parentSlug = parentSlugFor(slug);
   var project = findProject(config, parentSlug || slug);
@@ -42,6 +48,8 @@ function getProjectAccess(config, slug, osUsers) {
   if (!parentSlug) {
     return {
       slug: slug,
+      lifecycleExecutionPaused: project.lifecycleExecutionPaused === true || !!pendingLifecycleOperation(config, project),
+      ownershipRecovery: project.ownershipRecovery || null,
       visibility: visibility,
       allowedUsers: parentAllowedUsers,
       ownerId: project.ownerId || null,
@@ -54,6 +62,8 @@ function getProjectAccess(config, slug, osUsers) {
   var worktreeAllowedUsers = uniqueUsers(grants);
   return {
     slug: slug,
+    lifecycleExecutionPaused: project.lifecycleExecutionPaused === true || !!pendingLifecycleOperation(config, project),
+    ownershipRecovery: project.ownershipRecovery || null,
     visibility: visibility,
     allowedUsers: uniqueUsers(parentAllowedUsers.concat(worktreeAllowedUsers)),
     ownerId: project.ownerId || null,
@@ -129,6 +139,7 @@ function reconcileWorktreeGrants(config, parentSlug, existingSlugs) {
 }
 
 module.exports = {
+  pendingLifecycleOperation: pendingLifecycleOperation,
   parentSlugFor: parentSlugFor,
   getProjectAccess: getProjectAccess,
   setAllowedUsers: setAllowedUsers,

package/lib/daemon-project-lifecycle-callbacks.js

@@ -0,0 +1,15 @@
+// The daemon and production UI fixtures share these exact callback adapters.
+function attachLifecycleCallbacks(ctx) {
+  function attempt(action) {
+    try { return action(); }
+    catch (error) { return Object.assign({ ok: false, status: 'failed', error: error.message, persisted: false, retrySafe: true }, error.lifecycleResult || {}); }
+  }
+  return {
+    onAddProject: function (candidate, user) { return attempt(function () { return ctx.service.register(candidate, user); }); },
+    onCreateProject: function (name, user) { return attempt(function () { return ctx.service.create(name, user); }); },
+    onRemoveProject: function (slug, userId) { return ctx.service.remove(slug, userId); },
+    onSetProjectTitle: function (slug, title) { return attempt(function () { return ctx.service.update(slug, 'rename', title); }); },
+    onSetProjectEnv: function (slug, value) { return attempt(function () { return ctx.service.update(slug, 'environment', value); }); },
+  };
+}
+module.exports = { attachLifecycleCallbacks: attachLifecycleCallbacks };

package/lib/daemon-project-lifecycle.js

@@ -0,0 +1,262 @@
+// Shared ordinary-project mutations. Persistence precedes runtime publication.
+var fs = require('fs');
+var path = require('path');
+var cp = require('child_process');
+var access = require('./daemon-project-access');
+var ownership = require('./project-ownership');
+var configModule = require('./config');
+function attachProjectLifecycle(ctx) {
+  var pending = new Map();
+  var operations = require('./project-lifecycle-operations').attachLifecycleOperations({ config: config, find: find, snapshot: snapshot, save: save, record: record,
+    storageDir: configModule.CONFIG_DIR, directory: identity, relay: relay, publish: publish, publishRuntime: publishRuntime });
+  function config() { return ctx.getConfig(); }
+  function relay() { return ctx.getRelay(); }
+  function find(slug) { return (config().projects || []).find(function (p) { return p.slug === slug; }); }
+  function ordinary(project) {
+    if (!project || ownership.isPersonal(project) || access.parentSlugFor(project.slug)) throw new Error('Choose a registered ordinary parent project. Clay, Mates and worktrees are excluded.');
+    if (project.lifecycleState) throw new Error('Project removal is still pending; inspect its receipt before another action.');
+    return project;
+  }
+  function save(next) { ctx.saveConfig(next); ctx.setConfig(next); }
+  function publish() {
+    try { configModule.syncClayrc(config().projects); } catch (error) {}
+    relay().broadcastAll({ type: 'projects_updated', projects: relay().getProjects(), projectCount: config().projects.length });
+  }
+  function identity(candidate) {
+    var canonical = fs.realpathSync(candidate), stat = fs.statSync(canonical);
+    if (!stat.isDirectory()) throw new Error('Choose an existing directory.');
+    return { path: canonical, dev: stat.dev, ino: stat.ino, uid: stat.uid };
+  }
+  function existing(candidate, user) {
+    var target = identity(candidate), found = (config().projects || []).find(function (project) { return require('./project-directory-claim').canonical(project.path) === target.path; });
+    if (!found) return null;
+    var users = require('./users');
+    if (users.isMultiUser() ? !user || !users.canAccessProject(user.id, access.getProjectAccess(config(), found.slug, config().osUsers)) : !!found.ownerId && found.ownerId !== (user && user.id || null)) throw new Error('Directory access is not permitted.');
+    ordinary(found);
+    return found;
+  }
+  function registration(candidate, user) {
+    var target = identity(candidate);
+    var dataRoot = require('./project-directory-claim').canonical(configModule.CONFIG_DIR);
+    var relative = path.relative(dataRoot, target.path), inverse = path.relative(target.path, dataRoot);
+    if (relative !== '..' && relative.indexOf('..' + path.sep) !== 0 && !path.isAbsolute(relative) || inverse !== '..' && inverse.indexOf('..' + path.sep) !== 0 && !path.isAbsolute(inverse)) throw new Error('Clay private storage cannot be registered as an ordinary project.');
+    (config().projects || []).forEach(function (p) {
+      var root = identity(p.path).path;
+      function inside(a, b) { var rel = path.relative(a, b); return rel !== '..' && rel.indexOf('..' + path.sep) !== 0 && !path.isAbsolute(rel); }
+      if (inside(target.path, root) || inside(root, target.path) && p.ownerId !== (user && user.id)) throw new Error('Directory intersects a registered project.');
+    });
+    return target;
+  }
+  function assertSupported(action) {
+    if (config().osUsers && ['visibility', 'allowed_users', 'owner'].indexOf(action) >= 0) throw new Error('OS filesystem sharing and ownership changes are unavailable through canonical Clay; the OS sharing/ownership transaction has no completion acknowledgement.');
+  }
+  function creationPlan(name) {
+    var current = config(), base = current.osUsers ? '/var/clay/projects' : current.projectsDir || path.join(configModule.REAL_HOME, 'clay-projects');
+    var canonical = require('./project-directory-claim').canonical;
+    var slug = configModule.generateSlug(path.join(base, name), current.projects.map(function (p) { return p.slug; }));
+    return { base: base, path: path.join(canonical(base), slug), slug: slug };
+  }
+  function creationRevision(anchor) {
+    var plan = creationPlan('inspection');
+    var canonical = require('./project-directory-claim').canonical;
+    if (!anchor) {
+      anchor = plan.base;
+      while (!fs.existsSync(anchor)) { var parent = path.dirname(anchor); if (parent === anchor) break; anchor = parent; }
+    }
+    return JSON.stringify({ base: plan.base, canonicalBase: canonical(plan.base), anchor: anchor, directory: identity(anchor), osUsers: config().osUsers, projects: config().projects });
+  }
+  function inspect(slug) {
+    var project = ordinary(find(slug));
+    return { project: JSON.parse(JSON.stringify(project)), directory: identity(project.path) };
+  }
+  function stamp(slug) { return JSON.stringify(inspect(slug)); }
+  function receipt(key, fingerprint, userId) {
+    var item = key && (config().projectControlReceipts || {})[key];
+    if (!item) return null;
+    if (item.fingerprint !== fingerprint || item.ownerId !== (userId || null)) throw new Error('requestId already names another exact project action.');
+    var live = item.slug && find(item.slug);
+    if (!live && item.result.filesDeleted !== false && item.result.outcome !== 'removal_reserved_runtime_pending') throw new Error('The receipt target registration was deleted. No action was repeated.');
+    if (live && (live.projectKnowledgeId !== item.projectKnowledgeId || live.ownerId !== item.ownerId && !(item.action === 'owner' && item.result.status === 'completed'))) throw new Error('The receipt target was replaced or transferred.');
+    return item.result;
+  }
+  function record(next, correlation, result, project, action) {
+    if (!correlation) return;
+    var receipts = Object.assign({}, next.projectControlReceipts || {});
+    if (!receipts[correlation.key] && Object.keys(receipts).length >= 5000) throw new Error('Project control receipt capacity reached.');
+    receipts[correlation.key] = { action: action || correlation.action, sourceKey: correlation.sourceKey || null, fingerprint: correlation.fingerprint, ownerId: correlation.ownerId || null, slug: project && project.slug, projectKnowledgeId: project && project.projectKnowledgeId, result: result };
+    next.projectControlReceipts = receipts;
+  }
+  function runtime(slug) { var found; relay().forEachProject(function (project, candidate) { if (candidate === slug) found = project; }); return found; }
+  function publishRuntime(project, action) {
+    if (config().osUsers && (action === 'register' || action === 'create')) require('./project-linux-access').verify(project.path, ctx.findUser(project.ownerId), ctx.resolveIdentity);
+    var current = runtime(project.slug), status = current && current.getStatus();
+    if (status && (status.path !== project.path || status.projectKnowledgeId !== project.projectKnowledgeId)) throw new Error('A replacement runtime occupies the saved registration.');
+    if (!current && relay().addProject(project.path, project.slug, project.title || null, project.icon || null, project.ownerId || null, null, { projectKnowledgeId: project.projectKnowledgeId }) === false) throw new Error('Saved project runtime publication was not acknowledged.');
+    relay().setProjectTitle(project.slug, project.title || null);
+    relay().forEachProject(function (target, slug) {
+      if (slug === project.slug || access.parentSlugFor(slug) === project.slug) {
+        target.setProjectOwner(project.ownerId || null);
+        if ((action === 'environment' || action === 'recovered') && target.refreshEnvironmentRuntime) target.refreshEnvironmentRuntime();
+      }
+    });
+    if (action === 'owner' || action === 'visibility' || action === 'allowed_users' || action === 'recovered') relay().refreshProjectAccess();
+    if ((action === 'create' || action === 'register') && ctx.registerWorktrees) ctx.registerWorktrees(project, project.ownerId && ctx.findUser(project.ownerId));
+  }
+  function publication(next, project, action, result, correlation) {
+    var op = operations.begin(next, project, action, result, correlation);
+    save(next);
+    try {
+      publishRuntime(project, action);
+      if (correlation && correlation.authorize) correlation.authorize();
+      operations.exact(op);
+      var completed = snapshot(); operations.complete(completed, op, project); save(completed);
+      try { publish(); } catch (error) { result.notificationPending = true; }
+      return Object.assign({}, result, { operationId: op.id });
+    } catch (error) { error.lifecycleResult = Object.assign({}, error.lifecycleResult || {}, operations.partial(op, error.message)); throw error; }
+  }
+  function receiptPreview(fingerprint, sourceKey, ownerId) {
+    return Object.values(config().projectControlReceipts || {}).find(function (item) {
+      return item.action === 'owner' && item.result.status === 'completed' && item.fingerprint === fingerprint && item.sourceKey === sourceKey && item.ownerId === ownerId;
+    });
+  }
+  function snapshot() { var lastConfig = config(); return Object.assign({}, lastConfig, JSON.parse(JSON.stringify(lastConfig))); }
+  function creatingAccount(user, existingOnly) {
+    var users = require('./users');
+    if (!users.isMultiUser()) return null;
+    var live = user && ctx.findUser(user.id);
+    if (!live || !existingOnly && !users.getEffectivePermissions(live, config().osUsers).createProject) throw new Error('Live project creation permission is required.');
+    return live;
+  }
+  function create(name, user, correlation, validate) {
+    user = creatingAccount(user);
+    if (!/^[a-zA-Z0-9_-]{1,100}$/.test(name) || (/^mate-/i.test(name) || name.indexOf('--') >= 0)) throw new Error('Invalid ordinary project name.');
+    if (validate) validate();
+    var current = config(), base = current.osUsers ? '/var/clay/projects' : current.projectsDir || path.join(configModule.REAL_HOME, 'clay-projects');
+    var creatingIdentity = JSON.stringify([user && user.id, user && user.linuxUser]);
+    var osIdentity = null;
+    if (current.osUsers) {
+      if (!user || !user.linuxUser) throw new Error('A provisioned Linux account is required.');
+      osIdentity = ctx.resolveIdentity(user.linuxUser);
+      if (!Number.isInteger(osIdentity.uid) || !Number.isInteger(osIdentity.gid)) throw new Error('Linux identity unavailable.');
+    }
+    var slug = configModule.generateSlug(path.join(base, name), current.projects.map(function (p) { return p.slug; }));
+    var claim = require('./project-directory-claim').claim({ baseDir: base, slug: slug, projects: current.projects, userId: user && user.id });
+    var persisted = false;
+    try {
+      claim.assertOwned();
+      var options = { cwd: claim.path, stdio: 'pipe' };
+      if (osIdentity) {
+        fs.chownSync(claim.path, osIdentity.uid, osIdentity.gid);
+        options = Object.assign({}, options, { uid: osIdentity.uid, gid: osIdentity.gid, env: { HOME: osIdentity.home, USER: user.linuxUser, PATH: '/usr/local/bin:/usr/bin:/bin' } });
+        var wrapped = require('./os-users').wrapSpawnAsUser('git', ['init'], options);
+        cp.execFileSync(wrapped.command, wrapped.args, wrapped.options);
+      } else cp.execFileSync('git', ['init'], options);
+      claim.assertOwned();
+      user = creatingAccount(user);
+      if (JSON.stringify([user && user.id, user && user.linuxUser]) !== creatingIdentity) throw new Error('Creating OS account identity changed.');
+      if (osIdentity && JSON.stringify(ctx.resolveIdentity(user.linuxUser)) !== JSON.stringify(osIdentity)) throw new Error('Resolved OS identity changed during creation.');
+      if (osIdentity) { fs.chmodSync(claim.path, 0o700); require('./project-linux-access').verify(claim.path, user, ctx.resolveIdentity); }
+      if (validate) validate();
+      var next = snapshot(), project = { slug: slug, path: claim.path, ownerId: user && user.id || null, visibility: 'private', addedAt: Date.now(), projectKnowledgeId: require('./project-log-context').createProjectKnowledgeId() };
+      next.projects.push(project);
+      var result = { ok: true, slug: slug, status: 'completed' };
+      return publication(next, project, 'create', result, correlation);
+    } catch (error) {
+      persisted = !!(error.lifecycleResult && error.lifecycleResult.persisted);
+      if (!persisted) { try { if (!claim.cleanup()) error.message += '; claimed directory was replaced; cleanup skipped'; } catch (cleanupError) { error.message += '; directory cleanup failed: ' + cleanupError.message; } }
+      else error.message += '; registration persisted; inspect operationId and explicitly reconcile rather than creating again';
+      throw error;
+    }
+  }
+  function register(candidate, user, correlation, validate) {
+    user = creatingAccount(user, true);
+    if (validate) validate();
+    var registered = existing(candidate, user);
+    if (registered) {
+      if (config().osUsers) require('./project-linux-access').verify(registered.path, user, ctx.resolveIdentity);
+      if (!runtime(registered.slug)) {
+        var pendingOperation = Object.values(config().projectLifecycleOperations || {}).reverse().find(function (item) { return item.slug === registered.slug && item.phase === 'pending'; });
+        if (pendingOperation) return operations.partial(pendingOperation);
+        throw new Error('The registration exists but its runtime is unavailable.');
+      }
+      return { ok: true, status: 'completed', slug: registered.slug, existing: true };
+    }
+    user = creatingAccount(user);
+    var target = registration(candidate, user), next = snapshot();
+    if (config().osUsers) require('./project-linux-access').verify(candidate, user, ctx.resolveIdentity);
+    var slug = configModule.generateSlug(target.path, next.projects.map(function (p) { return p.slug; }));
+    if (/^mate-/.test(slug) || access.parentSlugFor(slug)) throw new Error('Reserved private project identity.');
+    var removed = (next.removedProjects || []).find(function (p) { return p.path === target.path && (p.userId || null) === (user && user.id || null); });
+    var project = { slug: slug, path: target.path, ownerId: user && user.id || null, visibility: 'private', addedAt: Date.now(), projectKnowledgeId: removed && removed.projectKnowledgeId || require('./project-log-context').createProjectKnowledgeId() };
+    next.projects.push(project); next.removedProjects = (next.removedProjects || []).filter(function (p) { return p.path !== target.path; });
+    if (validate) validate();
+    var result = { ok: true, status: 'completed', slug: slug };
+    return publication(next, project, 'register', result, correlation);
+  }
+  function update(slug, action, value, correlation, validate) {
+    if (validate) validate();
+    ordinary(find(slug));
+    var next = snapshot(), project = next.projects.find(function (p) { return p.slug === slug; });
+    if (action === 'rename') {
+      if (value !== null && (typeof value !== 'string' || value.length > 100 || /[\u0000-\u001f\u007f]/.test(value))) throw new Error('Invalid project title.');
+      project.title = value;
+    } else if (action === 'environment') {
+      if (typeof value !== 'string' || value.length > 100000 || /\u0000/.test(value)) throw new Error('Invalid project environment.');
+      var envError = require('./runtime-env').validateEnvString(value);
+      if (envError) throw new Error(envError);
+      project.envrc = value;
+    } else if (action === 'visibility') {
+      if (next.osUsers) throw new Error('OS filesystem sharing changes are unavailable through this service.');
+      if (value !== 'public' && value !== 'private') throw new Error('Invalid visibility.'); project.visibility = value;
+    } else if (action === 'allowed_users') {
+      if (next.osUsers) throw new Error('OS filesystem sharing changes are unavailable through this service.');
+      if (!Array.isArray(value) || value.length > 100 || value.some(function (id, i) { return !ctx.findUser(id) || value.indexOf(id) !== i; })) throw new Error('Choose existing unique accounts.');
+      project.allowedUsers = value;
+    } else if (action === 'owner') {
+      if (next.osUsers) throw new Error('OS ownership transfers are unavailable through this service.');
+      if (typeof value !== 'string' || !ctx.findUser(value)) throw new Error('Choose an existing owner account.');
+      project.ownerId = value;
+    } else if (action === 'session_visibility') {
+      var changed = access.setSessionVisibilityDefault(next, slug, value); if (!changed.ok) throw new Error(changed.error);
+    } else throw new Error('Unsupported project mutation.');
+    var result = { ok: true, status: 'completed', slug: slug };
+    if (action === 'environment') result.runtimeRefreshed = true;
+    if (action === 'environment') result.timing = 'Applies to newly created coding-agent processes. Active processes keep their current environment.';
+    return publication(next, project, action, result, correlation);
+  }
+  async function remove(slug, userId, correlation, validate) {
+    if (validate) validate();
+    var project = ordinary(find(slug)), next = snapshot();
+    var savedProject = next.projects.find(function (item) { return item.slug === slug; });
+    var result = { ok: true, status: 'completed', slug: slug, filesDeleted: false, semantics: 'Removed the Clay registration and stopped project runtimes. Project files and stored history remain on disk.' };
+    var targets = relay().getProjectLifecycleTargets(slug);
+    var op = operations.begin(next, savedProject, 'remove', result, correlation, targets); save(next);
+    return operations.reconcile(slug, op.id, { userId: userId || null }, correlation && correlation.authorize || function () {}, null);
+  }
+  function execute(args, user, correlation, validate) {
+    var old = correlation && receipt(correlation.key, correlation.fingerprint, correlation.ownerId);
+    if (old) return pending.get(correlation.key) || old;
+    if (args.action === 'reconcile' || args.action === 'recover_registration') return operations.reconcile(args.projectSlug, args.value, { userId: user && user.id || null }, correlation.authorize, validate, args.action === 'recover_registration');
+    if (args.action === 'create') return create(args.name, user, correlation, validate);
+    if (args.action === 'register') return register(args.path, user, correlation, validate);
+    if (args.action !== 'remove') return update(args.projectSlug, args.action, args.value, correlation, validate);
+    var promise = remove(args.projectSlug, user && user.id, correlation, validate).catch(function (error) {
+      var current = find(args.projectSlug);
+      if (current && current.lifecycleState === 'removing' && !error.lifecycleResult) error.lifecycleResult = { outcome: 'removal_reserved_runtime_pending', persisted: true, retrySafe: false, slug: args.projectSlug, operationId: current.lifecycleOperationId, recoveryAction: 'reconcile' };
+      throw error;
+    });
+    if (correlation) { pending.set(correlation.key, promise); promise.finally(function () { pending.delete(correlation.key); }).catch(function () {}); }
+    return promise;
+  }
+  function resumeRecovered(slug, userId) {
+    var project = ordinary(find(slug));
+    var pendingOperation = access.pendingLifecycleOperation(config(), project);
+    if (pendingOperation) throw new Error('Review and reconcile pending project operation ' + pendingOperation.id + ' before resuming execution.');
+    if (!project.lifecycleExecutionPaused) return true;
+    if (project.ownerId !== userId || !ctx.findUser(userId)) throw new Error('Only the current owner can explicitly resume recovered project execution.');
+    var next = snapshot(); delete next.projects.find(function (item) { return item.slug === slug; }).lifecycleExecutionPaused; save(next); return true;
+  }
+  function canRestore(project) { return !project.lifecycleState; }
+  return { resumeRecovered: resumeRecovered, inspectRecovery: operations.inspect, receiptPreview: receiptPreview, canRestore: canRestore, assertSupported: assertSupported, creationPlan: creationPlan, creationRevision: creationRevision, inspect: inspect, stamp: stamp, registration: registration, receipt: receipt, execute: execute, create: create, register: register, update: update, remove: remove };
+}
+module.exports = { attachProjectLifecycle: attachProjectLifecycle };