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

package/lib/clay-product-control.js

@@ -0,0 +1,237 @@
+var crypto = require("crypto");
+var builtinMates = require("./builtin-mates");
+var accessModule = require("./workspace-query-access");
+var refs = require("./workspace-query-service");
+var provenance = require("./session-provenance");
+var personal = require("./mcp-session-access");
+
+var input = require("./clay-product-control-input");
+var ACTIONS = input.ACTIONS;
+var KEYS = input.KEYS;
+var deleteScope = require("./project-session-delete").resolveDeletionScope;
+function revision(session) {
+  return JSON.stringify([session.ownerId, session.sessionOriginId, session.cliSessionId, session.title, session.vendor,
+    session.model, session.effort, session.permissionMode, session.mode, session.runtimeMode, session.hidden,
+    session.isProcessing, session._queryStarting, session.taskStopRequested, session._pendingMessageDrainPaused,
+    session._sdkQueryGeneration, session.history && session.history.length, session.messageUUIDs,
+    session.sessionProvenance, session.pendingPush, Object.keys(session.pendingPermissions || {}), Object.keys(session.pendingAskUser || {})]);
+}
+function string(value, max) { return typeof value === "string" && value.trim() && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value); }
+function attachClayProductControl(ctx) {
+  var access = accessModule.attachWorkspaceQueryAccess(ctx);
+  var states = new WeakMap();
+  var busy = new WeakSet();
+  function bind(source) {
+    if (!source || !source.session) return null;
+    var session = source.session, generation = Number(session._sdkQueryGeneration || 0);
+    var sourceProject = ctx.getProjects().get(source.projectSlug);
+    function authorize() {
+      var project = ctx.getProjects().get(source.projectSlug);
+      if (!project || project !== sourceProject) throw new Error("Source project was deleted or replaced.");
+      var status = project.getStatus(), manager = project.getSessionManager();
+      var mate = ctx.resolveMate(source.projectOwnerId, source.mateId);
+      var definition = mate && builtinMates.getBuiltinByKey(mate.builtinKey);
+      if (!status || !status.isMate || status.mateId !== source.mateId || status.projectOwnerId !== source.projectOwnerId || !mate || mate.lifecycleDeletion || mate.id !== source.mateId || mate.builtinKey !== "clay" || !definition || !definition.hostAgent || (ctx.isMultiUser() && mate.createdBy !== source.projectOwnerId)) throw new Error("Canonical Clay ownership is no longer valid.");
+      if (manager.sessions.get(session.localId) !== session || Number(session._sdkQueryGeneration || 0) !== generation || session.taskStopRequested || session.abortController && session.abortController.signal.aborted || session.spawn || provenance.isWorker(session) || session.homeDebatePlanning || session.debateSetupMode || session._mentionInProgress) throw new Error("This canonical Clay query is stale or stopped.");
+      if (session.destroying || session.hidden || session.mateCreationMode || session._mcpForeignInput || session.sessionVisibility === "shared" || session.delegated || session._delegatedBy || session._pairDelegation) throw new Error("Product controls require a private, owner-authored canonical Clay conversation.");
+      if (ctx.isMultiUser() && !personal.canUsePersonalConnections(session, manager.sessions)) throw new Error("Foreign input cannot authorize personal product controls.");
+      if (!ctx.isMultiUser() && (session.ownerId || (session.history || []).some(function (entry) { return entry.type === "user_message" && entry.from && entry.from !== "default"; }))) throw new Error("Foreign input cannot authorize personal product controls.");
+      if (ctx.isMultiUser() && (!source.projectOwnerId || session.ownerId !== source.projectOwnerId || !ctx.findUser(source.projectOwnerId))) throw new Error("The source owner is no longer available.");
+      if (!ctx.isMultiUser() && session.ownerId && session.ownerId !== source.projectOwnerId) throw new Error("Source ownership changed.");
+      return { userId: ctx.isMultiUser() ? source.projectOwnerId : null, singleUserOwnerId: source.projectOwnerId || null };
+    }
+    try { authorize(); } catch (error) { return null; }
+    var state = states.get(session);
+    if (!state || state.generation !== generation) { state = { generation: generation, targets: new Map(), requests: new Map() }; states.set(session, state); }
+    function resolve(slug, ref) {
+      var principal = authorize(), project = ctx.getProjects().get(slug);
+      var status = project && project.getStatus();
+      if (!status || status.isMate || !access.evaluate(principal, status).accessible) throw new Error("Target project is unavailable or private.");
+      var sm = project.getSessionManager(), target = null;
+      sm.sessions.forEach(function (candidate) { if (refs.sessionRef(slug, candidate) === ref) target = candidate; });
+      if (!target || target.hidden || (ctx.isMultiUser() ? target.ownerId !== principal.userId : !!target.ownerId && target.ownerId !== principal.singleUserOwnerId)) throw new Error("Target session is unavailable or belongs to another owner.");
+      if (target.spawn || provenance.isWorker(target)) throw new Error("Worker sessions are operated by their project Driver.");
+      return { project: project, session: target, principal: principal };
+    }
+    function scope(project, target) {
+      var sm = project.getSessionManager();
+      var plan = deleteScope(sm.sessions, [target], function (item) { return (item.ownerId || null) === (target.ownerId || null); });
+      if (!plan.ok) throw new Error(plan.error);
+      return plan.ids.map(function (id) { var item = sm.sessions.get(id); return { item: item, revision: revision(item) }; });
+    }
+    function check(target, queueRequired, terminalClosing) {
+      if (Date.now() - target.created > 300000) throw new Error("Target inspection expired.");
+      var live = resolve(target.slug, target.ref);
+      if (!terminalClosing && (live.project.inspectProductSessionRuntime ? live.project.inspectProductSessionRuntime(live.session) : JSON.stringify([live.session.terminalId, live.session.runtimeTerminalId, live.session.tuiSuspended])) !== target.terminalRevision) throw new Error("Terminal runtime changed. Inspect again.");
+      if (live.project !== target.project || live.session !== target.session || revision(live.session) !== target.revision) throw new Error("The exact target revision changed. Inspect again before requesting a new action.");
+      if (queueRequired && live.project.inspectProductSessionQueue(live.principal, live.session).revision !== target.queueRevision) throw new Error("The queue revision changed. Inspect and review again.");
+      var current = scope(live.project, live.session);
+      if (current.length !== target.scope.length || current.some(function (entry, i) { return entry.item !== target.scope[i].item || entry.revision !== target.scope[i].revision; })) throw new Error("Driver or owned Worker revision changed. Inspect again.");
+      return live;
+    }
+    function capabilities() {
+      authorize();
+      return { screen: { tools: ["read_owner_screen", "inspect_owner_screen_change", "control_owner_screen"], scope: "Exact authenticated owner UI connection and owned conversation navigation; delivery and client acceptance do not prove rendering. Screen context is server-known connection/conversation only. Owner notification read and reviewed exact dismissal use the existing queue. No arbitrary messages, settings or contextual UI.", receipts: "Query-local attempts survive catalog rebinding only. Read delivery status; never blindly repeat an uncertain delivery." }, actions: ACTIONS, scheduling: { tools: ["begin_schedule_control_interview", "read_schedule_controls", "inspect_schedule_change", "control_schedules"], mates: "Own and same-owner private Mate conversation list/read/create/update/cancel. No pause/resume/run-now action exists for logical Mate schedules.", projects: "Selected owned ordinary-project Driver list/read, proposed creation requiring final workbench Create task, reviewed update/pause/resume/cancel/run through existing scheduling services. Run is queued, never task completion; Workers remain owned by the project scheduled executor.", receipts: "Dated request IDs; 24-hour receipt window, at most 100 retained receipts on the source conversation. Interrupted writes require inspection, never blind execution." }, projectRecords: { tools: ["read_project_records", "inspect_project_record_change", "control_project_records"], scope: "Selected owned ordinary projects, including worktree context. Exact owner review; query-local bounded retry receipts.", unsupported: ["githubFiling", "workSessionLaunch", "scheduledResultMutation"], routing: "Use the existing reviewed project assignment or follow-up tools for Driver execution. Record changes never run Git commits." }, mateKnowledge: { tools: ["read_mate_knowledge_control", "inspect_mate_knowledge_change", "control_mate_knowledge"], review: "Exact owner-reviewed Markdown and typed database/record operations; serialized intents are limited to 1400 characters within the existing review card.", unsupported: ["hardDatabaseOrRecordDeletion", "legacyJsonlWrites", "promotionOrSharing", "arbitraryFilesystemOrSql", "userKnowledgeCuration"] }, mateLifecycle: { actions: ["list", "inspect", "profile", "delete"], profileFields: ["name", "bio", "workspaceColor", "avatarCatalogId"], deletion: "Idle owner-private Mates only; canonical Clay and primary Mates are protected. Stored transcripts and provider history are retained. Pending runtime cleanup without closure proof requires operator recovery.", excluded: ["knowledge", "directMessages", "schedules", "sharing", "ownershipTransfer", "model"] }, mateChat: { tools: ["read_mate_chat_control", "inspect_mate_chat_change", "control_mate_chat"], actions: ["send", "stop", "model", "vendor", "effort"], scope: "Exact existing same-owner private Mate conversation; vendor selection requires a fresh idle conversation. Delegated messages are untrusted and never owner input. Dated durable retry receipts, no implicit resume or thread migration." }, workspace: { tools: ["read_project_workspace", "read_workspace_receipt", "inspect_workspace_change", "control_project_workspace"], files: "Bounded list/read and exact reviewed writes to existing regular text files within a selected owned ordinary project. Symlinks, hardlinks, managed settings, create/delete/move and arbitrary filesystem operations are excluded.", git: "Status and changed-file diff; exact reviewed selected-path stage/unstage only. No linked Git metadata/submodules, commits, pull/push, PR operations or arbitrary Git arguments.", terminal: "Owner shell list/scrollback and reviewed blank shell creation, rename, resize and acknowledged close. No input, commands, coding-agent/login terminals or Worker control." }, approval: "All changes except Stop require an authenticated owner review of the exact action and target revision.",
+        taskExecution: "Use propose_project_assignment or propose_project_follow_up to route execution through a project Driver. A stopped session cannot be resumed by this control layer.",
+        unsupported: { archive: "No authoritative session archive service exists.", send: "Use reviewed Driver assignment or follow-up.", runtime: "New TUI presentation and cross-provider thread migration are unavailable. runtime=gui closes a legacy Claude terminal with acknowledged exit. vendor_new_session creates a private blank GUI session and retains the original without execution.", projectLifecycle: ctx.projectLifecycle ? "Create, register, rename, remove registration, project environment and owner access controls use exact human review. OS filesystem sharing changes are unavailable through this service." : "Unavailable in this runtime." },
+        excluded: ["serverSettings", "userSettings", "workerCreation", "pairOrchestration"] };
+    }
+    function inspect(args) {
+      if (!args || Object.keys(args).some(function (key) { return ["projectSlug", "sessionRef"].indexOf(key) < 0; }) || !string(args.projectSlug, 200) || !/^session:[\w-]{24}$/.test(args.sessionRef)) throw new Error("An exact projectSlug and opaque sessionRef are required.");
+      var live = resolve(args.projectSlug, args.sessionRef), target = live.session;
+      if (state.targets.size >= 100) state.targets.delete(state.targets.keys().next().value);
+      var queue = typeof live.project.inspectProductSessionQueue === "function" ? live.project.inspectProductSessionQueue(live.principal, target) : null;
+      var token = "control:" + crypto.randomUUID();
+      state.targets.set(token, { slug: args.projectSlug, ref: args.sessionRef, project: live.project, session: target, ownerId: target.ownerId || null, queueRevision: queue && queue.revision, terminalRevision: live.project.inspectProductSessionRuntime ? live.project.inspectProductSessionRuntime(target) : JSON.stringify([target.terminalId, target.runtimeTerminalId, target.tuiSuspended]), revision: revision(target), scope: scope(live.project, target), created: Date.now() });
+      var sm = live.project.getSessionManager(), vendor = target.vendor || sm.defaultVendor || "claude";
+      var caps = (sm.capabilitiesByVendor || {})[vendor] || {};
+      return { queue: queue, availableVendors: sm.availableVendors || [], runtimeMode: target.runtimeMode || target.mode || "gui", runtimeTransition: "Only legacy Claude terminal to GUI chat is supported; terminal exit must be acknowledged. No execution starts.", vendorTransition: "vendor selects a fresh idle GUI Driver provider; vendor_new_session creates a private blank session and retains an established original without migrating history.", targetToken: token, projectSlug: args.projectSlug, sessionRef: args.sessionRef, title: target.title || "New Session", vendor: vendor, model: target.model || null, effort: target.effort || null, permissionMode: target.permissionMode || "default", processing: !!target.isProcessing, stopped: !!target.taskStopRequested, queuePaused: !!target._pendingMessageDrainPaused,
+        providerCapabilities: { fork: caps.fork === true, conversationRewind: caps.rollback === true || caps.rewind === true, effort: caps.effort === true, modelCatalogAvailable: !!((sm.modelsByVendor || {})[vendor] || []).length }, deletionCount: scope(live.project, target).length, checkpoints: (target.messageUUIDs || []).map(function (entry) { return { uuid: entry.uuid, type: entry.type }; }), actions: ACTIONS, models: (sm.modelsByVendor || {})[vendor] || [], permissions: require("./session-permission-mode").clientState(target, sm.currentPermissionMode, vendor), expiresInSeconds: 300 };
+    }
+    async function run(args, target) {
+      var queueAction = args.action.indexOf("queue_") === 0;
+      var live = check(target, queueAction);
+      if (Date.now() - target.created > 300000) throw new Error("Target inspection expired.");
+      if (args.action !== "stop") {
+        var question = input.description(args) + "\nProject: " + target.slug + "\nSession: " + (live.session.title || "New Session") + " (" + target.ref + ")\nWhy: " + args.why;
+        if (queueAction) question += "\nQueue revision: " + target.queueRevision + ". Queue changes never resume a stopped Driver.";
+        if (args.action === "delete") question += "\nPermanently deletes " + target.scope.length + " sessions: this Driver and all its owned Worker history. Inspect again if anything changes.";
+        var result = await sourceProject.requestProductControlReview(session, question, function () { authorize(); check(target, queueAction); });
+        if (result.status !== "submitted" || !result.answers.control || result.answers.control.length !== 1 || result.answers.control[0] !== "Apply exact change") return { status: "cancelled", action: args.action };
+        live = check(target, queueAction);
+      }
+      if (!queueAction && live.session.taskStopRequested && args.action !== "stop" && args.action !== "rename" && args.action !== "delete") throw new Error("The target was stopped. Resume it explicitly through its Driver.");
+      if (typeof live.project.applyProductSessionAction !== "function") throw new Error("Target project controls are unavailable.");
+      if (busy.has(live.session)) throw new Error("Another control action is applying to this target. Inspect again after it settles.");
+      busy.add(live.session);
+      var result;
+      try { result = await live.project.applyProductSessionAction(live.principal, live.session, args.action, args.value, function () { check(target, queueAction, args.action === "runtime"); }, { args: args, requestKey: source.projectSlug + "\n" + (session.sessionOriginId || session.localId) + "\n" + args.requestId }); }
+      finally { busy.delete(live.session); }
+      return Object.assign({ status: "completed", action: args.action, projectSlug: target.slug, sessionRef: target.ref, why: args.why }, result);
+    }
+    function act(args) {
+      authorize();
+      input.validate(args);
+      args = Object.assign({}, args);
+      if (args.ids) args.ids = args.ids.slice();
+      var target = state.targets.get(args.targetToken);
+      if (!target) throw new Error("Inspect the exact target first.");
+      var key = JSON.stringify(KEYS.map(function (name) { return args[name] === undefined ? null : args[name]; }));
+      var old = state.requests.get(args.requestId);
+      if (old) { if (old.key !== key) throw new Error("requestId already names a different exact action."); var project = ctx.getProjects().get(target.slug);
+        if (project !== target.project || !access.evaluate(authorize(), project.getStatus()).accessible) throw new Error("Target access changed.");
+        var current = project.getSessionManager().sessions.get(target.session.localId);
+        if (current && (current !== target.session || (current.ownerId || null) !== target.ownerId)) throw new Error("Target was replaced.");
+        return old.promise; }
+      if (state.requests.size >= 100) throw new Error("Too many control requests in this query.");
+      var promise = Promise.resolve().then(function () { return run(args, target); }).catch(function (error) { return Object.assign({ status: "failed", action: args.action, error: error.message }, error.productControlResult || {}); });
+      state.requests.set(args.requestId, { key: key, promise: promise });
+      return promise;
+    }
+    if (!state.lifecycle) state.lifecycle = { targets: new Map(), requests: new Map() };
+    var lifecycle = require("./clay-project-lifecycle").attachClayProjectLifecycle({
+      state: state.lifecycle, service: ctx.projectLifecycle, authorize: authorize, getProjects: ctx.getProjects, findUser: ctx.findUser,
+      permissions: ctx.lifecyclePermissions, canUsePath: ctx.canUsePath, getAccess: ctx.onGetProjectAccess,
+      sourceKey: source.projectSlug + "\n" + (session.sessionOriginId || session.localId),
+      creationRevision: function (anchor) { return ctx.projectLifecycle.creationRevision(anchor); },
+      review: function (question, check) { return sourceProject.requestProductControlReview(session, question, check); },
+    });
+    if (!state.mates) state.mates = { targets: new Map(), requests: new Map() };
+    var mateControls = require('./clay-mate-lifecycle').attachClayMateLifecycle({ state: state.mates, authorize: authorize,
+      getService: ctx.getMateLifecycle, getProjects: ctx.getProjects,
+      review: function (question, check) { return sourceProject.requestProductControlReview(session, question, check); } });
+    if (!state.knowledge) state.knowledge = { targets: new Map(), requests: new Map() };
+    var knowledgeControls = require('./clay-mate-knowledge').attachClayMateKnowledge({ state: state.knowledge, authorize: authorize,
+      getProjects: ctx.getProjects, resolveMate: ctx.resolveMate, getMateDir: ctx.getMateDir,
+      sourceKey: source.projectSlug + '\n' + (session.sessionOriginId || session.localId),
+      review: function (question, check) { return sourceProject.requestProductControlReview(session, question, check); } });
+    if (!state.records) state.records = { targets: new Map(), requests: new Map() };
+    var recordControls = require('./clay-project-records').attachClayProjectRecords({ state: state.records, authorize: authorize,
+      services: function () { return ctx.getRecordServices && ctx.getRecordServices(); },
+      resolve: function (slug) {
+        var principal = authorize(), project = ctx.getProjects().get(slug), status = project && project.getStatus();
+        var decision = status && access.evaluate(principal, status);
+        if (!status || status.isMate || !decision.owned || !decision.accessible) throw new Error('Selected records require an owned ordinary project with live access.');
+        if (status.isWorktree) {
+          var parent = ctx.getProjects().get(status.parentSlug), parentStatus = parent && parent.getStatus();
+          if (!parentStatus || parentStatus.isMate || !access.evaluate(principal, parentStatus).owned || !access.evaluate(principal, parentStatus).accessible) throw new Error('Selected worktree records require live parent ownership and access.');
+        }
+        return { principal: principal, project: project, status: status };
+      },
+      actor: function () { authorize(); provenance.ensureOrigin(session); return { type: 'canonicalClay', userId: session.ownerId || null, displayName: 'Clay', sourceProjectSlug: source.projectSlug, mateId: source.mateId, sessionKey: session.cliSessionId || 'local:' + session.localId, sessionOriginId: session.sessionOriginId, vendor: session.vendor || null }; },
+      review: function (question, check) { return sourceProject.requestProductControlReview(session, question, check); } });
+    if (!state.scheduling) state.scheduling = { targets: new Map(), requests: new Map(), interview: false };
+    var scheduleControls = require('./clay-scheduling').attachClayScheduling({ state: state.scheduling, authorize: authorize, session: session,
+      multiUser: ctx.isMultiUser, getProjects: ctx.getProjects, resolveMate: ctx.resolveMate, getMateDir: ctx.getMateDir,
+      mateSlug: function (id) {
+        var found;
+        ctx.getProjects().forEach(function (project, slug) { var status = project.getStatus(); if (status.isMate && status.mateId === id) found = slug; });
+        if (!found) throw new Error('The Mate scheduling runtime is unavailable.'); return found;
+      },
+      authorizeProject: function (principal, status) {
+        var decision = access.evaluate(principal, status);
+        if (!decision.owned || !decision.accessible) throw new Error('Scheduling requires live ordinary-project ownership and access.');
+        if (status.isWorktree) { var parent = ctx.getProjects().get(status.parentSlug), parentStatus = parent && parent.getStatus(); if (!parentStatus || parentStatus.isMate || !access.evaluate(principal, parentStatus).owned || !access.evaluate(principal, parentStatus).accessible) throw new Error('Scheduling requires live parent-project ownership and access.'); }
+      },
+      actor: function () { authorize(); provenance.ensureOrigin(session); return { type: 'canonicalClay', userId: session.ownerId || null, sourceProjectSlug: source.projectSlug, mateId: source.mateId, sessionOriginId: session.sessionOriginId, vendor: session.vendor || null }; },
+      sourceKey: source.projectSlug + '\n' + (session.sessionOriginId || session.localId),
+      save: function () { return sourceProject.getSessionManager().saveSessionFile(session); },
+      review: function (question, check) { return sourceProject.requestProductControlReview(session, question, check); } });
+    if (!state.mateChat) state.mateChat = { targets: new Map(), requests: new Map() };
+    var mateChatControls = require('./clay-mate-chat').attachClayMateChat({
+      state: state.mateChat, authorize: authorize, session: session, multiUser: ctx.isMultiUser,
+      sourceIdentity: function () {
+        var status = sourceProject.getStatus(), owner = source.projectOwnerId || 'default';
+        if (require('path').resolve(status.path) !== require('path').resolve(ctx.getMateDir(owner, source.mateId))) throw new Error('The canonical source Mate directory changed.');
+        return sourceProject.getMateChatControl().validate(session);
+      },
+      getProjects: ctx.getProjects, resolveMate: ctx.resolveMate, getMateDir: ctx.getMateDir,
+      save: function () { return sourceProject.getSessionManager().saveSessionFile(session); },
+      actor: function () { authorize(); return { mateId: source.mateId, sourceProjectSlug: source.projectSlug, sourceSessionRef: refs.sessionRef(source.projectSlug, session) }; },
+      review: function (question, check) { return sourceProject.requestProductControlReview(session, question, check); },
+    });
+    if (!state.workspace) state.workspace = { targets: new Map(), requests: new Map() };
+    var workspaceControls = require('./clay-workspace-controls').attachWorkspaceControls({
+      state: state.workspace, session: session, authorize: authorize, getProjects: ctx.getProjects,
+      sourceIdentity: function () {
+        var status = sourceProject.getStatus(), owner = source.projectOwnerId || 'default';
+        if (require('path').resolve(status.path) !== require('path').resolve(ctx.getMateDir(owner, source.mateId))) throw new Error('Canonical source directory changed.');
+        return sourceProject.getMateChatControl().validate(session);
+      },
+      authorizeProject: function (principal, status) {
+        var decision = access.evaluate(principal, status);
+        if (!decision.owned || !decision.accessible) throw new Error('Workspace controls require current ordinary-project ownership and access.');
+        if (status.isWorktree) {
+          var parent = ctx.getProjects().get(status.parentSlug), parentStatus = parent && parent.getStatus();
+          if (!parentStatus || parentStatus.isMate || !access.evaluate(principal, parentStatus).owned || !access.evaluate(principal, parentStatus).accessible) throw new Error('Worktree controls require current parent ownership and access.');
+        }
+      },
+      save: function () { return sourceProject.getSessionManager().saveSessionFile(session); },
+      review: function (question, check) { return sourceProject.requestProductControlReview(session, question, check); },
+    });
+    if (!state.screen) state.screen = { targets: new Map(), requests: new Map() };
+    var screenControls = require('./clay-screen-controls').attachScreenControls({
+      state: state.screen, session: session, authorize: authorize, getProjects: ctx.getProjects,
+      getService: ctx.getOwnerUi, getNotifications: ctx.getNotifications,
+      sourceIdentity: function () {
+        var status = sourceProject.getStatus(), owner = source.projectOwnerId || 'default';
+        if (require('path').resolve(status.path) !== require('path').resolve(ctx.getMateDir(owner, source.mateId))) throw new Error('Canonical source directory changed.');
+        return sourceProject.getMateChatControl().validate(session);
+      },
+      authorizeProject: function (principal, status) {
+        if (status.isMate) {
+          var mate = ctx.resolveMate(source.projectOwnerId, status.mateId);
+          if (!mate || mate.lifecycleDeletion || status.projectOwnerId !== source.projectOwnerId || ctx.isMultiUser() && mate.createdBy !== source.projectOwnerId || require('path').resolve(status.path) !== require('path').resolve(ctx.getMateDir(source.projectOwnerId || 'default', status.mateId))) throw new Error('Private Mate navigation access denied.');
+        } else {
+          var decision = access.evaluate(principal, status);
+          if (!decision.owned || !decision.accessible || ctx.canUsePath && !ctx.canUsePath(principal.userId, status.path)) throw new Error('Navigation requires current project ownership and access.');
+          if (status.isWorktree) { var parent = ctx.getProjects().get(status.parentSlug), parentStatus = parent && parent.getStatus(); if (!parentStatus || !access.evaluate(principal, parentStatus).owned || !access.evaluate(principal, parentStatus).accessible) throw new Error('Worktree parent access changed.'); }
+        }
+      },
+      review: function (question, check) { return sourceProject.requestProductControlReview(session, question, check); }
+    });
+    return Object.assign({ capabilities: capabilities, inspect: inspect, act: act, inspectProject: lifecycle.inspectProject, actProject: lifecycle.actProject }, mateControls, knowledgeControls, recordControls, scheduleControls, mateChatControls, workspaceControls, screenControls);
+  }
+  return { bind: bind };
+}
+module.exports = { attachClayProductControl: attachClayProductControl };

