clay-server 5.5.0-beta.2 → 5.5.0-beta.4

package/lib/clay-product-control-input.js

@@ -1,4 +1,4 @@
-var ACTIONS = ['rename', 'stop', 'model', 'effort', 'permission', 'delete', 'fork', 'rewind', 'vendor', 'vendor_new_session', 'runtime', 'queue_add', 'queue_edit', 'queue_cancel', 'queue_reorder'];
+var ACTIONS = ['rename', 'stop', 'force_stop', 'model', 'effort', 'permission', 'delete', 'fork', 'rewind', 'vendor', 'vendor_new_session', 'runtime', 'queue_add', 'queue_edit', 'queue_cancel', 'queue_reorder'];
 var KEYS = ['targetToken', 'action', 'value', 'why', 'requestId', 'text', 'messageId', 'ids'];
 function string(value, max) { return typeof value === 'string' && value.trim() && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value); }
 function messageId(value) { return typeof value === 'string' && /^pm_[1-9][0-9]{0,15}$/.test(value); }
@@ -23,7 +23,7 @@ function validate(args) {
 function description(args) {
   if (args.action === 'vendor_new_session') return 'Create a new private GUI session using provider ' + args.value + '. The original conversation and its provider thread remain unchanged. No history is migrated and no model execution is started.';
   if (args.action === 'runtime') return 'Return this legacy terminal session to GUI chat: ' + args.value + '. Wait for confirmed terminal shutdown, retain the same provider thread, and start no execution. New terminal presentation is unavailable.';
-  var labels = { rename: 'Rename this conversation to ', model: "Change this conversation's model to ", effort: 'Change reasoning effort to ', permission: 'Change the permission mode to ', delete: 'Permanently delete this Driver and its owned Worker history', fork: 'Fork this conversation at checkpoint ', rewind: 'Rewind conversation history to checkpoint ', vendor: 'Select the provider for this fresh GUI Driver: ' };
+  var labels = { force_stop: 'Force terminate this Driver and every owned Worker runtime only when all targets support it, and pause queued messages. Runtime exit must be confirmed; external commands and requests may still be running', rename: 'Rename this conversation to ', model: "Change this conversation's model to ", effort: 'Change reasoning effort to ', permission: 'Change the permission mode to ', delete: 'Permanently delete this Driver and its owned Worker history', fork: 'Fork this conversation at checkpoint ', rewind: 'Rewind conversation history to checkpoint ', vendor: 'Select the provider for this fresh GUI Driver: ' };
   if (args.action === 'queue_add') return 'Queue this exact message for the project Driver. It may run immediately when idle; it will not resume a stopped Driver.\nMessage:\n' + args.text;
   if (args.action === 'queue_edit') return 'Replace the text of queued message ' + args.messageId + '. Existing attachments are preserved.\nNew message:\n' + args.text;
   if (args.action === 'queue_cancel') return 'Cancel queued message ' + args.messageId + '. Already delivered work is not undone.';

package/lib/clay-product-control-tools.js

@@ -46,7 +46,7 @@ function getToolDefs(bound) {
     tool("inspect_project_control", "Inspect an exact ordinary-project lifecycle intent before review. Create/register are private. Remove unregisters and stops runtimes but preserves files/history. Existing project changes require ownership. Clay/Mates/worktrees and Server/User Settings are excluded. Environment values appear only in the owner review. Retry an identical intent with the same requestId after inspection; durable receipts prevent duplicate creation. Failed persisted operations expose operationId. Inspect reconcile to complete their exact saved change, or recover_registration to cancel a pending removal and restore access with execution paused. Both require a fresh owner review. Completed transfer retries return only the original bounded outcome to the same canonical source.", { action: z.enum(require("./clay-project-lifecycle").ACTIONS), projectSlug: z.string().optional(), name: z.string().optional(), path: z.string().optional(), value: z.union([z.string(), z.array(z.string())]).optional() }, "inspectProject"),
     tool("control_project_lifecycle", "Request the inspected project change and explain why. Only authenticated human approval of the exact revision authorizes the action. Reuse requestId for an identical retry; do not repeat an unknown or partial result with a new ID. Removal awaits runtime shutdown and retains files/history. OS filesystem sharing is unavailable. The exact combined value, target and reason must fit the existing 2000-character owner review.", { targetToken: z.string(), requestId: z.string(), why: z.string() }, "actProject"),
     tool("inspect_session_control", "Inspect an exact owned project Driver session before changing it. Returns a short-lived target revision token, model catalog and runtime state.", { projectSlug: z.string(), sessionRef: z.string() }, "inspect"),
-    tool("control_project_session", "Request an explicit change to an inspected project Driver. Explain what and why. Clay asks the authenticated owner to review the exact change; confirmed:true cannot authorize it. Reuse requestId only for an identical retry. Failed receipts may report an applied or unknown provider effect, or a fork retained in memory; inspect those effects before another action and never create another fork to retry a save. Queue actions inspect, persist and update the real Driver queue, never resume Stop, and do not directly execute Workers. Stop requests return queued until the runtime settles. Use reviewed project assignment/follow-up for task execution; never resume a stopped session.", { targetToken: z.string(), action: z.enum(input.ACTIONS), value: z.string().describe("Rename title, model, effort, permission mode, or exact checkpoint UUID for fork/chat rewind. Rewind restores conversation only; vendor selects an installed provider only on a fresh idle GUI Driver; vendor_new_session creates a blank private GUI session for an established conversation and retains the original without history migration or execution; runtime accepts gui to close a legacy Claude terminal after confirmed exit. New TUI presentation is unavailable.").optional(), why: z.string(), requestId: z.string(), text: z.string().max(1200).describe("Exact message text for queue_add or queue_edit. The full text is reviewed by the owner.").optional(), messageId: z.string().describe("Exact queued message ID from inspection, for edit or cancel.").optional(), ids: z.array(z.string()).max(100).describe("All owned pending message IDs in desired order for queue_reorder.").optional() }, "act"),
+    tool("control_project_session", "Request an explicit change to an inspected project Driver. Explain what and why. Clay asks the authenticated owner to review the exact change; confirmed:true cannot authorize it. Reuse requestId only for an identical retry. Failed receipts may report an applied or unknown provider effect, or a fork retained in memory; inspect those effects before another action and never create another fork to retry a save. Queue actions inspect, persist and update the real Driver queue, never resume Stop, and do not directly execute Workers. Stop requests return queued until the runtime settles. Reviewed force_stop requires explicit YOKE force termination support for the Driver and every owned Worker before any effect. It pauses queues and reports exact query runtime exit or unconfirmed termination; external commands and requests remain unconfirmed. Use reviewed project assignment/follow-up for task execution; never resume a stopped session.", { targetToken: z.string(), action: z.enum(input.ACTIONS), value: z.string().describe("Rename title, model, effort, permission mode, or exact checkpoint UUID for fork/chat rewind. Rewind restores conversation only; vendor selects an installed provider only on a fresh idle GUI Driver; vendor_new_session creates a blank private GUI session for an established conversation and retains the original without history migration or execution; runtime accepts gui to close a legacy Claude terminal after confirmed exit. New TUI presentation is unavailable.").optional(), why: z.string(), requestId: z.string(), text: z.string().max(1200).describe("Exact message text for queue_add or queue_edit. The full text is reviewed by the owner.").optional(), messageId: z.string().describe("Exact queued message ID from inspection, for edit or cancel.").optional(), ids: z.array(z.string()).max(100).describe("All owned pending message IDs in desired order for queue_reorder.").optional() }, "act"),
   ];
 }
 module.exports = { getToolDefs: getToolDefs };

package/lib/clay-product-control.js

@@ -83,7 +83,7 @@ function attachClayProductControl(ctx) {
       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 lists server-known connections. split_views reads saved configuration and challenges one selected live project window for visible/cached pane bindings, layout and focus. Typed reviewed split_view changes share human persistence and navigation paths. Owner notification read and reviewed exact dismissal use the existing queue. No arbitrary messages or Settings. Split view create/update/rename/separate/member transfer/folder/Favorite/open/focus are supported in the selected live project window; zero-to-eight session composition and bounded v1 workspace updates for existing tool instances share the human View service. File Follow/Pin/close, placement and layout are supported; new or rebound tool resources remain unavailable through this control. Saved descriptors and client observations are distinct. Account-wide workbench mode remains excluded.", 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.",
         vendorUsage: { tools: ["read_vendor_usage"], scope: "Read-only usage of the owner's own vendor accounts and sessions in one owned project, through the same service as the top bar; the owner's identity only, no refresh, credentials, URLs, commands or settings. Account figures keep each vendor's units; unreadable usage is reported with its reason." },
         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." },
+        unsupported: { personalProviders: "Personal AI provider installation discovery, reviewed supported installation, sign-in and audio transcription API keys are available only in authenticated human settings. No canonical credential, provider installation or sign-in operation is exposed.", worktrees: "Worktree icon edits, exclusion and disk deletion are available only through human product controls. Restoring exclusions and reconciling pending worktree removals have no in-app operation.", 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) {
@@ -96,7 +96,7 @@ function attachClayProductControl(ctx) {
       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 };
+        providerCapabilities: { forceTermination: require('./session-force-stop-support').describe(sm, target), 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;
@@ -105,12 +105,13 @@ function attachClayProductControl(ctx) {
       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 === "force_stop") question += "\nForce stop scope: this Driver and " + (target.scope.length - 1) + " owned Workers. Panes and conversation history remain. Every target must support YOKE force termination before any effect. Query runtime exit is reported separately from unconfirmed external commands or requests.";
         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 review(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 (!queueAction && live.session.taskStopRequested && args.action !== "stop" && args.action !== "force_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.");
       if (args.action === "stop" && display.current()) display.current().start("running");

package/lib/daemon-project-access.js

@@ -1,5 +1,6 @@
 // Persisted Clay-level access rules for parent projects and exact worktrees.
 // Filesystem and Git permissions are deliberately outside this module.
+var worktreePreferences = require("./worktree-preferences");
 
 function parentSlugFor(slug) {
   if (typeof slug !== "string") return null;
@@ -33,7 +34,7 @@ function pendingLifecycleOperation(config, project) {
   });
 }
 
-function getProjectAccess(config, slug, osUsers) {
+function getProjectAccess(config, slug, osUsers, worktreeIdentity) {
   var parentSlug = parentSlugFor(slug);
   var project = findProject(config, parentSlug || slug);
   if (!project) return { error: "Project not found" };
@@ -60,9 +61,16 @@ function getProjectAccess(config, slug, osUsers) {
 
   var grants = project.worktreeAllowedUsers && project.worktreeAllowedUsers[slug];
   var worktreeAllowedUsers = uniqueUsers(grants);
+  var preference = worktreePreferences.entry(config, parentSlug, slug);
+  var identityKnown = worktreeIdentity && worktreeIdentity.slug === slug &&
+    typeof worktreeIdentity.path === "string" && worktreeIdentity.path &&
+    typeof worktreeIdentity.changeSetId === "string" && worktreeIdentity.changeSetId;
+  var boundPreference = identityKnown
+    ? worktreePreferences.blocked(config, parentSlug, slug, worktreeIdentity.path, worktreeIdentity.changeSetId)
+    : preference && preference.lifecycleState;
   return {
     slug: slug,
-    lifecycleExecutionPaused: project.lifecycleExecutionPaused === true || !!pendingLifecycleOperation(config, project),
+    lifecycleExecutionPaused: project.lifecycleExecutionPaused === true || !!pendingLifecycleOperation(config, project) || !!boundPreference,
     ownershipRecovery: project.ownershipRecovery || null,
     visibility: visibility,
     allowedUsers: uniqueUsers(parentAllowedUsers.concat(worktreeAllowedUsers)),

package/lib/daemon-projects.js

@@ -9,6 +9,7 @@ var { scanWorktreesResult, isWorktree } = require("./worktree");
 var { daemonSync } = require("./daemon-sync");
 var logContext = require("./project-log-context");
 var daemonProjectAccess = require("./daemon-project-access");
+var worktreePreferences = require("./worktree-preferences");
 var saveConfig = require("./config").saveConfig;
 
 // --- Worktree tracking state ---
@@ -31,7 +32,9 @@ function isWorktreeSlug(slug) {
  * @param {string} parentIcon - icon of parent project
  * @param {string} parentOwnerId - owner user ID
  */
-function scanAndRegisterWorktrees(relay, parentPath, parentSlug, parentIcon, parentOwnerId, projectKnowledgeId, osUserInfo, config) {
+function scanAndRegisterWorktrees(relay, parentPath, parentSlug, parentIcon, parentOwnerId, projectKnowledgeId, osUserInfo, config, getConfig, getOsUserInfo) {
+  var savedParent = config && (config.projects || []).find(function (item) { return item.slug === parentSlug; });
+  if (savedParent && (savedParent.lifecycleState || worktreePreferences.pendingRemoval(config, parentSlug))) return;
   if (isWorktree(parentPath, osUserInfo)) return;
   var scan = scanWorktreesResult(parentPath, osUserInfo);
   if (!scan.ok) return;
@@ -50,12 +53,18 @@ function scanAndRegisterWorktrees(relay, parentPath, parentSlug, parentIcon, par
     if (alreadyRegistered) continue;
     var context = logContext.resolveWorktreeContext(wt.path, projectKnowledgeId, { branch: wt.branch || wt.dirName }, osUserInfo);
     var wtMeta = Object.assign({ parentSlug: parentSlug, external: wt.external, projectKnowledgeId: projectKnowledgeId }, context);
-    relay.addProject(wt.path, wtSlug, wt.branch || wt.dirName, parentIcon, parentOwnerId, wtMeta);
+    if (worktreePreferences.blocked(config || {}, parentSlug, wtSlug, wt.path, context.changeSetId)) continue;
+    relay.addProject(wt.path, wtSlug, wt.branch || wt.dirName, worktreePreferences.icon(config || {}, parentSlug, wtSlug, wt.path, context.changeSetId), parentOwnerId, wtMeta);
     worktreeRegistry[parentSlug].push(wtSlug);
     console.log("[daemon] Registered worktree:", wtSlug, "->", wt.path, wt.external ? "(external)" : "(inside project folder)");
   }
   daemonSync.register(getWorktreeSyncKey(parentSlug), function () {
-    rescanWorktrees(relay, parentPath, parentSlug, parentIcon, parentOwnerId, config, projectKnowledgeId, osUserInfo);
+    var currentConfig = getConfig ? getConfig() : config;
+    var current = currentConfig && (currentConfig.projects || []).find(function (item) { return item.slug === parentSlug; });
+    if (currentConfig && !current) return;
+    rescanWorktrees(relay, current ? current.path : parentPath, parentSlug, current ? current.icon : parentIcon,
+      current ? current.ownerId : parentOwnerId, currentConfig, current ? current.projectKnowledgeId : projectKnowledgeId,
+      current && getOsUserInfo ? getOsUserInfo(current) : osUserInfo);
   });
 }
 
@@ -69,6 +78,8 @@ function scanAndRegisterWorktrees(relay, parentPath, parentSlug, parentIcon, par
  * @param {object} [config] - daemon config (optional, for broadcasting project count)
  */
 function rescanWorktrees(relay, parentPath, parentSlug, parentIcon, parentOwnerId, config, projectKnowledgeId, osUserInfo) {
+  var liveParent = config && (config.projects || []).find(function (item) { return item.slug === parentSlug; });
+  if (liveParent && (liveParent.lifecycleState || worktreePreferences.pendingRemoval(config, parentSlug))) return;
   if (worktreeScanning[parentSlug]) return;
   worktreeScanning[parentSlug] = true;
   try {
@@ -96,7 +107,8 @@ function rescanWorktrees(relay, parentPath, parentSlug, parentIcon, parentOwnerI
       if (!found) {
         var context = logContext.resolveWorktreeContext(wt.path, projectKnowledgeId, { branch: wt.branch || wt.dirName }, osUserInfo);
         var wtMeta = Object.assign({ parentSlug: parentSlug, external: wt.external, projectKnowledgeId: projectKnowledgeId }, context);
-        relay.addProject(wt.path, wtSlug, wt.branch || wt.dirName, parentIcon, parentOwnerId, wtMeta);
+        if (worktreePreferences.blocked(config || {}, parentSlug, wtSlug, wt.path, context.changeSetId)) continue;
+        relay.addProject(wt.path, wtSlug, wt.branch || wt.dirName, worktreePreferences.icon(config || {}, parentSlug, wtSlug, wt.path, context.changeSetId), parentOwnerId, wtMeta);
         if (!worktreeRegistry[parentSlug]) worktreeRegistry[parentSlug] = [];
         worktreeRegistry[parentSlug].push(wtSlug);
         console.log("[daemon] Rescan: added worktree:", wtSlug);

package/lib/daemon-worktree-controls.js

@@ -0,0 +1,171 @@
+// Shared authoritative worktree display/removal service. Reviews expire after five minutes.
+var fs = require('fs');
+var path = require('path');
+var crypto = require('crypto');
+var access = require('./daemon-project-access');
+var prefs = require('./worktree-preferences');
+var identities = require('./worktree-identity');
+var branches = require('./worktree-branch');
+var operationsModule = require('./project-lifecycle-operations');
+function attachWorktreeControls(ctx) {
+  var locks = new Set(), reviews = new Map();
+  function config() { return ctx.getConfig(); }
+  function relay() { return ctx.getRelay(); }
+  function copy() { return JSON.parse(JSON.stringify(config())); }
+  function save(next) { ctx.saveConfig(next); ctx.setConfig(next); }
+  function parent(slug) { return (config().projects || []).find(function (item) { return item.slug === access.parentSlugFor(slug); }); }
+  function runtime(slug) { var found; relay().forEachProject(function (item, key) { if (key === slug) found = item; }); return found; }
+  function publish() { relay().broadcastAll({ type: 'projects_updated', projects: relay().getProjects(), projectCount: config().projects.length }); }
+  // Context-bound identities come from the server, including contexts retained during shutdown.
+  function getAccess(slug, runtimeIdentity) {
+    var live = runtimeIdentity ? null : runtime(slug);
+    return access.getProjectAccess(config(), slug, config().osUsers, runtimeIdentity || live && live.getStatus());
+  }
+  function authorize(slug, userId, removal) {
+    var project = parent(slug) || (config().projects || []).find(function (item) { return item.slug === slug; });
+    if (!project || project.lifecycleState || project.ownershipRecovery || project.lifecycleExecutionPaused || access.pendingLifecycleOperation(config(), project)) throw new Error('Project registration is unavailable or paused.');
+    var user = userId && ctx.findUser(userId);
+    if (ctx.users.isMultiUser()) {
+      if (!user || !ctx.users.getEffectivePermissions(user, config().osUsers)[removal ? 'deleteProject' : 'projectSettings']) throw new Error(access.parentSlugFor(slug) ? 'Only the project owner with the required permission may change this worktree.' : 'The required project permission is unavailable.');
+      if (access.parentSlugFor(slug)) {
+        if (user.id !== project.ownerId) throw new Error('Only the project owner with the required permission may change this worktree.');
+      } else if (!ctx.users.canAccessProject(user.id, getAccess(slug))) throw new Error('Project access is not permitted.');
+    } else if (access.parentSlugFor(slug) && project.ownerId && project.ownerId !== userId) throw new Error('Project owner does not match.');
+    return project;
+  }
+  function record(next, slug, status) {
+    var project = next.projects.find(function (item) { return item.slug === access.parentSlugFor(slug); });
+    if (!project.worktreePreferences) project.worktreePreferences = {};
+    var old = project.worktreePreferences[slug];
+    if (!prefs.matches(old, status.path, status.changeSetId)) old = {};
+    project.worktreePreferences[slug] = Object.assign({}, old, { slug: slug, path: status.path, changeSetId: status.changeSetId, projectKnowledgeId: status.projectKnowledgeId, ownerId: project.ownerId || null });
+    return project.worktreePreferences[slug];
+  }
+  function setIcon(slug, icon, userId) {
+    var persisted = false;
+    try {
+      var project = authorize(slug, userId, false);
+      if (locks.has(project.slug) || prefs.pendingRemoval(config(), project.slug)) throw new Error('Worktree removal is in progress.');
+      if (icon !== null && (typeof icon !== 'string' || icon.length > 64 || /[\u0000-\u001f\u007f]/.test(icon))) throw new Error('Invalid project icon.');
+      var live = runtime(slug); if (!live) throw new Error('Project runtime is unavailable.');
+      var next = copy();
+      if (access.parentSlugFor(slug)) {
+        var status = live.getStatus(), git = identities.inspect(project.path, status.path, ctx.osIdentity(project), false);
+        verifyMarker(git, status);
+        var old = prefs.entry(config(), project.slug, slug);
+        if (prefs.matches(old, status.path, status.changeSetId) && old.lifecycleState) throw new Error('Worktree removal is pending.');
+        record(next, slug, status).icon = icon;
+      }
+      else next.projects.find(function (item) { return item.slug === slug; }).icon = icon;
+      save(next); persisted = true;
+      if (!access.parentSlugFor(slug) && ctx.syncRecent) { try { ctx.syncRecent(next.projects); } catch (error) {} }
+      if (relay().setProjectIcon(slug, icon) !== true) throw new Error('The icon was saved, but runtime publication was not acknowledged.');
+      publish();
+      return { ok: true, persisted: true };
+    } catch (error) { return { ok: false, persisted: persisted, error: error.message }; }
+  }
+  function verifyMarker(git, status) {
+    var marker = JSON.parse(fs.readFileSync(path.join(git.git.path, 'clay-change-set.json'), 'utf8'));
+    if (marker.changeSetId !== status.changeSetId || marker.projectKnowledgeId !== status.projectKnowledgeId) throw new Error('The worktree change-set identity changed.');
+  }
+  function binding(slug, userId, action, status) {
+    var project = authorize(slug, userId, true), os = ctx.osIdentity(project);
+    if (!access.parentSlugFor(slug) || project.slug.indexOf('mate-') === 0) throw new Error('Choose an ordinary registered worktree.');
+    if (locks.has(project.slug)) throw new Error('Another worktree operation is in progress.');
+    if (!status || !status.isWorktree || status.slug !== slug || !status.changeSetId) throw new Error('Exact worktree registration is unavailable.');
+    var expected = project.slug + '--' + path.basename(status.path);
+    if (slug !== expected) throw new Error('Worktree registration does not match its directory.');
+    (config().projects || []).forEach(function (other) {
+      if (other.slug === project.slug) return;
+      var root; try { root = fs.realpathSync(other.path); } catch (error) { root = path.resolve(other.path); }
+      if (root === status.path || require('./worktree').isPathInside(status.path, root) || require('./worktree').isPathInside(root, status.path)) throw new Error('Worktree directory intersects another registered project.');
+    });
+    relay().forEachProject(function (other, otherSlug) {
+      if (otherSlug === slug || otherSlug === project.slug) return;
+      var root = other.getStatus().path;
+      if (root === status.path || require('./worktree').isPathInside(status.path, root)) throw new Error('Another registered runtime is inside this worktree.');
+    });
+    var git = identities.inspect(project.path, status.path, os, action === 'delete');
+    verifyMarker(git, status);
+    if (config().osUsers && (!os || git.parent.uid !== os.uid || git.target.uid !== os.uid)) throw new Error('Mapped OS ownership does not match the worktree.');
+    var base = Object.assign({}, project); delete base.worktreePreferences;
+    return { parent: base, status: { slug: slug, path: status.path, isWorktree: true, changeSetId: status.changeSetId, projectKnowledgeId: status.projectKnowledgeId }, os: os, git: git };
+  }
+  function preview(slug, action, userId, connection, deleteBranch) {
+    if (deleteBranch !== undefined && typeof deleteBranch !== 'boolean') throw new Error('Invalid local branch choice.');
+    if (deleteBranch && action !== 'delete') throw new Error('Exclude always keeps the local branch.');
+    if (action !== 'delete' && action !== 'exclude') throw new Error('Choose Exclude or Delete worktree.');
+    reviews.forEach(function (item, key) { if (item.expires < Date.now()) reviews.delete(key); });
+    if (reviews.size >= 128) throw new Error('Too many pending worktree reviews.');
+    var live = runtime(slug), status = live && live.getStatus();
+    var bound = binding(slug, userId, action, status);
+    var existing = prefs.entry(config(), bound.parent.slug, slug);
+    if (prefs.matches(existing, status.path, status.changeSetId) && existing.lifecycleState) throw new Error('Worktree removal is pending. Inspect operation ' + existing.lifecycleOperationId + ' before recovery.');
+    var branch = deleteBranch ? branches.inspect(bound.git, bound.os, false) : null;
+    var token = crypto.randomUUID();
+    reviews.set(token, { slug: slug, action: action, userId: userId, connection: connection, bound: bound, branch: branch, deleteBranch: deleteBranch === true, live: live, expires: Date.now() + 300000 });
+    return { ok: true, token: token, slug: slug, action: action, path: bound.git.target.path, branch: bound.git.branch, deleteBranch: deleteBranch === true, localBranch: /^refs\/heads\//.test(bound.git.branch), expiresInSeconds: 300 };
+  }
+  function find(slug) { var project = parent(slug); return project && prefs.entry(config(), project.slug, slug); }
+  var operations = operationsModule.attachLifecycleOperations({ config: config, find: find, directory: function (value) { return identities.identity(value, true); }, storageDir: ctx.storageDir,
+    record: function () {}, snapshot: copy, save: save, relay: relay, publish: publish });
+  async function execute(token, userId, connection, validate, deleteBranch) {
+    if (validate) validate();
+    var review = reviews.get(token); reviews.delete(token);
+    if (!review || review.expires < Date.now() || review.userId !== userId || review.connection !== connection) throw new Error('Worktree confirmation expired or belongs to another connection. Review again.');
+    if (deleteBranch !== undefined && deleteBranch !== review.deleteBranch) throw new Error('The local branch choice does not match the reviewed confirmation.');
+    var slug = review.slug, bound = binding(slug, userId, review.action, review.bound.status);
+    if (JSON.stringify(bound) !== JSON.stringify(review.bound) || runtime(slug) !== review.live) throw new Error('The reviewed worktree changed. Review it again.');
+    if (review.branch) branches.exact(bound.git, review.branch, bound.os, false);
+    var parentSlug = bound.parent.slug, op, reserved = false, diskRemoved = false, branchRemoved = false;
+    var contextState = require('./project-log-context').isMerged(bound.parent.path, bound.status.path, bound.os) ? 'merged' : 'archived';
+    var archive = relay().captureWorktreeLogContext ? relay().captureWorktreeLogContext(slug) : null;
+    locks.add(parentSlug);
+    try {
+      var next = copy(), registration = record(next, slug, review.bound.status);
+      var targets = relay().getProjectLifecycleTargets(slug);
+      if (targets.length !== 1 || targets[0].slug !== slug || targets[0].path !== bound.status.path) throw new Error('Exact runtime closure scope is unavailable.');
+      var result = { ok: true, status: 'completed', slug: slug, action: review.action, filesDeleted: review.action === 'delete', branchDeleted: false, deleteBranch: review.deleteBranch, branch: bound.git.branch };
+      op = operations.begin(next, registration, 'remove', result, null, targets);
+      op.worktreeReview = { git: bound.git, branch: review.branch, deleteBranch: review.deleteBranch };
+      save(next); reserved = true;
+      await relay().closeProjectLifecycle(targets, false);
+      if (relay().getProjectLifecycleTargets(slug).length) throw new Error('A runtime appeared during worktree shutdown.');
+      operations.confirmClosed(op); operations.exact(op);
+      if (validate) validate();
+      locks.delete(parentSlug);
+      var current = binding(slug, userId, review.action, bound.status);
+      locks.add(parentSlug);
+      if (JSON.stringify(current) !== JSON.stringify(bound)) throw new Error('Worktree identity or authorization changed during shutdown.');
+      if (review.branch) branches.exact(bound.git, review.branch, bound.os, false);
+      if (review.action === 'delete') { identities.remove(bound.git, bound.os); diskRemoved = true; }
+      if (review.branch) { await branches.remove(bound.git, review.branch, bound.os, function () {
+        if (validate) validate();
+        if (relay().getProjectLifecycleTargets(slug).length) throw new Error('A runtime appeared during local branch deletion.');
+        var project = authorize(slug, userId, true), base = Object.assign({}, project); delete base.worktreePreferences;
+        if (JSON.stringify(base) !== JSON.stringify(bound.parent) || JSON.stringify(ctx.osIdentity(project)) !== JSON.stringify(bound.os)) throw new Error('Worktree authorization or mapped OS identity changed during branch deletion.');
+        if (JSON.stringify(find(slug)) !== op.expected) throw new Error('The exact saved worktree registration changed.');
+      }); branchRemoved = true; result.branchDeleted = true; }
+      if (archive) archive(contextState);
+      // Record the observed disk effect even if subsequent persistence/publication fails.
+      next = copy(); var saved = next.projects.find(function (item) { return item.slug === parentSlug; }).worktreePreferences[slug];
+      delete saved.lifecycleState; delete saved.lifecycleOperationId; saved.excluded = true;
+      access.clearWorktreeGrant(next, slug);
+      operations.complete(next, op, saved); save(next);
+      ctx.unregister(parentSlug, slug);
+      publish();
+      return Object.assign(result, { operationId: op.id, runtimeClosed: true });
+    } catch (error) {
+      if (reserved) error.lifecycleResult = Object.assign(operations.partial(op, error.message), { filesDeleted: diskRemoved, branchDeleted: branchRemoved, deleteBranch: review.deleteBranch, branch: bound.git.branch, recoveryAction: 'inspect_worktree_removal', directoryAbsent: !fs.existsSync(bound.git.target.path), runtimeClosureConfirmed: operations.closed(op) });
+      if (reserved) {
+        try { var partialConfig = copy(); partialConfig.projectLifecycleOperations[op.id].observed = error.lifecycleResult; save(partialConfig); } catch (saveError) {}
+      }
+      throw error;
+    } finally { locks.delete(parentSlug); }
+  }
+  function busy(parentSlug) {
+    return locks.has(parentSlug) || prefs.pendingRemoval(config(), parentSlug);
+  }
+  return { getAccess: getAccess, setIcon: setIcon, preview: preview, execute: execute, busy: busy };
+}
+module.exports = { attachWorktreeControls: attachWorktreeControls };

package/lib/daemon.js

@@ -32,7 +32,7 @@ var osUsersMod = require("./os-users");
 var { scheduleOsUserDiagnosticsAsync } = require("./os-user-diagnostics");
 var { checkAclSupport, grantProjectAccess, revokeProjectAccess, provisionAllUsers, provisionLinuxUser, grantAllUsersAccess, deactivateLinuxUser, ensureProjectsDir } = osUsersMod;
 var usersModule = require("./users");
-var { createWorktree, removeWorktree, isWorktree } = require("./worktree");
+var { createWorktree, isWorktree } = require("./worktree");
 var mates = require("./mates");
 var mateKnowledgeMigration = require("./mate-knowledge-migration");
 var { isWorktreeSlug, scanAndRegisterWorktrees, rescanWorktrees, cleanupWorktreesForParent, getFilteredRemovedProjects, registerWorktreeSlug, unregisterWorktreeSlug } = require("./daemon-projects");
@@ -183,7 +183,7 @@ function worktreeOsUserInfo(project, requestUser) {
 function registerProjectWorktrees(project, requestUser) {
   try {
     var osUserInfo = worktreeOsUserInfo(project, requestUser);
-    scanAndRegisterWorktrees(relay, project.path, project.slug, project.icon, project.ownerId, project.projectKnowledgeId, osUserInfo, config);
+    scanAndRegisterWorktrees(relay, project.path, project.slug, project.icon, project.ownerId, project.projectKnowledgeId, osUserInfo, config, function () { return config; }, worktreeOsUserInfo);
   } catch (e) {
     console.error("[daemon] Failed to scan worktrees for " + project.slug + ": " + e.message);
   }
@@ -195,7 +195,13 @@ var projectLifecycle = require("./daemon-project-lifecycle").attachProjectLifecy
   findUser: usersModule.findUserById, registerWorktrees: registerProjectWorktrees,
 });
 var lifecycleCallbacks = require("./daemon-project-lifecycle-callbacks").attachLifecycleCallbacks({ service: projectLifecycle });
+var worktreeControls = require("./daemon-worktree-controls").attachWorktreeControls({
+  getConfig: function () { return config; }, setConfig: function (next) { config = next; }, saveConfig: saveConfig,
+  getRelay: function () { return relay; }, findUser: usersModule.findUserById, users: usersModule,
+  osIdentity: worktreeOsUserInfo, syncRecent: syncClayrc, storageDir: require("./config").CONFIG_DIR, unregister: unregisterWorktreeSlug,
+});
 var relay = createServer({
+  worktreeControls: worktreeControls,
   projectLifecycle: projectLifecycle,
   tlsOptions: tlsOptions,
   caPath: caRoot,
@@ -316,43 +322,7 @@ var relay = createServer({
     });
   },
   onRemoveProject: function (slug, userId) {
-    // Check if this is a worktree project (ephemeral)
-    if (isWorktreeSlug(slug)) {
-      var wtParent = slug.split("--")[0];
-      var wtDirName = slug.split("--").slice(1).join("--");
-      // Find parent project path
-      var parentProject = null;
-      for (var pi = 0; pi < config.projects.length; pi++) {
-        if (config.projects[pi].slug === wtParent) { parentProject = config.projects[pi]; break; }
-      }
-      if (parentProject) {
-        var wtPath = path.join(parentProject.path, wtDirName);
-        var removeUser = userId ? usersModule.findUserById(userId) : null;
-        var removeOsUserInfo;
-        try {
-          removeOsUserInfo = worktreeOsUserInfo(parentProject, removeUser);
-        } catch (e) {
-          return { ok: false, error: e.message };
-        }
-        var contextStatus = projectLogContext.isMerged(parentProject.path, wtPath, removeOsUserInfo) ? "merged" : "archived";
-        var rmResult = removeWorktree(parentProject.path, wtDirName, removeOsUserInfo);
-        if (!rmResult.ok) {
-          console.log("[daemon] Failed to remove worktree:", slug, rmResult.error);
-          return { ok: false, error: rmResult.error };
-        }
-        relay.setProjectLogContextState(slug, contextStatus);
-      }
-      relay.removeProject(slug);
-      unregisterWorktreeSlug(wtParent, slug);
-      if (daemonProjectAccess.clearWorktreeGrant(config, slug)) saveConfig(config);
-      console.log("[daemon] Removed worktree (web):", slug);
-      relay.broadcastAll({
-        type: "projects_updated",
-        projects: relay.getProjects(),
-        projectCount: config.projects.length,
-      });
-      return { ok: true };
-    }
+    if (isWorktreeSlug(slug)) return { ok: false, error: "Use the reviewed Exclude or Delete worktree control." };
     return lifecycleCallbacks.onRemoveProject(slug, userId);
   },
   onReorderProjects: function (slugs) {
@@ -390,26 +360,8 @@ var relay = createServer({
     if (isWorktreeSlug(slug)) { relay.setProjectTitle(slug, newTitle); return { ok: true }; }
     return lifecycleCallbacks.onSetProjectTitle(slug, newTitle);
   },
-  onSetProjectIcon: function (slug, newIcon) {
-    relay.setProjectIcon(slug, newIcon);
-    for (var ii = 0; ii < config.projects.length; ii++) {
-      if (config.projects[ii].slug === slug) {
-        if (newIcon) {
-          config.projects[ii].icon = newIcon;
-        } else {
-          delete config.projects[ii].icon;
-        }
-        break;
-      }
-    }
-    saveConfig(config);
-    try { syncClayrc(config.projects); } catch (e) {}
-    relay.broadcastAll({
-      type: "projects_updated",
-      projects: relay.getProjects(),
-      projectCount: config.projects.length,
-    });
-    return { ok: true };
+  onSetProjectIcon: function (slug, newIcon, userId) {
+    return worktreeControls.setIcon(slug, newIcon, userId);
   },
   onSetProjectSessionVisibilityDefault: function (slug, visibility) {
     return projectLifecycle.update(slug, "session_visibility", visibility);
@@ -865,9 +817,7 @@ var relay = createServer({
     }
     return { error: "Project not found" };
   },
-  onGetProjectAccess: function (slug) {
-    return daemonProjectAccess.getProjectAccess(config, slug, config.osUsers);
-  },
+  onGetProjectAccess: worktreeControls.getAccess,
   onUserProvisioned: function (userId, linuxUser) {
     // Grant ACL on all public projects to the newly provisioned user
     if (!config.osUsers || !linuxUser) return;
@@ -891,6 +841,7 @@ var relay = createServer({
       if (config.projects[j].slug === parentSlug) { parent = config.projects[j]; break; }
     }
     if (!parent) return { ok: false, error: "Parent project not found" };
+    if (worktreeControls.busy(parentSlug) || parent.lifecycleState) return { ok: false, error: "Worktree lifecycle operation is pending." };
     var osUserInfo;
     try {
       osUserInfo = worktreeOsUserInfo(parent, requestUser);
@@ -909,7 +860,7 @@ var relay = createServer({
       baseCommit: baseCommit,
     }, osUserInfo);
     var wtMeta = Object.assign({ parentSlug: parentSlug, external: false, projectKnowledgeId: parent.projectKnowledgeId }, context);
-    relay.addProject(result.path, wtSlug, branchName, parent.icon, parent.ownerId, wtMeta);
+    relay.addProject(result.path, wtSlug, branchName, null, parent.ownerId, wtMeta);
     registerWorktreeSlug(parentSlug, wtSlug);
     console.log("[daemon] Created worktree:", wtSlug, "->", result.path);
     relay.broadcastAll({

package/lib/personal-provider-install.js

@@ -0,0 +1,85 @@
+// Exact human-settings review, one-use receipts, and scoped installer lifecycle.
+var crypto = require('crypto');
+var locks = new Map();
+function attach(ctx, personal) {
+  var pending = new WeakMap(), running = new Map();
+  function emit(ws, request, state, extra) {
+    if (ws.readyState === 1) ctx.sendTo(ws, Object.assign({type:'personal_provider_install',vendor:request.vendor,personalRequestId:request.personalRequestId,state:state,requestId:request.requestId},extra || {}));
+  }
+  function valid(item) { return item.authority.validate() && Date.now() < item.expires; }
+  function release(ws) {
+    pending.delete(ws);
+    var item = running.get(ws); if (item) stop(ws,item);
+  }
+  async function stop(ws,item) {
+    if (item.stopping) return;
+    item.stopping = true; clearInterval(item.timer);
+    emit(ws,item.request,'stopping',{message:'Stopping the installation terminal…'});
+    try {
+      await ctx.tm.closeAndWait(item.terminal.id,{identity:item.terminal.identity,revalidate:function () { if (running.get(ws) !== item) throw new Error('Installation terminal changed.'); }});
+      emit(ws,item.request,'stopped',{message:'Installation terminal exited. Partial files may remain. Refresh status before explicitly reviewing another attempt.'});
+      locks.delete(item.key); running.delete(ws);
+    } catch(error) {
+      // Keep the lock: an uncertain effect must never be replayed automatically.
+      emit(ws,item.request,'unknown',{message:'Terminal shutdown could not be confirmed. Ask the server operator to inspect it before trying again.'});
+    }
+  }
+  function handle(ws,msg) {
+    if (typeof msg.type !== 'string' || msg.type.indexOf('personal_provider_install_') !== 0) return false;
+    try {
+      if (msg.type === 'personal_provider_install_stop') {
+        var active = running.get(ws);
+        if (active && active.request.personalRequestId === msg.personalRequestId && active.request.vendor === msg.vendor) stop(ws,active);
+        return true;
+      }
+      if (msg.type === 'personal_provider_install_cancel') {
+        var review = pending.get(ws);
+        if (review && review.token === msg.reviewId && review.request.personalRequestId === msg.personalRequestId && review.request.vendor === msg.vendor) pending.delete(ws);
+        return true;
+      }
+      if (msg.type === 'personal_provider_install_review') {
+        if (running.has(ws)) throw new Error('An installation is already running or its result is uncertain.');
+        var authority = personal.resolveInstall(ws,msg);
+        var key = JSON.stringify([authority.runtime.uid,authority.runtime.home,msg.vendor]);
+        if (locks.has(key)) throw new Error('An installation for this runtime account is already running or needs inspection.');
+        var item = {authority:authority,key:key,request:{vendor:msg.vendor,personalRequestId:msg.personalRequestId,requestId:msg.requestId},token:crypto.randomUUID(),expires:Date.now()+120000};
+        pending.set(ws,item);
+        emit(ws,msg,'review',{reviewId:item.token,command:authority.recipe.command,source:authority.recipe.source,effects:authority.recipe.effects,runtime:authority.runtime,message:'Review this exact installation. Review expires in two minutes; leaving settings cancels it.'});
+        return true;
+      }
+      if (msg.type === 'personal_provider_install_start') {
+        var item = pending.get(ws); pending.delete(ws);
+        if (!item || item.token !== msg.reviewId || item.request.vendor !== msg.vendor || item.request.personalRequestId !== msg.personalRequestId || !valid(item) || locks.has(item.key)) throw new Error('Installation review expired, changed or was already used. Refresh status and review again.');
+        var fresh = personal.resolveInstall(ws,msg);
+        if (fresh.recipe !== item.authority.recipe || JSON.stringify(fresh.runtime) !== JSON.stringify(item.authority.runtime)) throw new Error('Installation target changed.');
+        item.request.requestId = msg.requestId;
+        locks.set(item.key,item); running.set(ws,item);
+        var terminal;
+        try {
+          terminal = ctx.tm.create(100,24,item.authority.runtime,ws,{kind:'provider-install',title:'Install '+msg.vendor,providerInstall:msg.vendor,
+            revalidateInstall:function () { if (!valid(item) || running.get(ws) !== item || locks.get(item.key) !== item) throw new Error('Installation permission or identity changed.'); },
+            onExit:function (session) {
+              if (item.stopping || running.get(ws) !== item) return;
+              clearInterval(item.timer); running.delete(ws); locks.delete(item.key);
+              if (!valid(item)) { emit(ws,item.request,'unknown',{message:'Installation terminal exited after account context changed. Refresh status; no task was replayed.'}); return; }
+              var installed = null;
+              try { installed = !!require('./yoke/vendor-registry').getVendorInfo(msg.vendor).resolveExecutable({user:item.authority.identity.linuxUser}); } catch(error) {}
+              if (!valid(item)) { emit(ws,item.request,'unknown',{message:'Installation discovery ended after account context changed. Refresh status before continuing.'}); return; }
+              emit(ws,item.request,session.exitCode === 0 ? 'completed' : 'failed',{installed:installed,exitCode:session.exitCode,message:session.exitCode === 0 ? (installed === null ? 'Installer exited successfully, but runtime discovery is unavailable. Refresh status to check the installation.' : installed ? 'Installer exited successfully; runtime discovery now finds this provider. Authentication remains unknown.' : 'Installer exited successfully, but runtime discovery has not found the provider. Check ~/.local/bin on the runtime PATH and refresh status.') : 'Installer did not report success. Refresh status and inspect the runtime setup before explicitly reviewing another attempt.'});
+            }});
+          if (!terminal) throw new Error('The installation terminal could not be created.');
+          item.terminal = terminal;
+          // Review expiry bounds launch, not a running install. Authority stays live.
+          item.expires = Infinity;
+          item.timer = setInterval(function () { if (!valid(item)) stop(ws,item); },250);
+          item.timer.unref();
+          emit(ws,msg,'started',{message:'Installation started in the reviewed runtime account. Waiting for terminal exit; downloads may be quiet.'});
+        } catch(error) { emit(ws,item.request,'unknown',{message:'Installation launch could not be confirmed. Ask the server operator to inspect the runtime before retrying.'}); }
+        return true;
+      }
+      throw new Error('Unsupported installation operation.');
+    } catch(error) { emit(ws,msg,'refused',{message:error.message}); return true; }
+  }
+  return {handle:handle,release:release,destroy:function () { pending = new WeakMap(); running.forEach(function(item,ws){stop(ws,item);}); }};
+}
+module.exports = {attach:attach};