clay-server 5.2.0-beta.1 → 5.2.0-beta.11

package/lib/mcp-remote-connections.js

@@ -1,5 +1,7 @@
 var crypto = require('crypto');
 var Client = require('@modelcontextprotocol/sdk/client/index.js').Client;
+var SSEClientTransport = require('@modelcontextprotocol/sdk/client/sse.js').SSEClientTransport;
+var localTransport = require('./mcp-local-transport').localTransport;
 var StreamableHTTPClientTransport = require('@modelcontextprotocol/sdk/client/streamableHttp.js').StreamableHTTPClientTransport;
 var network = require('./mcp-network');
 var oauth = require('./mcp-oauth');
@@ -9,12 +11,33 @@ function createRemoteConnections(ctx) {
   var accounts = new Map(), live = new Map(), flows = new Map(), queues = new Map();
   var remoteFetch = ctx.remoteFetch || network.createRemoteFetch();
   var closed = false;
+  function sameRuntimeConfig(left, right) {
+    return left && right && left.url === right.url && left.enabled === right.enabled && left.authMode === right.authMode && left.token === right.token && JSON.stringify(left.auth || null) === JSON.stringify(right.auth || null) && JSON.stringify([left.transport, left.command, left.args, left.env, left.cwd, left.headers, left.envHeaders, left.references, left.disabledTools, left.enabledTools, left.toolPatterns, left.toolPrefix]) === JSON.stringify([right.transport, right.command, right.args, right.env, right.cwd, right.headers, right.envHeaders, right.references, right.disabledTools, right.enabledTools, right.toolPatterns, right.toolPrefix]);
+  }
+  function invalidate(owner, previous, current) {
+    var byId = new Map(current.filter(function (row) { return row.source !== 'computer'; }).map(function (row) { return [row.id, row]; }));
+    previous.filter(function (row) { return row.source !== 'computer'; }).forEach(function (row) {
+      var next = byId.get(row.id);
+      if (!next || !sameRuntimeConfig(row, next)) disconnect(owner, row.id);
+    });
+  }
   function records(owner) {
     ctx.authorize(owner);
-    if (!accounts.has(owner)) accounts.set(owner, ctx.storage.load(owner));
-    return accounts.get(owner);
+    var account = accounts.get(owner), snapshot = typeof ctx.storage.snapshot === 'function' ? ctx.storage.snapshot(owner) : { records: ctx.storage.load(owner), revision: typeof ctx.storage.revision === 'function' ? ctx.storage.revision(owner) : null };
+    var loaded = snapshot.records, revision = snapshot.revision;
+    if (!account) accounts.set(owner, account = { records: loaded, revision: revision });
+    else if (account.revision !== revision) { invalidate(owner, account.records, loaded); account.records = loaded; account.revision = revision; }
+    return account.records;
+  }
+  function persist(owner) {
+    ctx.authorize(owner); if (closed) throw new Error('MCP connections closed.');
+    var account = accounts.get(owner);
+    if (!account) throw new Error('MCP connection snapshot is unavailable.');
+    var revision;
+    try { revision = ctx.storage.save(owner, account.records, account.revision); }
+    catch (error) { accounts.delete(owner); invalidate(owner, account.records, []); throw error; }
+    if (account) account.revision = revision;
   }
-  function persist(owner) { ctx.authorize(owner); if (closed) throw new Error('MCP connections closed.'); ctx.storage.save(owner, records(owner)); }
   function find(owner, id) {
     var row = records(owner).find(function (item) { return item.id === id; });
     if (!row) throw new Error('Connection is unavailable.');
@@ -23,14 +46,15 @@ function createRemoteConnections(ctx) {
   function key(owner, id) { return JSON.stringify([owner, id]); }
   function check(owner, row) {
     if (closed || find(owner, row.id) !== row) throw new Error('Connection changed.');
+    if (row.source === 'local' && ctx.ownerIdentity) ctx.ownerIdentity(owner);
   }
   function changed(owner) { if (!closed) ctx.changed(owner); }
   function view(owner) {
-    return records(owner).filter(function (row) { return row.source === 'url'; }).map(function (row) {
+    return records(owner).filter(function (row) { return row.source !== 'computer'; }).map(function (row) {
       var entry = live.get(key(owner, row.id));
-      return { id: row.id, name: row.id, label: row.label, source: 'url', transport: 'http', url: row.url,
+      return { id: row.id, name: row.id, label: row.label, source: row.source, transport: row.transport || 'http', url: row.url ? new URL(row.url).origin + new URL(row.url).pathname : null, provenance: row.provenance, references: require('./mcp-import-credentials').requiredNames(row),
         projectEnabled: !!row.enabled, extensionEnabled: true, tools: row.tools || [], toolCount: (row.tools || []).length,
-        status: entry ? entry.status : (row.tools ? 'idle' : 'unavailable'), error: entry ? entry.error : '', authMode: row.authMode || 'auto' };
+        status: entry ? entry.status : (row.provenance || row.tools ? 'idle' : 'unavailable'), error: entry ? entry.error : '', authMode: row.authMode || 'auto' };
     });
   }
   async function disconnect(owner, id) {
@@ -39,7 +63,7 @@ function createRemoteConnections(ctx) {
     if (entry && entry.client) await entry.client.close().catch(function () {});
   }
   function provider(owner, row, flow) {
-    return oauth.createOAuthProvider(row, function () { check(owner, row); persist(owner); }, flow);
+    return oauth.createOAuthProvider(row, function () { check(owner, row); persist(owner); }, flow, function () { check(owner, row); });
   }
   async function connect(owner, row, flow) {
     check(owner, row);
@@ -47,17 +71,20 @@ function createRemoteConnections(ctx) {
     check(owner, row);
     if (flow && flow.cancelled) throw new Error('Sign-in expired.');
     var client = new Client({ name: 'clay', version: '1.0.0' }, { capabilities: {} });
-    var options = { fetch: remoteFetch.fetch };
-    if (row.authMode === 'token' && row.token) options.requestInit = { headers: { Authorization: 'Bearer ' + row.token } };
+    if (row.source !== 'local' && ((row.references || []).length || Object.keys(row.envHeaders || {}).length)) throw new Error('Configure required credentials in Clay before connecting.');
+    var options = { fetch: async function (input, init) { check(owner, row); var response = await remoteFetch.fetch(input, init); check(owner, row); return response; }, requestInit: { headers: row.headers || {} } };
+    if (row.authMode === 'token' && row.token) options.requestInit = { headers: Object.assign({}, row.headers || {}, { Authorization: 'Bearer ' + row.token }) };
     else if (flow || (row.auth && row.auth.tokens)) options.authProvider = provider(owner, row, flow);
-    var transport = new StreamableHTTPClientTransport(new URL(row.url), options);
+    var transport = row.source === 'local' ? localTransport(row, ctx.ownerIdentity ? ctx.ownerIdentity(owner) : null) : (row.transport === 'sse' ? new SSEClientTransport(new URL(row.url), options) : new StreamableHTTPClientTransport(new URL(row.url), options));
     var entry = { client: client, transport: transport, status: 'connecting', error: '' };
     live.set(key(owner, row.id), entry); changed(owner);
     try {
       await client.connect(transport, { timeout: 30000 });
+      check(owner, row);
       var tools = [], cursor, seen = new Set();
       do {
         var page = await client.listTools(cursor ? { cursor: cursor } : {}, { timeout: 30000 });
+        check(owner, row);
         tools = tools.concat(page.tools);
         if (tools.length > 1000 || seen.size >= 100 || (page.nextCursor && seen.has(page.nextCursor))) throw new Error('Tool catalog exceeds the supported limit.');
         cursor = page.nextCursor; seen.add(cursor);
@@ -65,13 +92,16 @@ function createRemoteConnections(ctx) {
       if (JSON.stringify(tools).length > 2 * 1024 * 1024) throw new Error('Tool catalog exceeds the supported limit.');
       check(owner, row);
       if (live.get(key(owner, row.id)) !== entry || (flow && flow.cancelled)) throw new Error('Connection changed.');
+      tools = tools.filter(function (tool) {
+        return require('./mcp-tool-policy').permits(row, tool.name);
+      });
       require('./mcp-proxy').validateDefinitions(tools);
       row.tools = tools; entry.status = 'ready'; persist(owner);
       return entry;
     } catch (error) {
       var requiresAuth = error.code === 401 || error.code === 403 || error.name === 'UnauthorizedError' || (flow && flow.authorizationUrl);
       entry.status = requiresAuth ? 'auth_required' : 'unavailable';
-      entry.error = requiresAuth ? 'Sign in or provide an access token to connect.' : 'Could not connect. Check the address and try again.';
+      entry.error = requiresAuth ? 'Sign in or provide an access token to connect.' : row.source === 'local' ? 'Could not start the command. Check its dependency and working directory.' : 'Could not connect. Check the address and try again.';
       if (!flow) await client.close().catch(function () {});
       return entry;
     } finally { changed(owner); }
@@ -101,6 +131,7 @@ function createRemoteConnections(ctx) {
       if (ready.status !== 'ready') throw new Error('Connection failed after sign-in.');
       setTimeout(function () { if (flows.get(key(owner, row.id)) === flow) { cancelLogin(owner, row.id); changed(owner); } }, 500);
     });
+    try { check(owner, row); } catch (error) { flow.close(); throw error; }
     flows.set(key(owner, row.id), flow);
     flow.timer = setTimeout(function () { cancelLogin(owner, row.id); }, 10 * 60 * 1000); flow.timer.unref();
     row.authMode = 'auto'; delete row.token;
@@ -123,40 +154,61 @@ function createRemoteConnections(ctx) {
     pending.finally(function () { if (queues.get(owner) === pending) queues.delete(owner); }).catch(function () {});
     return pending;
   }
+  function commitImport(owner, select, authorize) {
+    authorize();
+    var imported = select();
+    records(owner);
+    if (accounts.get(owner).revision !== imported.revision) throw new Error('Connections changed. Scan again.');
+    if (records(owner).some(function (item) { return item.importSignature === imported.signature || imported.config.url && item.url === imported.config.url; })) throw new Error('This server is already imported.');
+    authorize();
+    var row = Object.assign({}, imported.config, { id: 'remote-' + crypto.randomBytes(8).toString('hex'), importSignature: imported.signature, enabled: false });
+    records(owner).push(row); persist(owner);
+    return row;
+  }
+  function importConnection(owner, select, authorize) {
+    return serial(owner, function () { var row = commitImport(owner, select, authorize); changed(owner); return row.id; });
+  }
   function command(owner, msg, ws) {
     // Revocation takes effect before any queued network work completes.
     if (msg.action === 'remove' || (msg.action === 'enable' && msg.enabled !== true)) {
       try {
         var revoked = find(owner, msg.id);
-        if (revoked.source !== 'url') throw new Error('Not a remote connection.');
+        if (revoked.source === 'computer') throw new Error('Not a remote connection.');
         revoked.enabled = false; cancelLogin(owner, revoked.id); persist(owner);
         disconnect(owner, revoked.id); changed(owner);
       } catch (error) { return Promise.reject(error); }
     }
     return serial(owner, async function () {
       var row;
-      if (msg.action === 'add') {
+      if (msg.action === 'import') {
+        row = commitImport(owner, function () { return ctx.selectImport(owner, ws, msg); }, function () { if (!ctx.canAccess(ws, owner)) throw new Error('MCP account is unavailable.'); });
+      } else if (msg.action === 'add') {
         var url = network.remoteUrl(msg.url).href;
-        if (records(owner).filter(function (item) { return item.source === 'url'; }).length >= 30) throw new Error('You can add up to 30 remote connections per project.');
+        if (records(owner).filter(function (item) { return item.source !== 'computer'; }).length >= 30) throw new Error('You can add up to 30 remote connections per project.');
         if (records(owner).some(function (item) { return item.url === url; })) throw new Error('This server is already connected. Open it from your connections.');
         row = { id: 'remote-' + crypto.randomBytes(8).toString('hex'), source: 'url', url: url, label: new URL(url).hostname, enabled: false };
         records(owner).push(row); persist(owner);
         await connect(owner, row);
       } else {
         row = find(owner, msg.id);
-        if (row.source !== 'url') throw new Error('Not a remote connection.');
-        if (msg.action === 'enable') { row.enabled = msg.enabled === true; persist(owner); }
+        if (row.source === 'computer') throw new Error('Not a remote connection.');
+        if (msg.action === 'enable') { row.enabled = msg.enabled === true; persist(owner); if (row.enabled && row.provenance) { try { await connect(owner, row); } catch (error) { row.enabled = false; persist(owner); throw error; } } }
         else if (msg.action === 'rename') {
           if (typeof msg.label !== 'string' || !msg.label.trim() || msg.label.length > 100) throw new Error('Use a name between 1 and 100 characters.');
           row.label = msg.label.trim(); persist(owner);
         } else if (msg.action === 'remove') {
           cancelLogin(owner, row.id); await disconnect(owner, row.id);
-          accounts.set(owner, records(owner).filter(function (item) { return item !== row; })); persist(owner);
+          var account = accounts.get(owner);
+          accounts.set(owner, { records: records(owner).filter(function (item) { return item !== row; }), revision: account && account.revision }); persist(owner);
         } else if (msg.action === 'test') { cancelLogin(owner, row.id); await connect(owner, row); }
-        else if (msg.action === 'token') {
+        else if (msg.action === 'credentials') {
+          if (!msg.values || typeof msg.values !== 'object' || Array.isArray(msg.values)) throw new Error('Enter required credential values.');
+          var next = require('./mcp-import-credentials').applyCredentials(row, msg.values);
+          cancelLogin(owner, row.id); Object.assign(row, next); persist(owner); await disconnect(owner, row.id);
+        } else if (msg.action === 'token') {
           if (typeof msg.token !== 'string' || !msg.token.trim() || msg.token.length > 8192 || /[\r\n]/.test(msg.token)) throw new Error('Enter a valid access token.');
           cancelLogin(owner, row.id); row.token = msg.token.trim(); row.authMode = 'token'; delete row.auth; persist(owner); await connect(owner, row);
-        } else if (msg.action === 'signin') await signIn(owner, row, ws);
+        } else if (msg.action === 'signin') { if (row.source === 'local') throw new Error('This server uses process environment credentials.'); await signIn(owner, row, ws); }
         else throw new Error('Unsupported connection action.');
       }
       changed(owner);
@@ -174,6 +226,7 @@ function createRemoteConnections(ctx) {
     return serial(owner, async function () {
       authorize(); var row = find(owner, id);
       if (!row.enabled) throw new Error('Connection is disabled.');
+      if (!require('./mcp-tool-policy').permits(row, name)) throw new Error('Tool is excluded by the imported vendor policy.');
       var entry = live.get(key(owner, id));
       if (!entry || entry.status !== 'ready') entry = await connect(owner, row);
       authorize(); check(owner, row);
@@ -183,6 +236,7 @@ function createRemoteConnections(ctx) {
       var result;
       try { result = await entry.client.callTool({ name: name, arguments: args || {} }, undefined, { timeout: 60000 }); }
       catch (error) {
+        authorize(); check(owner, row);
         if (live.get(key(owner, id)) === entry) {
           entry.status = error.code === 401 || error.code === 403 || error.name === 'UnauthorizedError' ? 'auth_required' : 'unavailable';
           entry.error = entry.status === 'auth_required' ? 'Sign in again to reconnect.' : 'The tool call could not complete. Check the service before retrying.';
@@ -209,7 +263,7 @@ function createRemoteConnections(ctx) {
     closed = true; live.forEach(function (entry) { entry.client.close().catch(function () {}); }); live.clear();
     remoteFetch.close();
   }
-  return { view: view, command: command, call: call, handleBrowser: handleBrowser, destroy: destroy,
+  return { view: view, command: command, importConnection: importConnection, call: call, handleBrowser: handleBrowser, destroy: destroy,
     computerEnabled: computerEnabled, toggleComputer: toggleComputer };
 }
 module.exports = { createRemoteConnections: createRemoteConnections };

package/lib/mcp-source-adapters.js

@@ -0,0 +1 @@
+module.exports = require("./yoke/mcp-source-adapters");

package/lib/mcp-source-context.js

@@ -0,0 +1 @@
+module.exports = require("./yoke/mcp-source-context");

package/lib/mcp-source-discovery.js

@@ -0,0 +1 @@
+module.exports = require("./yoke/mcp-source-discovery");

package/lib/mcp-source-plugins.js

@@ -0,0 +1 @@
+module.exports = require("./yoke/mcp-source-plugins");

package/lib/mcp-source-restrictions.js

@@ -0,0 +1 @@
+module.exports = require("./yoke/mcp-source-restrictions");

package/lib/mcp-tool-policy.js

@@ -0,0 +1,9 @@
+var normalize = require("./yoke/mcp-tool-policy-normalize").normalize;
+function matches(pattern, name) {
+  return new RegExp('^' + pattern.split('').map(function (letter) { return letter === '*' ? '.*' : letter === '?' ? '.' : letter.replace(/[\\^$+.[\]{}()|]/g, '\\$&'); }).join('') + '$').test(name);
+}
+function permits(row, name) {
+  if ((row.disabledTools || []).indexOf(name) >= 0 || row.enabledTools && row.enabledTools.indexOf(name) < 0) return false;
+  return !(row.toolPatterns || []).some(function (pattern) { return matches(pattern, row.toolPrefix ? row.toolPrefix + name : name); });
+}
+module.exports = { normalize: normalize, permits: permits, matches: matches };

package/lib/notes-checklist.js

@@ -0,0 +1,92 @@
+// Bounded source identities shared by checklist validation and reconciliation.
+function items(text) {
+  var lines = (text || '').split('\n').slice(1);
+  var occurrences = Object.create(null);
+  var out = [];
+  var fence = null;
+  for (var i = 0; i < lines.length; i++) {
+    var line = lines[i];
+    var match = line.match(/^\s*(\x60{3,}|~{3,})/);
+    if (match) { fence = fence === match[1].charAt(0) ? null : (fence || match[1].charAt(0)); continue; }
+    if (fence || !line.trim() || /^\s*#{1,6}\s/.test(line)) continue;
+    var occurrence = occurrences[line] || 0;
+    occurrences[line] = occurrence + 1;
+    var key = line + '\u0000' + occurrence;
+    if (i <= 1000 && key.length <= 2000 && encodeURIComponent(key).length <= 2000) out.push({ index: i, key: key });
+  }
+  return out;
+}
+
+function validState(value) {
+  if (!Array.isArray(value) && (!value || typeof value !== 'object')) return false;
+  var keys = Object.keys(value);
+  if (keys.length > 1000) return false;
+  for (var i = 0; i < keys.length; i++) {
+    if (keys[i].length > 2000 || typeof value[keys[i]] !== 'boolean') return false;
+  }
+  return true;
+}
+
+function normalizeState(value, text) {
+  var state = {};
+  items(text).forEach(function (item) {
+    var checked = value && value[Array.isArray(value) ? item.index : item.key];
+    if (typeof checked === 'boolean' && Object.keys(state).length < 1000) state[item.key] = checked;
+  });
+  return state;
+}
+
+function validateChange(note, changes) {
+  if (changes.checklistIndex === undefined) return null;
+  if (!Number.isInteger(changes.checklistIndex) || changes.checklistIndex < 0 || changes.checklistIndex > 1000) return null;
+  if (typeof changes.checklistChecked !== 'boolean' || typeof changes.checklistSource !== 'string' || typeof changes.checklistKey !== 'string') return null;
+  if (changes.checklistSource !== note.text || changes.checklistKey.length > 2000 || (changes.text !== undefined && changes.text !== note.text)) return null;
+  var item = items(note.text).find(function (item) { return item.index === changes.checklistIndex; });
+  var state = normalizeState(note.checklistState, note.text);
+  if (item && state[item.key] === undefined && Object.keys(state).length >= 1000) return null;
+  try { return item && item.key === decodeURIComponent(changes.checklistKey) ? item.key : null; } catch (error) { return null; }
+}
+
+// Saved booleans win over Markdown markers, matching the native task controls.
+var MARKER = /^\s*(?:[-*+]\s+)?\[([ xX])\]\s*(.*)$/;
+
+function describe(note) {
+  var text = note && typeof note.text === 'string' ? note.text : '';
+  var state = normalizeState(note && note.checklistState, text);
+  var lines = text.split('\n');
+  return items(text).map(function (item) {
+    var line = lines[item.index + 1];
+    var marker = line.match(MARKER);
+    var saved = typeof state[item.key] === 'boolean' ? state[item.key] : null;
+    return {
+      item: encodeURIComponent(item.key),
+      index: item.index,
+      text: marker ? marker[2] : line.trim(),
+      checked: saved !== null ? saved : !!(marker && marker[1].toLowerCase() === 'x'),
+      saved: saved,
+    };
+  });
+}
+
+// Prompt/knowledge projection of a checklist note with its effective checks.
+function effectiveText(note) {
+  var text = note && typeof note.text === 'string' ? note.text : '';
+  if (!note || note.checklistMode !== true) return text;
+  var lines = text.split('\n');
+  describe(note).forEach(function (entry) {
+    lines[entry.index + 1] = '- [' + (entry.checked ? 'x' : ' ') + '] ' + entry.text;
+  });
+  return lines.join('\n');
+}
+
+function findItem(note, encodedKey) {
+  if (typeof encodedKey !== 'string') return null;
+  var key;
+  try { key = decodeURIComponent(encodedKey); } catch (error) { return null; }
+  return items(note && note.text).find(function (item) { return item.key === key; }) || null;
+}
+
+module.exports = {
+  validState: validState, normalizeState: normalizeState, validateChange: validateChange,
+  describe: describe, effectiveText: effectiveText, findItem: findItem,
+};

package/lib/notes.js

@@ -4,6 +4,7 @@ var crypto = require("crypto");
 var config = require("./config");
 var utils = require("./utils");
 var lifecycle = require("./notes-lifecycle");
+var checklist = require("./notes-checklist");
 
 function createNotesManager(opts) {
   var cwd = opts.cwd;
@@ -61,6 +62,8 @@ function createNotesManager(opts) {
       h: typeof data.h === "number" ? data.h : 180,
       color: data.color || "purple",
       opacity: typeof data.opacity === "number" ? data.opacity : 0.64,
+      checklistMode: data.checklistMode === true,
+      checklistState: checklist.validState(data.checklistState) ? checklist.normalizeState(data.checklistState, data.text || "") : [],
       minimized: false,
       // A new note is always an open attention item.
       state: lifecycle.STATE_OPEN,
@@ -84,13 +87,33 @@ function createNotesManager(opts) {
   function update(id, changes) {
     for (var i = 0; i < notes.length; i++) {
       if (notes[i].id === id) {
-        var allowed = ["text", "x", "y", "w", "h", "color", "minimized", "zIndex", "opacity"];
+        if (changes.checklistConvert === true) {
+          if (changes.checklistSource !== notes[i].text || changes.checklistVersion !== notes[i].updatedAt || notes[i].checklistMode === true) return null;
+          changes = Object.assign({}, changes, { text: "", checklistState: {}, checklistMode: true });
+        }
+        if (changes.checklistEdit === true && (notes[i].checklistMode !== true || changes.checklistSource !== notes[i].text || changes.checklistVersion !== notes[i].updatedAt || typeof changes.text !== "string")) return null;
+        if (changes.checklistMode !== undefined && typeof changes.checklistMode !== "boolean") return null;
+        if (changes.checklistState !== undefined && !checklist.validState(changes.checklistState)) return null;
+        var checklistKey = checklist.validateChange(notes[i], changes);
+        if (changes.checklistIndex !== undefined && !checklistKey) return null;
+        var previous = {};
+        var snapshotKeys = ["text", "x", "y", "w", "h", "color", "minimized", "zIndex", "opacity", "checklistMode", "checklistState", "hidden", "state", "closedAt", "closedBy", "updatedAt"];
+        for (var s = 0; s < snapshotKeys.length; s++) previous[snapshotKeys[s]] = notes[i][snapshotKeys[s]];
+        var allowed = ["text", "x", "y", "w", "h", "color", "minimized", "zIndex", "opacity", "checklistMode", "checklistState"];
         for (var j = 0; j < allowed.length; j++) {
           var key = allowed[j];
           if (changes[key] !== undefined) {
             notes[i][key] = changes[key];
           }
         }
+        if (checklistKey) {
+          var state = checklist.normalizeState(notes[i].checklistState, notes[i].text);
+          state[checklistKey] = changes.checklistChecked === true;
+          notes[i].checklistState = state;
+        }
+        if (changes.text !== undefined || changes.checklistState !== undefined || checklistKey) {
+          notes[i].checklistState = checklist.normalizeState(notes[i].checklistState, notes[i].text);
+        }
         // `hidden` is the legacy spelling of the lifecycle. Route it through the
         // transitions so state, hidden, and the close provenance can never
         // disagree, and so an old client cannot half-apply a close.
@@ -98,8 +121,11 @@ function createNotesManager(opts) {
           if (changes.hidden === true) lifecycle.applyClose(notes[i], changes.actor || null, Date.now());
           else lifecycle.applyReopen(notes[i]);
         }
-        notes[i].updatedAt = Date.now();
-        saveToDisk();
+        notes[i].updatedAt = Math.max(Date.now(), (previous.updatedAt || 0) + 1);
+        if (!saveToDisk()) {
+          for (var p = 0; p < snapshotKeys.length; p++) notes[i][snapshotKeys[p]] = previous[snapshotKeys[p]];
+          return null;
+        }
         return notes[i];
       }
     }
@@ -120,6 +146,25 @@ function createNotesManager(opts) {
     return null;
   }
 
+  // Human close includes the visible draft and an exact canonical snapshot.
+  // Recheck it here, then persist draft + lifecycle/removal in one transaction.
+  function closeHuman(id, changes, actor) {
+    for (var i = 0; i < notes.length; i++) {
+      var note = notes[i];
+      if (note.id !== id) continue;
+      if (note.text !== changes.expectedText || note.updatedAt !== changes.expectedVersion || typeof changes.draftText !== "string") return null;
+      if (!changes.draftText.trim()) {
+        notes.splice(i, 1);
+        if (saveToDisk()) return { removed: note };
+        notes.splice(i, 0, note);
+        return null;
+      }
+      var updated = update(id, { text: changes.draftText, hidden: true, actor: actor });
+      return updated ? { note: updated } : null;
+    }
+    return null;
+  }
+
   // Reopen a closed note. Idempotent.
   function reopen(id) {
     for (var i = 0; i < notes.length; i++) {
@@ -199,7 +244,8 @@ function createNotesManager(opts) {
     for (var j = 0; j < active.length; j++) {
       var n = active[j];
       var label = n.color ? "[" + n.color + "]" : "";
-      lines.push("- " + label + " " + n.text.trim());
+      // Checklist notes project their saved completion, not stale Markdown marks.
+      lines.push("- " + label + " " + checklist.effectiveText(n).trim());
     }
     return lines.join("\n");
   }
@@ -211,6 +257,7 @@ function createNotesManager(opts) {
     create: create,
     update: update,
     close: close,
+    closeHuman: closeHuman,
     reopen: reopen,
     remove: remove,
     removeClosed: removeClosed,

package/lib/os-user-diagnostics.js

@@ -17,12 +17,10 @@ function commandAvailable(command, execFile) {
 
 function credentialPaths(home) {
   if (!home) return [];
-  return [
-    home + "/.claude",
-    home + "/.codex",
+  return require("./yoke/maintenance").credentialPaths(home).concat([
     home + "/.config/gh",
     home + "/.config/gcloud",
-  ];
+  ]);
 }
 
 function accessStatus(checks) {

package/lib/os-users.js

@@ -153,6 +153,19 @@ function fsAsUser(op, args, osUserInfo) {
     });
     var binOutput = execFileSync(binSpawn.command, binSpawn.args, binSpawn.options);
     return { buffer: Buffer.from(binOutput.trim(), "base64") };
+  } else if (op === 'write_exact') {
+    script = [
+      "var fs = require('fs'), crypto = require('crypto'), path = require('path');",
+      "var f = " + JSON.stringify(args.file) + "; var expected = " + JSON.stringify(args.expected) + ";",
+      "var root = " + JSON.stringify(args.root) + "; var relative = path.relative(root, f);",
+      "function checkPath() { if (fs.realpathSync(root) !== root || path.isAbsolute(relative) || relative.split(path.sep).indexOf('..') >= 0) throw new Error('The canonical file boundary changed.'); var at = root; relative.split(path.sep).forEach(function (part) { at = path.join(at, part); if (fs.lstatSync(at).isSymbolicLink()) throw new Error('File parent symlinks are unavailable.'); }); }",
+      "checkPath();",
+      "var fd = fs.openSync(f, fs.constants.O_RDWR | fs.constants.O_NOFOLLOW);",
+      "try { var s = fs.fstatSync(fd);",
+      "if (!s.isFile() || s.nlink !== 1 || s.dev !== expected.dev || s.ino !== expected.ino || s.mode !== expected.mode || s.uid !== expected.uid || s.gid !== expected.gid || s.size !== expected.size || s.mtimeMs !== expected.mtime || crypto.createHash('sha256').update(fs.readFileSync(fd, 'utf8')).digest('hex') !== expected.hash) throw new Error('The exact file revision changed.');",
+      "checkPath(); fs.ftruncateSync(fd, 0); var bytes = Buffer.from(" + JSON.stringify(args.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); }",
+      "process.stdout.write(JSON.stringify({ ok: true }));",
+    ].join(' ');
   } else if (op === "write") {
     script = [
       "var fs = require('fs');",
@@ -267,18 +280,18 @@ function isHomeDirectory(dirPath) {
  * Uses setfacl to add recursive + default ACL entries.
  * Skips home directories to avoid slow recursive ACL on large trees.
  */
-function grantProjectAccess(projectPath, linuxUser) {
+function grantProjectAccess(projectPath, linuxUser, options) {
   if (isHomeDirectory(projectPath)) {
     console.log("[os-users] Skipping ACL for home directory: " + projectPath);
-    return;
+    return true;
   }
   if (!isSafeLinuxUsername(linuxUser)) {
     console.error("[os-users] Invalid Linux username for ACL grant: " + linuxUser);
-    return;
+    return false;
   }
   var cacheKey = aclCacheKey(projectPath, linuxUser);
-  if (_aclGrantCache[cacheKey]) {
-    return;
+  if (_aclGrantCache[cacheKey] && !(options && options.force)) {
+    return true;
   }
   try {
     // Recursive ACL for existing files
@@ -295,6 +308,7 @@ function grantProjectAccess(projectPath, linuxUser) {
     });
     _aclGrantCache[cacheKey] = true;
     console.log("[os-users] Granted ACL access for " + linuxUser + " on " + projectPath);
+    return true;
   } catch (e) {
     delete _aclGrantCache[cacheKey];
     var errMsg = (e.stderr || e.message || "").toString();
@@ -305,6 +319,7 @@ function grantProjectAccess(projectPath, linuxUser) {
     } else {
       console.error("[os-users] Failed to grant ACL access for " + linuxUser + " on " + projectPath + ": " + errMsg);
     }
+    return false;
   }
 }
 
@@ -460,72 +475,11 @@ function getLinuxUserUid(username) {
  * hardcoded ~/.local/bin/claude path.
  * Returns true if claude resolves, false otherwise.
  */
-function claudeAvailableForUser(linuxName) {
-  if (!isSafeLinuxUsername(linuxName)) return false;
-  try {
-    var out = execFileSync("su", ["-", linuxName, "-c", "command -v claude"], {
-      encoding: "utf8",
-      timeout: 10000,
-      stdio: "pipe",
-    }).trim();
-    return out.length > 0;
-  } catch (e) {
-    return false;
-  }
-}
-
-/**
- * Install Claude CLI for a Linux user account.
- * Downloads and runs the install script, then ensures PATH is configured.
- * Non-fatal: logs errors but does not throw.
- * Skips entirely when claude is already resolvable for the user, or when
- * CLAY_SKIP_CLAUDE_INSTALL is set (bring-your-own-claude).
- */
-function installClaudeCli(linuxName) {
-  if (process.env.CLAY_SKIP_CLAUDE_INSTALL) {
-    console.log("[os-users] CLAY_SKIP_CLAUDE_INSTALL set, skipping Claude CLI install for " + linuxName);
-    return;
-  }
-  if (claudeAvailableForUser(linuxName)) {
-    console.log("[os-users] Claude CLI already available for " + linuxName + ", skipping install");
-    return;
-  }
-  try {
-    if (!isSafeLinuxUsername(linuxName)) throw new Error("Invalid Linux username");
-    // Download and run the Claude CLI install script as the target user
-    execFileSync("su", ["-", linuxName, "-c", "curl -fsSL https://claude.ai/install.sh | bash"], {
-      encoding: "utf8",
-      timeout: 60000,
-      stdio: "pipe",
-    });
-    console.log("[os-users] Claude CLI installed for " + linuxName);
-  } catch (e) {
-    var msg = (e.stderr || e.message || "").trim();
-    console.error("[os-users] Failed to install Claude CLI for " + linuxName + ": " + msg);
-    return;
-  }
-
-  // Append PATH export to the user's shell config if not already present
-  try {
-    var userInfo = resolveOsUserInfo(linuxName);
-    var home = userInfo.home || ("/home/" + linuxName);
-    var rcPath = fs.existsSync(path.join(home, ".zshrc")) ? path.join(home, ".zshrc") : path.join(home, ".bashrc");
-    var exportLine = 'export PATH="$HOME/.local/bin:$PATH"';
-    var existing = "";
-    try { existing = fs.readFileSync(rcPath, "utf8"); } catch (e2) {}
-    if (existing.indexOf(exportLine) === -1) {
-      var prefix = existing && !/\n$/.test(existing) ? "\n" : "";
-      fs.appendFileSync(rcPath, prefix + exportLine + "\n", "utf8");
-      try { fs.chownSync(rcPath, userInfo.uid, userInfo.gid); } catch (e3) {}
-      console.log("[os-users] PATH export appended to " + rcPath + " for " + linuxName);
-    } else {
-      console.log("[os-users] PATH already configured in " + rcPath + " for " + linuxName);
-    }
-  } catch (e) {
-    var rcMsg = (e.stderr || e.message || "").trim();
-    console.error("[os-users] Failed to configure PATH for " + linuxName + ": " + rcMsg);
-  }
+function defaultRuntimeProvisioning() {
+  return require("./yoke/provisioning").forProvider("claude", { isSafeLinuxUsername: isSafeLinuxUsername, resolveOsUserInfo: resolveOsUserInfo });
 }
+function claudeAvailableForUser(user) { return defaultRuntimeProvisioning().available(user); }
+function installClaudeCli(user) { return defaultRuntimeProvisioning().install(user); }
 
 /**
  * Provision a Linux user account for a Clay user.

package/lib/pane-pending-interactions.js

@@ -0,0 +1,20 @@
+// Pending requests can precede the initial history window. Restate their exact
+// display payloads before snapshot completion, without resolving or replaying
+// any human decision. Client renderers deduplicate by their original IDs.
+function send(session, emit) {
+  Object.keys(session.pendingAskUser || {}).forEach(function (id) {
+    var pending = session.pendingAskUser[id];
+    var input = pending.input || { questions: pending.request && pending.request.questions || [] };
+    emit({ type: 'ask_user_pending', toolId: id, input: input });
+  });
+  Object.keys(session.pendingElicitations || {}).forEach(function (id) {
+    var request = session.pendingElicitations[id].request || {};
+    emit({ type: 'elicitation_request', requestId: id, serverName: request.serverName, message: request.message,
+      mode: request.mode || 'form', url: request.url || null, elicitationId: request.elicitationId || null, requestedSchema: request.requestedSchema || null });
+  });
+  Object.keys(session.pendingUserDialogs || {}).forEach(function (id) {
+    var request = session.pendingUserDialogs[id].request || {};
+    emit({ type: 'user_dialog_request', requestId: id, dialogKind: request.dialogKind, payload: request.payload || {}, toolUseId: request.toolUseID || null });
+  });
+}
+module.exports = { send: send };