package/lib/clay-project-lifecycle.js

@@ -0,0 +1,154 @@
+// Query-bound review of typed project intents; no transport impersonation.
+var crypto = require('crypto');
+var fs = require('fs');
+var path = require('path');
+var ACTIONS = ['create', 'register', 'rename', 'remove', 'visibility', 'allowed_users', 'session_visibility', 'environment', 'owner', 'reconcile', 'recover_registration'];
+function hash(value) { return crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+function attachClayProjectLifecycle(ctx) {
+  var targets = ctx.state.targets, requests = ctx.state.requests;
+  var service = ctx.service;
+  function principal() {
+    var actor = ctx.authorize();
+    if (!service) throw new Error('Project lifecycle is unavailable in this runtime.');
+    return actor;
+  }
+  function user() { var actor = principal(); return actor.userId ? ctx.findUser(actor.userId) : null; }
+  function permission(action) {
+    var account = user();
+    if (account) {
+      var perms = ctx.permissions(account);
+      if (action === 'environment' && !perms.projectSettings) throw new Error('Project settings access is not permitted.');
+      if ((action === 'create' || action === 'register') && !perms.createProject || action === 'remove' && !perms.deleteProject) throw new Error('Your project lifecycle permission is no longer available.');
+    }
+    return account;
+  }
+  function owned(slug) {
+    var actor = principal(), runtime = ctx.getProjects().get(slug), status = runtime && runtime.getStatus();
+    var record = ctx.getAccess(slug);
+    if (!status || status.isMate || /^mate-/.test(slug) || slug.indexOf('--') >= 0 || !record || record.error || record.isMate || record.ownershipRecovery || (actor.userId ? record.ownerId !== actor.userId : !!record.ownerId && record.ownerId !== actor.singleUserOwnerId)) throw new Error('Project controls require live ownership of an ordinary parent project.');
+    return runtime;
+  }
+  function validate(args) {
+    if (!args || Object.keys(args).some(function (key) { return ['action', 'projectSlug', 'name', 'path', 'value'].indexOf(key) < 0; }) || ACTIONS.indexOf(args.action) < 0) throw new Error('Choose a typed project lifecycle action.');
+    var allowed = ['action'];
+    if (args.action === 'create') {
+      allowed.push('name'); if (typeof args.name !== 'string' || !/^[a-zA-Z0-9_-]{1,100}$/.test(args.name)) throw new Error('Provide a valid project name.');
+    } else if (args.action === 'register') {
+      allowed.push('path'); if (typeof args.path !== 'string' || args.path.length > 4096 || !path.isAbsolute(args.path) || /[\u0000-\u001f]/.test(args.path)) throw new Error('Provide an absolute existing directory path.');
+    } else {
+      allowed.push('projectSlug'); if (typeof args.projectSlug !== 'string' || !args.projectSlug || args.projectSlug.length > 200) throw new Error('Provide an exact projectSlug.');
+      if (args.action !== 'remove') allowed.push('value');
+    }
+    if (Object.keys(args).some(function (key) { return allowed.indexOf(key) < 0; })) throw new Error('Fields do not match the project action.');
+    if (args.action === 'allowed_users') {
+      if (!Array.isArray(args.value) || args.value.length > 100 || args.value.some(function (id, i) { return typeof id !== 'string' || !ctx.findUser(id) || args.value.indexOf(id) !== i; })) throw new Error('Choose unique existing account IDs.');
+    } else if (args.action !== 'create' && args.action !== 'register' && args.action !== 'remove' && args.action !== 'reconcile' && args.action !== 'recover_registration') {
+      if (typeof args.value !== 'string' || args.value.length > (args.action === 'environment' ? 10000 : 100) || /\u0000/.test(args.value)) throw new Error('Provide a bounded exact value.');
+      if (args.action === 'environment') { var error = require('./runtime-env').validateEnvString(args.value); if (error) throw new Error(error); }
+    }
+  }
+  function runtimeScope(slug) {
+    var scope = [];
+    ctx.getProjects().forEach(function (project, key) {
+      if (key !== slug && key.indexOf(slug + '--') !== 0) return;
+      var sessions = [];
+      project.getSessionManager().sessions.forEach(function (session) {
+        sessions.push([session, JSON.stringify([session.localId, session.sessionOriginId, session.ownerId, session.title, session.vendor, session.model, session.effort, session.permissionMode, session.sessionVisibility, session.isProcessing, session._queryStarting, session.taskStopRequested, session._sdkQueryGeneration, session.history && session.history.length, session.messageUUIDs, Object.keys(session.pendingPermissions || {}), Object.keys(session.pendingAskUser || {})])]);
+      });
+      scope.push({ slug: key, project: project, sessions: sessions });
+    });
+    return scope;
+  }
+  function sameScope(previous, current) {
+    return previous.length === current.length && previous.every(function (entry, i) {
+      var other = current[i]; return entry.slug === other.slug && entry.project === other.project && entry.sessions.length === other.sessions.length && entry.sessions.every(function (session, j) { return session[0] === other.sessions[j][0] && session[1] === other.sessions[j][1]; });
+    });
+  }
+  function inspect(args) {
+    validate(args);
+    args = JSON.parse(JSON.stringify({ action: args.action, projectSlug: args.projectSlug, name: args.name, path: args.path, value: args.value }));
+    var account = permission(args.action), runtime = null, revision = null;
+    service.assertSupported(args.action);
+    var recovery = null, receiptOnly = false;
+    if (args.action === 'reconcile' || args.action === 'recover_registration') {
+      recovery = service.inspectRecovery(args.projectSlug, args.value, principal()); permission(args.action === 'recover_registration' ? 'rename' : recovery.action); args.value = recovery.operationId; revision = recovery.revision;
+    } else if (args.action === 'owner' && service.receiptPreview(hash(args), ctx.sourceKey, account && account.id || null)) {
+      receiptOnly = true;
+    } else if (args.action === 'register') {
+      if (!ctx.canUsePath(account && account.id, args.path)) throw new Error('Directory access is not permitted.');
+      revision = JSON.stringify(service.registration(args.path, account));
+      args.path = fs.realpathSync(args.path);
+    } else if (args.action !== 'create') {
+      if (ctx.getProjects().has(args.projectSlug)) { runtime = owned(args.projectSlug); revision = service.stamp(args.projectSlug); }
+      else if (args.action !== 'remove') throw new Error('Project is unavailable.');
+    } else revision = ctx.creationRevision();
+    if (targets.size >= 100) targets.delete(targets.keys().next().value);
+    var token = 'project-control:' + crypto.randomUUID();
+    targets.set(token, { receiptOnly: receiptOnly, recovery: recovery, creationPlan: args.action === 'create' ? service.creationPlan(args.name) : null, scope: ['remove', 'reconcile', 'recover_registration'].indexOf(args.action) >= 0 ? runtimeScope(args.projectSlug) : null, accountIdentity: JSON.stringify([account && account.id, account && account.linuxUser]), intent: args, revision: revision, runtime: runtime, created: Date.now() });
+    var current = runtime && service.inspect(args.projectSlug).project;
+    return { recovery: recovery ? { operationId: recovery.operationId, action: recovery.action, phase: recovery.phase, conflict: recovery.conflict, runtimeClosureConfirmed: recovery.runtimeClosureConfirmed } : undefined, receiptOnly: receiptOnly, current: current ? { title: current.title || args.projectSlug, ownerId: current.ownerId, visibility: current.visibility || 'public', allowedUsers: current.allowedUsers || [], sessionVisibilityDefault: current.sessionVisibilityDefault || 'private', envrc: args.action === 'environment' ? current.envrc || '' : undefined } : undefined,
+      targetToken: token, action: args.action, projectSlug: args.projectSlug, name: args.name, path: args.path || (args.action === 'create' ? service.creationPlan(args.name).path : undefined), expiresInSeconds: 300,
+      details: args.action === 'remove' ? 'Removes the Clay registration and stops its runtimes. Files and stored history remain on disk. Worktree runtimes are also stopped.' : args.action === 'environment' ? 'Only newly created agent processes receive this project environment. Active processes keep their current environment.' : 'The authenticated owner must review the exact change before it is saved.' };
+  }
+  function check(target) {
+    var args = target.intent, account = permission(args.action);
+    if (target.receiptOnly) throw new Error('This token only reads the existing exact transfer receipt. Reuse its original requestId.');
+    if (args.action === 'reconcile' || args.action === 'recover_registration') {
+      if (!sameScope(target.scope, runtimeScope(args.projectSlug))) throw new Error('Recovery runtime scope changed. Inspect again.');
+      permission(args.action === 'recover_registration' ? 'rename' : target.recovery.action);
+      if (service.inspectRecovery(args.projectSlug, args.value, principal()).revision !== target.revision) throw new Error('The recovery operation changed. Inspect again.');
+      if (Date.now() - target.created > 300000) throw new Error('Recovery inspection expired.');
+      return account;
+    }
+    if (args.action === 'remove' && !sameScope(target.scope, runtimeScope(args.projectSlug))) throw new Error('Project or worktree session revisions changed. Inspect removal again.');
+    if (JSON.stringify([account && account.id, account && account.linuxUser]) !== target.accountIdentity) throw new Error('The operating account identity changed.');
+    if (Date.now() - target.created > 300000) throw new Error('Project inspection expired.');
+    if (args.action === 'register') {
+      if (!ctx.canUsePath(account && account.id, args.path) || JSON.stringify(service.registration(args.path, account)) !== target.revision) throw new Error('Registration path or access changed.');
+    } else if (args.action === 'create') {
+      if (ctx.creationRevision(JSON.parse(target.revision).anchor) !== target.revision) throw new Error('Project creation destination or registry changed. Inspect again.');
+    } else if (!target.runtime || owned(args.projectSlug) !== target.runtime || service.stamp(args.projectSlug) !== target.revision) throw new Error('The exact project revision was deleted, replaced or changed. Inspect again.');
+    return account;
+  }
+  function correlation(target, requestId) {
+    var actor = principal();
+    return { sourceKey: ctx.sourceKey, action: target.intent.action, authorize: ctx.authorize, key: hash([actor.userId || actor.singleUserOwnerId, ctx.sourceKey, requestId]), fingerprint: hash(target.intent), ownerId: actor.userId || null };
+  }
+  async function run(target, args, receipt) {
+    check(target);
+    var intent = target.intent;
+    var labels = { recover_registration: 'Cancel this pending removal and restore the current registration after acknowledged runtime closure. Queued and scheduled execution stays paused until the owner explicitly sends a new message', reconcile: 'Reconcile the exact persisted lifecycle operation. Runtime closure must be acknowledged before removal completes. No stopped work is resumed', owner: 'Transfer this ordinary project to the selected account; session owners stay unchanged', create: 'Create a private project', register: 'Register an existing directory as a private project', rename: 'Rename this project', remove: 'Remove this project registration', visibility: 'Change project visibility', allowed_users: 'Replace project sharing grants', session_visibility: 'Change the default visibility for new sessions', environment: 'Replace this project environment' };
+    var heading = target.recovery && intent.action === 'reconcile' && target.recovery.action === 'remove' ? 'Finish removing this Clay registration after confirming runtime closure. Files and stored history stay on disk.' : intent.action === 'recover_registration' ? 'Cancel the pending removal and restore the current registration. Execution stays paused until the owner sends a new message.' : labels[intent.action];
+    var question = heading + '\nTarget: ' + (intent.projectSlug || intent.name || intent.path) + '\n';
+    if (target.recovery) question += 'Original change: ' + target.recovery.action + '. Runtime closure: ' + (target.recovery.runtimeClosureConfirmed ? 'confirmed' : 'must be confirmed by the service') + '.\n' + (target.recovery.registrationTitle ? 'Current project: ' + target.recovery.registrationTitle + '\n' : '') + (target.recovery.conflict ? 'The registration changed. Removal finalization cannot overwrite it; restoring retains the current registration with execution paused.\n' : 'The saved registration revision must still match exactly.\n');
+    if (target.creationPlan) question += 'Directory: ' + target.creationPlan.path + '\nRegistration: ' + target.creationPlan.slug + '\n';
+    if (intent.value !== undefined) question += 'Exact value:\n' + (Array.isArray(intent.value) ? intent.value.join(', ') : intent.value) + '\n';
+    if (intent.action === 'remove') question += 'Runtime count: ' + target.scope.length + '. Conversation count: ' + target.scope.reduce(function (sum, entry) { return sum + entry.sessions.length; }, 0) + '.\nProject files and stored history remain on disk. All project and worktree runtimes will be stopped.\n';
+    if (intent.action === 'environment') question += 'Applies to new agent processes only; active processes keep their environment.\n';
+    question += 'Why: ' + args.why;
+    if (question.length > 2000) throw new Error('The exact project review exceeds 2000 characters. Shorten the value or reason; no change was applied.');
+    var answer = await ctx.review(question, function () { check(target); });
+    if (answer.status !== 'submitted' || !answer.answers.control || answer.answers.control.length !== 1 || answer.answers.control[0] !== 'Apply exact change') return { status: 'cancelled', action: intent.action };
+    var account = check(target);
+    return service.execute(intent, account, receipt, function () { check(target); });
+  }
+  function act(args) {
+    principal();
+    if (!args || Object.keys(args).some(function (key) { return ['targetToken', 'requestId', 'why'].indexOf(key) < 0; }) || typeof args.requestId !== 'string' || !/^[\w-]{1,128}$/.test(args.requestId) || typeof args.why !== 'string' || !args.why.trim() || args.why.length > 1000) throw new Error('Use an inspected targetToken, requestId and why. Model confirmation cannot authorize project changes.');
+    var target = targets.get(args.targetToken); if (!target) throw new Error('Inspect this exact project intent first.');
+    permission(target.intent.action);
+    var receipt = correlation(target, args.requestId);
+    var saved = service.receipt(receipt.key, receipt.fingerprint, receipt.ownerId);
+    if (saved && ['completed', 'superseded'].indexOf(saved.status) >= 0) return saved;
+    if (target.intent.action !== 'reconcile' && target.intent.action !== 'recover_registration' && !target.receiptOnly && ctx.getProjects().has(target.intent.projectSlug)) owned(target.intent.projectSlug);
+    var old = requests.get(receipt.key);
+    if (old) { if (old.fingerprint !== receipt.fingerprint) throw new Error('requestId already names another project action.'); return old.promise; }
+    if (saved) return saved;
+    if (requests.size >= 100) throw new Error('Too many project control requests in this query.');
+    var promise = run(target, args, receipt).catch(function (error) { return Object.assign({ status: 'failed', error: error.message }, error.lifecycleResult || {}); });
+    requests.set(receipt.key, { fingerprint: receipt.fingerprint, promise: promise });
+    return promise;
+  }
+  return { inspectProject: inspect, actProject: act };
+}
+module.exports = { attachClayProjectLifecycle: attachClayProjectLifecycle, ACTIONS: ACTIONS };

package/lib/clay-project-record-input.js

@@ -0,0 +1,44 @@
+var z = require('zod');
+var text = z.string(), revision = z.number().int().positive();
+var issueFields = { title: text.optional(), summary: text.optional(), body: text.optional(), resolutionSummary: text.optional(), type: z.enum(['bug', 'feature', 'plan']).optional(), priority: z.enum(['normal', 'important', 'urgent']).optional(), status: z.enum(['open', 'in_progress', 'resolved', 'closed']).optional(), closeReason: z.enum(['declined', 'duplicate', 'non_code_decision']).optional() };
+var logFields = { title: text.optional(), summary: text.optional(), body: text.optional(), kind: text.optional(), priority: z.enum(['normal', 'important', 'urgent']).optional(), tags: text.optional() };
+var page = { limit: z.number().int().positive().max(200).optional(), cursor: text.optional() };
+var filters = Object.assign({}, page, { query: text.optional(), kind: text.optional(), priority: text.optional(), tag: text.optional(), contextMode: z.enum(['current', 'project', 'all']).optional() });
+var issueFilter = Object.assign({}, page, { query: text.optional(), status: z.enum(['open', 'in_progress', 'resolved', 'closed']).optional(), type: text.optional(), priority: text.optional() });
+var READS = {}, WRITES = {};
+function operation(area, action, method, fields, writes) {
+  (writes ? WRITES : READS)[area + ':' + action] = method;
+  return z.object(Object.assign({ area: z.literal(area), action: z.literal(action) }, fields)).strict();
+}
+var readSchema = z.union([
+  operation('issues', 'list', 'listIssues', issueFilter), operation('issues', 'search', 'searchIssues', issueFilter),
+  operation('issues', 'read', 'readIssue', { ref: text }), operation('issues', 'history', 'issueHistory', { ref: text }),
+  operation('issues', 'revision', 'readIssueRevision', { ref: text, revision: revision }), operation('issues', 'feedback', 'listIssueFeedback', page),
+  operation('logs', 'list', 'listLogs', filters), operation('logs', 'search', 'searchLogs', filters),
+  operation('logs', 'read', 'readLog', { ref: text }), operation('logs', 'history', 'logHistory', Object.assign({ ref: text }, page)),
+  operation('logs', 'revision', 'readLogRevision', { ref: text, revision: revision }), operation('logs', 'feedback', 'listLogFeedback', filters),
+]);
+var review = { ref: text, expectedRevision: revision, commentId: text, reviewAction: z.enum(['incorporate', 'clarify', 'decline']), response: text.optional() };
+var writeSchema = z.union([
+  operation('issues', 'create', 'createIssue', Object.assign({}, issueFields, { title: text, commitSha: text.optional() }), true),
+  operation('issues', 'update', 'updateIssue', Object.assign({}, issueFields, { ref: text, expectedRevision: revision, commitSha: text.optional() }), true),
+  operation('issues', 'review', 'reviewIssueComment', Object.assign({}, issueFields, review), true),
+  operation('issues', 'comment', 'commentIssue', { ref: text, expectedRevision: revision, body: text }, true),
+  operation('issues', 'delete', 'removeIssue', { ref: text, expectedRevision: revision }, true),
+  operation('logs', 'create', 'createLog', Object.assign({}, logFields, { title: text, kind: text, summary: text }), true),
+  operation('logs', 'update', 'updateLog', Object.assign({}, logFields, { ref: text, expectedRevision: revision }), true),
+  operation('logs', 'review', 'reviewLogComment', Object.assign({}, logFields, review), true),
+  operation('logs', 'comment', 'commentLog', { ref: text, expectedRevision: revision, body: text }, true),
+  operation('logs', 'revert', 'revertLog', { ref: text, expectedRevision: revision, revision: revision, reason: text }, true),
+  operation('logs', 'link', 'linkLog', { ref: text, expectedRevision: revision, links: text }, true),
+  operation('logs', 'delete', 'removeLog', { ref: text, expectedRevision: revision }, true),
+]);
+function parameters(op) {
+  var out = Object.assign({}, op); delete out.area; delete out.action;
+  if (op.area === 'logs') {
+    ['tags', 'links'].forEach(function (key) { if (out[key] !== undefined) { out[key] = JSON.parse(out[key]); if (!Array.isArray(out[key])) throw new Error(key + ' must encode a JSON array.'); } });
+  }
+  if (op.action === 'review') { out.action = out.reviewAction; delete out.reviewAction; }
+  return out;
+}
+module.exports = { readSchema: readSchema, writeSchema: writeSchema, READS: READS, WRITES: WRITES, parameters: parameters };

package/lib/clay-project-records.js

@@ -0,0 +1,83 @@
+var crypto = require('crypto');
+var authority = require('./canonical-clay-record-authority');
+var input = require('./clay-project-record-input');
+function fingerprint(value) { return crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+function text(value, max) { return typeof value === 'string' && value.trim() && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value); }
+function attachClayProjectRecords(ctx) {
+  var state = ctx.state;
+  // This closure is created only after the canonical source query authorizes.
+  // Every service call rechecks it, including after commit-verification awaits.
+  var token = authority.issue(function (slug) {
+    var live = ctx.resolve(slug);
+    return Object.assign({}, live, { actor: ctx.actor() });
+  });
+  function resolve(slug, area) {
+    var live = authority.resolve(token, slug), services = ctx.services();
+    var service = services && services[area];
+    var bound = service && service.bindCanonicalClay({ projectSlug: slug, authority: token });
+    if (!bound) throw new Error('Selected project record service is unavailable.');
+    return { project: live.project, status: live.status, bound: bound };
+  }
+  function parse(args, write) {
+    ctx.authorize();
+    if (!args || Object.keys(args).some(function (key) { return key !== 'projectSlug' && key !== 'operation'; }) || !text(args.projectSlug, 200)) throw new Error('Choose an exact ordinary project and typed record operation.');
+    return JSON.parse(JSON.stringify((write ? input.writeSchema : input.readSchema).parse(args.operation)));
+  }
+  function snapshot(live, op) {
+    return op.ref ? live.bound[op.area === 'issues' ? 'readIssue' : 'readLog']({ ref: op.ref }) : null;
+  }
+  function check(target, exact) {
+    var live = resolve(target.slug, target.op.area);
+    if (live.project !== target.project || fingerprint([live.status.path, live.status.projectKnowledgeId, live.status.changeSetId, live.status.parentSlug, live.status.branch, live.status.baseCommit, live.status.headCommit]) !== target.context) throw new Error('Selected project records context changed.');
+    if (exact) {
+      if (Date.now() - target.created > 300000) throw new Error('Record inspection expired.');
+      if (fingerprint(snapshot(live, target.op)) !== target.snapshot) throw new Error('Record or comment revision changed. Inspect and review again.');
+    }
+    return live;
+  }
+  async function read(args) {
+    var op = parse(args, false), live = resolve(args.projectSlug, op.area);
+    var result = await live.bound[input.READS[op.area + ':' + op.action]](input.parameters(op));
+    var after = resolve(args.projectSlug, op.area);
+    if (after.project !== live.project || fingerprint(after.status) !== fingerprint(live.status)) throw new Error('Selected project changed during read.');
+    return result;
+  }
+  function inspect(args) {
+    var op = parse(args, true), live = resolve(args.projectSlug, op.area), entry = snapshot(live, op);
+    if (entry && (op.area === 'issues' ? entry.revision : entry.revisions) !== op.expectedRevision) throw new Error('Record revision conflict.');
+    if (entry && entry.scheduledResult) throw new Error('Scheduled results are server-owned records.');
+    if (JSON.stringify(op).length > 1400) throw new Error('The exact record change must fit the existing owner review; use a smaller change.');
+    if (state.targets.size >= 100) state.targets.delete(state.targets.keys().next().value);
+    var id = 'records-control:' + crypto.randomUUID();
+    state.targets.set(id, { slug: args.projectSlug, op: op, project: live.project, context: fingerprint([live.status.path, live.status.projectKnowledgeId, live.status.changeSetId, live.status.parentSlug, live.status.branch, live.status.baseCommit, live.status.headCommit]), snapshot: fingerprint(entry), created: Date.now() });
+    return { targetToken: id, projectSlug: args.projectSlug, operation: op, expiresInSeconds: 300 };
+  }
+  function act(args) {
+    ctx.authorize();
+    if (!args || Object.keys(args).some(function (key) { return ['targetToken', 'requestId', 'why'].indexOf(key) < 0; }) || !text(args.targetToken, 100) || !text(args.requestId, 128) || !text(args.why, 300)) throw new Error('Use an exact record token, requestId and reason.');
+    args = Object.assign({}, args);
+    var target = state.targets.get(args.targetToken), key = fingerprint(args), previous = state.requests.get(args.requestId);
+    if (!target) throw new Error('Inspect the exact record change first.');
+    if (previous) { if (previous.key !== key) throw new Error('requestId already names another record change.'); return previous.promise.then(function (result) { check(target, false); return result; }); }
+    if (state.requests.size >= 100) throw new Error('Too many record requests in this query.');
+    var persisted = false;
+    var promise = Promise.resolve().then(async function () {
+      check(target, true);
+      var question = 'Apply this exact project record change:\n' + JSON.stringify(target.op) + '\nProject: ' + target.slug + '\nWhy: ' + args.why;
+      if (question.length > 2000) throw new Error('The exact change must fit the existing owner review.');
+      var response = await ctx.review(question, function () { check(target, true); });
+      if (response.status !== 'submitted' || !response.answers.control || response.answers.control.length !== 1 || response.answers.control[0] !== 'Apply exact change') return { status: 'cancelled', persisted: false };
+      var live = check(target, true);
+      persisted = 'unknown';
+      var result = await live.bound[input.WRITES[target.op.area + ':' + target.op.action]](input.parameters(target.op));
+      persisted = true; check(target, false);
+      if (target.op.area === 'issues' && live.project.notifyIssueUpdate) live.project.notifyIssueUpdate(result, target.op.action === 'delete' ? 'issue_deleted' : undefined);
+      if (target.op.area === 'logs' && live.project.notifyLogUpdate) live.project.notifyLogUpdate(result, target.op.action === 'review' ? target.op.reviewAction : target.op.action);
+      return { status: 'completed', persisted: true, result: result };
+    }).catch(function (error) { return { status: 'failed', persisted: persisted, retrySafe: false, error: error.message }; });
+    state.requests.set(args.requestId, { key: key, promise: promise });
+    return promise;
+  }
+  return { readProjectRecords: read, inspectProjectRecordChange: inspect, actProjectRecords: act };
+}
+module.exports = { attachClayProjectRecords: attachClayProjectRecords };

package/lib/clay-scheduling-input.js

@@ -0,0 +1,21 @@
+var z = require('zod');
+var str = z.string();
+var runtime = z.object({ vendor: str, model: str, effort: str.nullable().optional() }).strict();
+var rule = z.object({ version: z.literal(1), timezone: z.literal('server-local'), anchorDate: str, time: str,
+  recurrence: z.object({ every: z.number().int(), unit: z.enum(['day', 'week', 'month', 'year']), weekdays: z.array(z.number().int()).optional() }).strict().nullable().optional(),
+  recurrenceEnd: z.object({ type: z.enum(['until', 'after']), date: str.optional(), count: z.number().int().optional() }).strict().nullable().optional(),
+  interval: z.object({ every: z.number().int(), unit: z.enum(['minute', 'hour']), end: z.object({ type: z.enum(['until', 'after']), time: str.optional(), count: z.number().int().optional() }).strict().nullable().optional() }).strict().nullable().optional(),
+}).strict();
+var mateFields = { message: str.optional(), date: str.optional(), time: str.optional(), scheduleRule: rule.optional() };
+var taskFields = { name: str.optional(), instructions: str.optional(), date: str.optional(), time: str.optional(), cron: str.nullable().optional(), scheduleRule: rule.nullable().optional(), execution: z.object({ driver: runtime, worker: runtime }).strict().optional(), skipIfRunning: z.boolean().optional() };
+var target = z.union([z.object({ kind: z.literal('mate'), mateId: str, sessionRef: str }).strict(), z.object({ kind: z.literal('project'), projectSlug: str, sessionRef: str }).strict()]);
+var read = z.object({ target: target, operation: z.union([z.object({ action: z.literal('list') }).strict(), z.object({ action: z.literal('receipt'), requestId: str }).strict(), z.object({ action: z.literal('read'), id: str }).strict()]) }).strict();
+var operation = z.union([
+  z.object({ action: z.literal('create_mate'), data: z.object(Object.assign({}, mateFields, { message: str })).strict() }).strict(),
+  z.object({ action: z.literal('update_mate'), id: str, revision: str, data: z.object(mateFields).strict() }).strict(),
+  z.object({ action: z.literal('cancel_mate'), id: str, revision: str }).strict(),
+  z.object({ action: z.literal('propose'), data: z.object(Object.assign({}, taskFields, { name: str, instructions: str })).strict() }).strict(),
+  z.object({ action: z.literal('update'), id: str, revision: z.number().int().positive(), data: z.object(taskFields).strict() }).strict(),
+  z.object({ action: z.enum(['cancel', 'pause', 'resume', 'run']), id: str, revision: z.number().int().positive() }).strict(),
+]);
+module.exports = { readSchema: read, inspectSchema: z.object({ target: target, operation: operation }).strict(), targetSchema: target };

package/lib/clay-scheduling-receipts.js

@@ -0,0 +1,26 @@
+// Persist before execution; an interrupted application never retries blindly.
+function attachReceipts(ctx) {
+  function entries() { return ctx.session.claySchedulingReceipts || []; }
+  function save(entry) {
+    ctx.authorize();
+    var previous = ctx.session.claySchedulingReceipts;
+    var all = entries().filter(function (item) {
+      var stamp = /_(\d{13})_/.exec(item.id);
+      return item.id !== entry.id && (item.status === 'applying' || !stamp || Date.now() - Number(stamp[1]) <= 86400000);
+    });
+    if (all.length >= 100) throw new Error('Scheduling receipt capacity is full for this 24-hour window; inspect pending attempts and wait for completed receipts to expire.');
+    ctx.session.claySchedulingReceipts = all.concat([entry]);
+    if (ctx.save() !== true) { ctx.session.claySchedulingReceipts = previous; throw new Error('The scheduling retry receipt could not be saved.'); }
+    ctx.authorize();
+  }
+  function read(id, key) {
+    ctx.authorize();
+    var match = /^[A-Za-z][A-Za-z0-9-]*_(\d{13})_[A-Za-z0-9_-]{1,80}$/.exec(id || '');
+    if (!match || Math.abs(Date.now() - Number(match[1])) > 86400000) throw new Error('Scheduling requestId requires prefix_<13-digit creation time>_<unique suffix> within 24 hours.');
+    var entry = entries().find(function (item) { return item.id === id; });
+    if (entry && key !== undefined && entry.key !== key) throw new Error('requestId already names another scheduling intent.');
+    return entry;
+  }
+  return { read: read, save: save };
+}
+module.exports = { attachReceipts: attachReceipts };