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

package/lib/yoke/adapters/claude.js

@@ -4,6 +4,7 @@
 // This is the ONLY file (besides claude-worker.js) that imports the SDK.
 // Also manages worker processes for OS-level user isolation.
 
+var attachWorkerStartup = require("../claude-worker-startup").attachWorkerStartup;
 var bindQueryAbort = require("../query-abort").bindAbort;
 var path = require("path");
 var fs = require("fs");
@@ -600,6 +601,8 @@ function createQueryHandle(rawQuery, messageQueue, abortController) {
   var correlation = claudeCorrelation.createCorrelation();
   var closed = false;
   var removeAbort = function () {};
+  var resolveStopped;
+  var stopped = new Promise(function(resolve) { resolveStopped = resolve; });
   var handle = {
     // Opaque adapter state (null for in-process queries)
     _adapterState: null,
@@ -610,12 +613,13 @@ function createQueryHandle(rawQuery, messageQueue, abortController) {
       return {
         next: function() {
           return rawIter.next().then(function(result) {
-            if (result.done) { closed = true; removeAbort(); }
+            if (result.done) { closed = true; removeAbort(); resolveStopped(); }
             if (result.done) return result;
             return { value: correlation.result(result.value, flattenEvent(result.value)), done: false };
           }, function(err) {
             closed = true;
             removeAbort();
+            resolveStopped();
             throw err;
           });
         },
@@ -715,6 +719,11 @@ function createQueryHandle(rawQuery, messageQueue, abortController) {
       }
     },
 
+    stopAndWait: function() {
+      handle.abort();
+      return stopped;
+    },
+
     close: function() {
       closed = true;
       removeAbort();
@@ -818,9 +827,7 @@ function spawnWorker(linuxUser, workerScriptPath, cwd) {
     buffer: "",
   };
 
-  worker.readyPromise = new Promise(function(resolve) {
-    worker._readyResolve = resolve;
-  });
+  attachWorkerStartup(worker);
 
   // Resolves when the worker process actually exits.
   // Used to prevent spawning a new worker before the old one finishes
@@ -860,7 +867,15 @@ function spawnWorker(linuxUser, workerScriptPath, cwd) {
     });
     connection.on("error", function(err) {
       console.error("[yoke/claude] Worker connection error:", err.message);
+      if (worker._readyReject) worker._readyReject(err);
     });
+    connection.on("close", function() {
+      if (worker._readyReject) worker._readyReject(new Error("Claude worker connection closed before ready."));
+    });
+  });
+  worker.server.on("error", function(error) {
+    if (worker._readyReject) worker._readyReject(error);
+    cleanupWorker(worker);
   });
 
   worker.server.listen(socketPath, function() {
@@ -892,6 +907,14 @@ function spawnWorker(linuxUser, workerScriptPath, cwd) {
     });
     worker.process = spawn(workerSpawn.command, workerSpawn.args, workerSpawn.options);
 
+    worker.process.on("error", function(error) {
+      if (worker._readyReject) worker._readyReject(error);
+      worker.messageHandlers.forEach(function(handler) { handler({ type: "query_error", error: error.message, _fallback: true }); });
+      cleanupWorker(worker);
+      // Only a spawn failure proves that no child execution exists. Other
+      // ChildProcess errors (for example a failed signal) are not exit evidence.
+      if (!worker.process.pid && worker._exitResolve) { worker._exitResolve(); worker._exitResolve = null; }
+    });
     worker.process.stdout.on("data", function(data) {
       console.log("[sdk-worker:" + linuxUser + "] " + data.toString().trim());
     });
@@ -905,9 +928,8 @@ function spawnWorker(linuxUser, workerScriptPath, cwd) {
     worker.process.on("exit", function(code, signal) {
       console.log("[yoke/claude] Worker for " + linuxUser + " exited (code=" + code + ", signal=" + signal + ")" + (worker._stderrBuf ? " stderr: " + worker._stderrBuf.trim() : ""));
       // Reject readyPromise if worker dies before becoming ready
-      if (!worker.ready && worker._readyResolve) {
-        worker._readyResolve = null;
-        // Let the readyPromise hang; the query_error handler will clean up
+      if (!worker.ready && worker._readyReject) {
+        worker._readyReject(new Error("Claude worker exited before ready (code=" + code + ")."));
       }
       // Notify message handlers about unexpected exit so sessions don't hang.
       // Always dispatch a fallback query_error. The handler is idempotent:
@@ -1082,6 +1104,9 @@ function createWorkerQueryHandle(worker, canUseTool, onElicitation, callMcpTool,
   var iterWaiting = null;
   var iterEnded = false;
   var iterError = null;
+  var resolveStopped;
+  var stopped = new Promise(function(resolve) { resolveStopped = resolve; });
+  if (worker.exitPromise) worker.exitPromise.then(resolveStopped);
 
   // Pending request/response correlation for handle methods that need a
   // result from the worker (e.g. rewindFiles). Each entry is keyed by a
@@ -1299,6 +1324,8 @@ function createWorkerQueryHandle(worker, canUseTool, onElicitation, callMcpTool,
       }
 
       case "query_done":
+        if (worker._abortTimeout) { clearTimeout(worker._abortTimeout); worker._abortTimeout = null; }
+        resolveStopped();
         rejectPendingPermissionModes(new Error("Worker query ended while changing permission mode"));
         console.log("[yoke/claude] IPC query_done received, pid=" + (worker.process ? worker.process.pid : "?"));
         worker._queryEnded = true;
@@ -1306,6 +1333,10 @@ function createWorkerQueryHandle(worker, canUseTool, onElicitation, callMcpTool,
         break;
 
       case "query_error": {
+        if (!msg._fallback) {
+          if (worker._abortTimeout) { clearTimeout(worker._abortTimeout); worker._abortTimeout = null; }
+          resolveStopped();
+        }
         rejectPendingPermissionModes(new Error(msg.error || "Worker exited while changing permission mode"));
         console.log("[yoke/claude] IPC query_error received, pid=" + (worker.process ? worker.process.pid : "?") + " _fallback=" + !!msg._fallback + " _queryEnded=" + worker._queryEnded + " error=" + (msg.error || "").substring(0, 100));
         // Skip fallback errors from exit handler if we already handled the real one
@@ -1472,6 +1503,11 @@ function createWorkerQueryHandle(worker, canUseTool, onElicitation, callMcpTool,
       }, 5000);
     },
 
+    stopAndWait: function() {
+      handle.abort();
+      return stopped;
+    },
+
     close: function() {
       rejectPendingPermissionModes(new Error("Worker query closed while changing permission mode"));
       // End the iterator
@@ -1909,7 +1945,10 @@ function createClaudeAdapter(opts) {
 
     // Wait for worker to be ready before sending query_start
     if (!reusingWorker) {
-      await worker.readyPromise;
+      try { await worker.readyPromise; } catch (error) {
+        worker.kill();
+        throw error;
+      }
     }
 
     // Build serializable query options (no callbacks, no AbortController).

package/lib/yoke/adapters/codex.js

@@ -1343,6 +1343,8 @@ function createCodexQueryHandle(appServer, queryOpts) {
       return { threadId: state.threadId, revision: inputRevision };
     },
 
+    getRecoveryThreadId: function() { return state.threadId || queryOpts.resumeSessionId || null; },
+
     retireIdleForRecovery: function() {
       handle.endInput();
       return loopFinished;
@@ -1461,11 +1463,23 @@ function createCodexAdapter(opts) {
   var _refCount = 0;
   var _lastActiveAt = Date.now();
   var _shuttingDown = false;
+  var _recoveryIdleShutdown = null;
   var _activeQueries = [];
-  var _recoveryHandoff = null;
-  var _recoveryRuntimes = [];
-  var _recoveryCleanup = Promise.resolve();
-  var _recoveryCleanupTasks = [];
+  var recoveryAdmission = require("../codex-recovery-admission").attachRecoveryAdmission({
+    state: function() { return { epoch: _shutdownEpoch, shuttingDown: _shuttingDown, retiring: _recoveryIdleShutdown === _shutdownEpoch,
+      initializing: _initializing, refCount: _refCount, server: _appServer, entries: _activeQueries.slice() }; },
+    shutdownError: createShutdownError,
+    stopIdle: async function() {
+      _recoveryIdleShutdown = _shutdownEpoch;
+      try { return await adapter.shutdownIfIdle(0); }
+      finally { _recoveryIdleShutdown = null; }
+    },
+    createRuntime: function(queryOpts) {
+      return createCodexAdapter(Object.assign({}, _defaultInitOpts, {
+        recoveryRuntime: true, recoverySessionMcpServer: queryOpts.sessionMcpServer,
+      }));
+    },
+  });
 
   function scopedSkillOptions(env) {
     if (!_runtimeLinuxUser) return { env: env };
@@ -1541,102 +1555,6 @@ function createCodexAdapter(opts) {
     updateLastActiveAt();
   }
 
-  function retainRecoveryRuntime(runtime) {
-    _recoveryRuntimes.push(runtime);
-  }
-
-  function removeRecoveryRuntime(runtime) {
-    var next = [];
-    for (var i = 0; i < _recoveryRuntimes.length; i++) {
-      if (_recoveryRuntimes[i] !== runtime) next.push(_recoveryRuntimes[i]);
-    }
-    _recoveryRuntimes = next;
-  }
-
-  function cleanupRecoveryRuntime(runtime) {
-    for (var i = 0; i < _recoveryCleanupTasks.length; i++) {
-      if (_recoveryCleanupTasks[i].runtime === runtime) return _recoveryCleanupTasks[i].promise;
-    }
-    var task = { runtime: runtime, promise: null };
-    _recoveryCleanupTasks.push(task);
-    var priorCleanup = _recoveryCleanup;
-    task.promise = Promise.resolve(priorCleanup).catch(function() {
-      return null;
-    }).then(function() {
-      return runtime.shutdown();
-    }).catch(function(error) {
-      console.error("[yoke/codex] Isolated recovery runtime shutdown failed:", error.message || error);
-    }).then(function() {
-      removeRecoveryRuntime(runtime);
-      var remainingTasks = [];
-      for (var ti = 0; ti < _recoveryCleanupTasks.length; ti++) {
-        if (_recoveryCleanupTasks[ti] !== task) remainingTasks.push(_recoveryCleanupTasks[ti]);
-      }
-      _recoveryCleanupTasks = remainingTasks;
-    });
-    _recoveryCleanup = task.promise;
-    return task.promise;
-  }
-
-  function shutdownRecoveryRuntimes() {
-    var runtimes = _recoveryRuntimes.slice();
-    if (!runtimes.length) return _recoveryCleanup;
-    return Promise.all(runtimes.map(function(runtime) {
-      return cleanupRecoveryRuntime(runtime);
-    })).then(function() {
-      _recoveryRuntimes = [];
-    });
-  }
-
-  async function createIsolatedRecoveryQuery(queryOpts) {
-    var shutdownEpoch = _shutdownEpoch;
-    function checkCurrent() {
-      idleRecovery.checkAbort(queryOpts);
-      if (_shuttingDown || shutdownEpoch !== _shutdownEpoch) throw createShutdownError();
-    }
-    var releaseHandoff;
-    var priorHandoff = _recoveryHandoff;
-    var myHandoff = new Promise(function(resolve) { releaseHandoff = resolve; });
-    _recoveryHandoff = myHandoff;
-    await (priorHandoff || Promise.resolve());
-    try {
-      await _recoveryCleanup;
-      checkCurrent();
-      if (!_initializing && _refCount > 0) {
-        await idleRecovery.retireIdleQueries(_activeQueries.slice(), _appServer, checkCurrent);
-      }
-      checkCurrent();
-      if (_refCount > 0 || _initializing) {
-        throw new Error("Codex resumed-tool recovery is waiting for an active shared runtime; retry after its current queries finish.");
-      }
-      if (_appServer) {
-        var stopped = await adapter.shutdownIfIdle(0);
-        if (!stopped) throw new Error("Codex resumed-tool recovery could not safely release the shared runtime; retry after its current queries finish.");
-      }
-      checkCurrent();
-      var recoveryRuntime = createCodexAdapter(Object.assign({}, _defaultInitOpts, {
-        recoveryRuntime: true,
-        recoverySessionMcpServer: queryOpts.sessionMcpServer,
-      }));
-      retainRecoveryRuntime(recoveryRuntime);
-      var recoveryOpts = Object.assign({}, queryOpts, {
-        isolatedRecovery: true,
-        onRuntimeFinished: function() {
-          return cleanupRecoveryRuntime(recoveryRuntime);
-        },
-      });
-      try {
-        return await recoveryRuntime.createQuery(recoveryOpts);
-      } catch (error) {
-        await cleanupRecoveryRuntime(recoveryRuntime);
-        throw error;
-      }
-    } finally {
-      releaseHandoff();
-      if (_recoveryHandoff === myHandoff) _recoveryHandoff = null;
-    }
-  }
-
   function buildReadyResponse(skillNames) {
     return {
       models: _cachedModels,
@@ -1777,12 +1695,14 @@ function createCodexAdapter(opts) {
       if (_runtimeLinuxUser && requestedLinuxUser && requestedLinuxUser !== _runtimeLinuxUser) {
         return Promise.reject(new Error("Codex runtime user mismatch"));
       }
-      if (_shuttingDown) {
+      if (_shuttingDown && _recoveryIdleShutdown !== _shutdownEpoch) {
         return Promise.reject(createShutdownError());
       }
-      if (_recoveryHandoff) {
+      try { recoveryAdmission.checkSharedExit(); }
+      catch (error) { return Promise.reject(error); }
+      if (recoveryAdmission.pending()) {
         var initEpoch = _shutdownEpoch;
-        return _recoveryHandoff.then(function() {
+        return recoveryAdmission.pending().then(function() {
           if (initEpoch !== _shutdownEpoch) throw createShutdownError();
           return adapter.init(initOpts);
         });
@@ -1963,6 +1883,10 @@ function createCodexAdapter(opts) {
       return null;
     },
 
+    retireIdleForRecovery: function(checkCurrent) {
+      return idleRecovery.retireIdleQueries(_activeQueries.slice(), _appServer, checkCurrent);
+    },
+
     createQuery: async function(queryOpts) {
       var requestedLinuxUser = queryOpts && queryOpts.linuxUser;
       if (!_runtimeLinuxUser && requestedLinuxUser) {
@@ -1974,28 +1898,37 @@ function createCodexAdapter(opts) {
       if (_runtimeLinuxUser && requestedLinuxUser && requestedLinuxUser !== _runtimeLinuxUser) {
         throw new Error("Codex runtime user mismatch");
       }
-      if (_shuttingDown) {
+      if (_shuttingDown && _recoveryIdleShutdown !== _shutdownEpoch) {
         throw createShutdownError();
       }
       if (queryOpts && queryOpts.sessionMcpServer && queryOpts.resumeSessionId && !queryOpts.isolatedRecovery) {
-        return createIsolatedRecoveryQuery(queryOpts);
+        return recoveryAdmission.createQuery(queryOpts);
       }
       var queryEpoch = _shutdownEpoch;
+      function checkAdmission() {
+        idleRecovery.checkAbort(queryOpts || {});
+        if ((_shuttingDown && _recoveryIdleShutdown !== _shutdownEpoch) || queryEpoch !== _shutdownEpoch) throw createShutdownError();
+      }
       // Recheck after every await: recovery may replace the runtime while an
       // ordinary start is waiting for initialization or an earlier handoff.
       while (true) {
         idleRecovery.checkAbort(queryOpts || {});
-        if (_shuttingDown || queryEpoch !== _shutdownEpoch) throw createShutdownError();
-        if (_recoveryHandoff) {
-          await _recoveryHandoff;
+        if ((_shuttingDown && _recoveryIdleShutdown !== _shutdownEpoch) || queryEpoch !== _shutdownEpoch) throw createShutdownError();
+        recoveryAdmission.checkSharedExit();
+        if (recoveryAdmission.pending()) {
+          await idleRecovery.wait(recoveryAdmission.pending(), checkAdmission);
+          continue;
+        }
+        if (queryOpts.resumeSessionId && recoveryAdmission.hasTarget(queryOpts.resumeSessionId)) {
+          await recoveryAdmission.waitForTarget(queryOpts);
           continue;
         }
         if (_initializing && _initPromise) {
-          await _initPromise;
+          await idleRecovery.wait(_initPromise, checkAdmission);
           continue;
         }
         if (!_appServer || !_appServer.started) {
-          await adapter.init(queryOpts || {});
+          await idleRecovery.wait(adapter.init(queryOpts || {}), checkAdmission);
           continue;
         }
         break;
@@ -2174,12 +2107,20 @@ function createCodexAdapter(opts) {
     },
 
     // Shutdown the app-server process
+    shutdownForRecovery: async function() {
+      var proc = _appServer && _appServer.proc;
+      await adapter.shutdown();
+      if (proc && proc.exitCode === null && proc.signalCode === null) {
+        throw new Error('Codex recovery runtime exit could not be confirmed; its thread remains reserved.');
+      }
+    },
+
     shutdown: function() {
       _shutdownEpoch++;
       return Promise.all([
         beginShutdown(true),
         shutdownUserRuntimes("shutdown"),
-        shutdownRecoveryRuntimes(),
+        recoveryAdmission.shutdown(),
       ]).then(function() { return true; });
     },
 

package/lib/yoke/claude-worker-startup.js

@@ -0,0 +1,28 @@
+// A transport error must settle startup even before a query iterator exists.
+function attachWorkerStartup(worker, options) {
+  options = options || {};
+  var schedule = options.setTimeout || setTimeout;
+  var cancel = options.clearTimeout || clearTimeout;
+  var timer;
+  var settled = false;
+  worker.readyPromise = new Promise(function(resolve, reject) {
+    worker._readyResolve = function() { settle(null, resolve, reject); };
+    worker._readyReject = function(error) { settle(error, resolve, reject); };
+  });
+  // Warmup and cancellation may abandon startup before their await is installed.
+  worker.readyPromise.catch(function() {});
+  function settle(error, resolve, reject) {
+    if (settled) return;
+    settled = true;
+    if (timer) cancel(timer);
+    worker._readyResolve = null;
+    worker._readyReject = null;
+    if (error) reject(error); else resolve();
+  }
+  timer = schedule(function() {
+    if (worker._readyReject) worker._readyReject(new Error("Claude worker did not become ready before the startup deadline."));
+    if (typeof worker.kill === "function") worker.kill();
+  }, options.timeoutMs || 180000);
+  if (timer && typeof timer.unref === "function") timer.unref();
+}
+module.exports = { attachWorkerStartup: attachWorkerStartup };

package/lib/yoke/codex-idle-recovery.js

@@ -49,4 +49,84 @@ async function retireIdleQueries(entries, server, checkCurrent) {
   return true;
 }
 
-module.exports = { retireIdleQueries: retireIdleQueries, checkAbort: checkAbort };
+// A separate process may resume a different thread only after the shared
+// process proves it has no writer for that thread. Never infer this from the
+// number of query handles: Codex can retain a loaded thread after input ends.
+async function loadedThreads(server, checkCurrent) {
+  var cursor = null;
+  var threads = [];
+  var deadline = Date.now() + 5000;
+  for (var page = 0; page < 20; page++) {
+    var remaining = deadline - Date.now();
+    if (remaining <= 0) return null;
+    var result;
+    try {
+      result = await server.send('thread/loaded/list', { cursor: cursor, limit: 100 }, remaining);
+    } catch (error) {
+      checkCurrent();
+      if (!server.started) throw error;
+      return null;
+    }
+    checkCurrent();
+    if (!result || !Array.isArray(result.data) || !result.data.every(function(id) { return typeof id === 'string'; })) return null;
+    threads = threads.concat(result.data);
+    if (!result.nextCursor) return threads;
+    if (result.nextCursor === cursor) return null;
+    cursor = result.nextCursor;
+  }
+  return null;
+}
+
+async function threadIsAbsent(server, threadId, checkCurrent) {
+  var threads = await loadedThreads(server, checkCurrent);
+  return !!threads && threads.indexOf(threadId) === -1;
+}
+
+async function runtimeCanStop(server, retiredThreads, checkCurrent) {
+  var threads = await loadedThreads(server, checkCurrent);
+  return !!threads && threads.every(function(threadId) { return retiredThreads.indexOf(threadId) !== -1; });
+}
+
+async function releaseThread(entries, server, threadId, checkCurrent) {
+  if (!server || !server.started) throw new Error('Codex disconnected while checking recovery admission');
+  var matching = entries.filter(function(entry) {
+    return entry.handle && entry.handle.getRecoveryThreadId() === threadId;
+  });
+  if (!matching.length && await threadIsAbsent(server, threadId, checkCurrent)) return true;
+  if (matching.length) {
+    if (!await retireIdleQueries(matching, server, checkCurrent)) return false;
+    checkCurrent();
+  } else {
+    // A closed SDK handle can leave a loaded provider thread behind. Only an
+    // explicitly idle provider thread with verified terminal state may unload.
+    try {
+      var status = await server.send('thread/read', { threadId: threadId, includeTurns: false }, 5000);
+      checkCurrent();
+      if (!status || !status.thread || status.thread.id !== threadId
+          || !status.thread.status || status.thread.status.type !== 'idle') return false;
+      var terminals = await server.send('thread/backgroundTerminals/list', { threadId: threadId }, 5000);
+      checkCurrent();
+      if (!terminalsAreIdle(terminals)) return false;
+    } catch (error) { checkCurrent(); if (!server.started) throw error; return false; }
+  }
+  try { await server.send('thread/unsubscribe', { threadId: threadId }, 5000); }
+  catch (error) { checkCurrent(); if (!server.started) throw error; return false; }
+  return threadIsAbsent(server, threadId, checkCurrent);
+}
+
+// Poll the lifecycle without holding the admission lock. Also check Stop and
+// shutdown while a provider probe, initialization, or process exit is pending.
+function wait(promise, checkCurrent) {
+  return new Promise(function(resolve, reject) {
+    var timer = setInterval(function() {
+      try { checkCurrent(); } catch (error) { clearInterval(timer); reject(error); }
+    }, 25);
+    Promise.resolve(promise).then(function(value) {
+      clearInterval(timer);
+      try { checkCurrent(); resolve(value); } catch (error) { reject(error); }
+    }, function(error) { clearInterval(timer); reject(error); });
+  });
+}
+
+module.exports = { retireIdleQueries: retireIdleQueries, checkAbort: checkAbort,
+  releaseThread: releaseThread, runtimeCanStop: runtimeCanStop, wait: wait };

package/lib/yoke/codex-recovery-admission.js

@@ -0,0 +1,164 @@
+var idleRecovery = require('./codex-idle-recovery');
+
+// Serialize decisions, not whole model turns. Waiting for a target must release
+// the gate so an unrelated Driver can still answer its Worker's permissions.
+function attachRecoveryAdmission(ctx) {
+  var handoff = null;
+  var runtimes = [];
+  var targets = new Map();
+  var cleanupTasks = new Map();
+  var cleanupFailures = new Map();
+  var cleanup = Promise.resolve();
+  var unconfirmedSharedProcess = null;
+
+  function checkSharedExit() {
+    if (!unconfirmedSharedProcess) return;
+    if (unconfirmedSharedProcess.exitCode === null && unconfirmedSharedProcess.signalCode === null) {
+      throw new Error('Codex shared runtime exit could not be confirmed; recovery remains reserved.');
+    }
+    unconfirmedSharedProcess = null;
+  }
+
+  function checker(queryOpts) {
+    var epoch = ctx.state().epoch;
+    return function() {
+      idleRecovery.checkAbort(queryOpts);
+      var state = ctx.state();
+      if ((state.shuttingDown && !state.retiring) || state.epoch !== epoch) throw ctx.shutdownError();
+    };
+  }
+
+  function cleanupRuntime(runtime) {
+    if (cleanupTasks.has(runtime)) return cleanupTasks.get(runtime);
+    var task = cleanup.catch(function() { return null; }).then(function() {
+      return runtime.shutdownForRecovery();
+    }).then(function() {
+      runtimes = runtimes.filter(function(current) { return current !== runtime; });
+      targets.forEach(function(current, threadId) { if (current === runtime) targets.delete(threadId); });
+      cleanupTasks.delete(runtime);
+      return true;
+    }, function(error) {
+      console.error('[yoke/codex] Isolated recovery runtime shutdown failed:', error.message || error);
+      // Retain ownership after an unconfirmed exit. In particular, never admit
+      // a second writer just because bounded process cleanup reached its limit.
+      cleanupFailures.set(runtime, error);
+      return false;
+    });
+    cleanupTasks.set(runtime, task);
+    cleanup = task;
+    return task;
+  }
+
+  async function withAdmission(checkCurrent, action) {
+    var release;
+    var prior = handoff;
+    var own = new Promise(function(resolve) { release = resolve; });
+    var tail = Promise.resolve(prior).then(function() { return own; });
+    handoff = tail;
+    tail.then(function() { if (handoff === tail) handoff = null; });
+    try {
+      await idleRecovery.wait(prior || Promise.resolve(), checkCurrent);
+      await idleRecovery.wait(cleanup, checkCurrent);
+      checkSharedExit();
+      return await action();
+    } finally {
+      // An aborted waiter still links to its predecessor. Releasing its own
+      // slot cannot let a later caller overtake a probe that is still running.
+      release();
+    }
+  }
+
+  async function releaseTarget(threadId, checkCurrent) {
+    var prior = targets.get(threadId);
+    if (!prior) return true;
+    if (cleanupFailures.has(prior)) throw cleanupFailures.get(prior);
+    await prior.retireIdleForRecovery(checkCurrent);
+    await cleanup;
+    checkCurrent();
+    if (cleanupFailures.has(prior)) throw cleanupFailures.get(prior);
+    return !targets.has(threadId);
+  }
+
+  async function prepareShared(threadId, checkCurrent) {
+    var state = ctx.state();
+    if (state.initializing) return false;
+    var retiredThreads = [];
+    if (state.refCount > 0) {
+      var snapshots = state.entries.map(function(entry) { return entry.handle && entry.handle.getIdleRecoverySnapshot(); });
+      if (await idleRecovery.retireIdleQueries(state.entries, state.server, checkCurrent)) {
+        retiredThreads = snapshots.filter(Boolean).map(function(snapshot) { return snapshot.threadId; });
+      }
+    }
+    state = ctx.state();
+    if (!state.server) return true;
+    if (!state.refCount && await idleRecovery.runtimeCanStop(state.server, retiredThreads, checkCurrent)) {
+      var proc = state.server.proc;
+      var stopped = await ctx.stopIdle();
+      if (stopped) { unconfirmedSharedProcess = proc || null; checkSharedExit(); }
+      return stopped;
+    }
+    return idleRecovery.releaseThread(state.entries, state.server, threadId, checkCurrent);
+  }
+
+  async function waitUntilAvailable(queryOpts, action) {
+    var checkCurrent = checker(queryOpts);
+    var waiting = false;
+    if (typeof queryOpts.onRecoveryAdmission === 'function') queryOpts.onRecoveryAdmission(true);
+    try {
+      while (true) {
+        checkCurrent();
+        // Cancellation returns to the caller immediately, but an in-flight
+        // unsubscribe or shutdown retains the gate until its bounded RPC settles.
+        var result = await idleRecovery.wait(withAdmission(checkCurrent, action.bind(null, checkCurrent)), checkCurrent);
+        if (result) {
+          if (waiting && typeof queryOpts.onRecoveryWaiting === 'function') queryOpts.onRecoveryWaiting(false);
+          return result;
+        }
+        if (!waiting && typeof queryOpts.onRecoveryWaiting === 'function') queryOpts.onRecoveryWaiting(true);
+        waiting = true;
+        await idleRecovery.wait(new Promise(function(resolve) { setTimeout(resolve, 50); }), checkCurrent);
+      }
+    } finally {
+      if (typeof queryOpts.onRecoveryAdmission === 'function') queryOpts.onRecoveryAdmission(false);
+    }
+  }
+
+  function createQuery(queryOpts) {
+    return waitUntilAvailable(queryOpts, async function(checkCurrent) {
+      if (!await releaseTarget(queryOpts.resumeSessionId, checkCurrent)) return false;
+      if (!await prepareShared(queryOpts.resumeSessionId, checkCurrent)) return false;
+      checkCurrent();
+      var runtime = ctx.createRuntime(queryOpts);
+      runtimes.push(runtime);
+      targets.set(queryOpts.resumeSessionId, runtime);
+      try {
+        return await runtime.createQuery(Object.assign({}, queryOpts, {
+          isolatedRecovery: true,
+          onRuntimeFinished: function() { return cleanupRuntime(runtime); },
+        }));
+      } catch (error) {
+        await cleanupRuntime(runtime);
+        throw error;
+      }
+    });
+  }
+
+  return {
+    createQuery: createQuery,
+    pending: function() { return handoff; },
+    checkSharedExit: checkSharedExit,
+    hasTarget: function(threadId) { return targets.has(threadId); },
+    waitForTarget: function(queryOpts) {
+      return waitUntilAvailable(queryOpts, function(checkCurrent) { return releaseTarget(queryOpts.resumeSessionId, checkCurrent); });
+    },
+    shutdown: function() {
+      return Promise.all(runtimes.slice().map(cleanupRuntime)).then(function(results) {
+        checkSharedExit();
+        if (results.indexOf(false) !== -1) throw new Error('Codex recovery runtime cleanup could not be confirmed.');
+        return cleanup;
+      });
+    },
+  };
+}
+
+module.exports = { attachRecoveryAdmission: attachRecoveryAdmission };

package/lib/yoke/session-tool-transport.js

@@ -2,6 +2,7 @@
 
 var vendorRegistry = require("./vendor-registry");
 var CODEX_CATALOG_VERSION = 5;
+var MATE_SCHEDULE_TOOLS = ["begin_mate_schedule_interview", "propose_mate_schedule", "list_mate_schedules", "read_mate_schedule", "update_mate_schedule", "cancel_mate_schedule"];
 var SCHEDULE_TOOLS = ["begin_scheduled_task_interview", "propose_scheduled_task", "list_scheduled_tasks", "read_scheduled_task", "update_scheduled_task", "report_scheduled_task_outcome"];
 
 function capability(vendor) {
@@ -38,6 +39,7 @@ function questionToolName(vendor) {
 
 function bridgeServerForTool(name) {
   if (name === "ask_user_questions") return "yoke-user-input";
+  if (MATE_SCHEDULE_TOOLS.indexOf(name) !== -1) return "clay-mate-schedules";
   if (SCHEDULE_TOOLS.indexOf(name) !== -1) return "clay-scheduled-tasks";
   return null;
 }
@@ -50,4 +52,5 @@ module.exports = {
   questionToolName: questionToolName,
   bridgeServerForTool: bridgeServerForTool,
   SCHEDULE_TOOLS: SCHEDULE_TOOLS,
+  MATE_SCHEDULE_TOOLS: MATE_SCHEDULE_TOOLS,
 };