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

package/lib/yoke/claude-response-recovery.js

@@ -0,0 +1,155 @@
+// Claude delivery watchdog. Only an unanswered foreground turn is replayable.
+function attachResponseRecovery(ctx) {
+  var states = new Map();
+  var schedule = ctx.setTimeout || setTimeout;
+  var unschedule = ctx.clearTimeout || clearTimeout;
+  var waitMs = ctx.waitMs || 180000;
+  var stopMs = ctx.stopMs || 10000;
+
+  function live(session, state) {
+    return (!ctx.isCurrentProvider || ctx.isCurrentProvider(session)) && states.get(session) === state && !session.destroying && !session.taskStopRequested
+      && state.ownerId === session.ownerId && state.vendor === session.vendor
+      && (!ctx.sessions || ctx.sessions.get(session.localId) === session);
+  }
+  function clearTimer(state) {
+    if (state.timer) unschedule(state.timer);
+    state.timer = null;
+  }
+  function cancel(session, expected) {
+    var state = states.get(session);
+    if (expected && state !== expected) return;
+    if (state) clearTimer(state);
+    states.delete(session);
+  }
+  function protectedWait(session) {
+    return [session.pendingPermissions, session.pendingAskUser, session.pendingElicitations,
+      session.pendingUserDialogs, session.activeTaskToolIds].some(function(map) {
+      return map && Object.keys(map).length > 0;
+    }) || (session.activeBackgroundTasks && session.activeBackgroundTasks.length > 0);
+  }
+  function arm(session, state) {
+    clearTimer(state);
+    if (!state.turns.length || state.turns[0].progress || state.stopping) return;
+    state.timer = schedule(function() { expire(session, state); }, waitMs);
+    if (state.timer && state.timer.unref) state.timer.unref();
+  }
+  function snapshot(payload) {
+    return Object.assign({}, payload, { images: payload.images ? JSON.parse(JSON.stringify(payload.images)) : payload.images });
+  }
+  function begin(session, payload, retryState) {
+    if (retryState) return retryState;
+    cancel(session);
+    var state = { turns: [snapshot(payload)], timer: null, stopping: false, retried: false, ownerId: session.ownerId, vendor: session.vendor };
+    states.set(session, state);
+    arm(session, state);
+    return state;
+  }
+  function enqueue(session, payload) {
+    var state = states.get(session);
+    if (!state) return begin(session, payload);
+    state.turns.push(snapshot(payload));
+    return state;
+  }
+  function progress(session) {
+    var state = states.get(session);
+    if (!state || state.stopping || !state.turns.length) return;
+    state.turns[0].progress = true;
+    clearTimer(state);
+  }
+  function event(session, msg) {
+    var state = states.get(session);
+    if (!state || state.stopping || !msg) return;
+    var type = msg.yokeType;
+    if (type === 'error' || type === 'interrupted') { cancel(session); return; }
+    if (type === 'result') {
+      if (msg.subtype === 'success' && !msg.is_error && msg.numTurns === 0
+          && msg.origin && msg.origin.kind === 'task-notification'
+          && !msg.localCommand && msg.resultText === '') return;
+      var remaining = require('../sdk-turn-queue').pendingSends(session, msg);
+      state.turns = remaining ? state.turns.slice(-remaining) : [];
+      state.retried = false;
+      arm(session, state);
+      if (!state.turns.length) cancel(session);
+    } else if ((type === 'text_delta' || type === 'thinking_delta') && (msg.text || msg.delta)
+        || type === 'tool_start' || type === 'tool_input_delta' || type === 'tool_progress'
+        || type === 'task_started' || type === 'task_progress' || type === 'subagent_message'
+        || type === 'message' && msg.messageRole === 'assistant' && msg.content && msg.content.length) {
+      progress(session);
+    }
+  }
+  function finish(session, state, text) {
+    if (!live(session, state)) { cancel(session, state); return; }
+    cancel(session);
+    // Fence late output when a transport cannot confirm termination.
+    session._sdkQueryGeneration = Number(session._sdkQueryGeneration || 0) + 1;
+    session.isProcessing = false;
+    session._awaitingTurnResult = false;
+    session._queuedTurnCount = 0;
+    ctx.changed();
+    ctx.record(session, { type: 'thinking_stop' });
+    ctx.record(session, { type: 'error', text: text });
+    ctx.record(session, { type: 'done', code: 1 });
+    ctx.broadcast();
+  }
+  async function expire(session, state) {
+    clearTimer(state);
+    if (!live(session, state)) { cancel(session, state); return; }
+    // Never stop a known tool or a human decision because prose is absent.
+    if (protectedWait(session)) { progress(session); return; }
+    state.stopping = true;
+    ctx.record(session, { type: 'info', text: 'Claude has not responded for three minutes. Stopping this attempt safely before retrying.' });
+    var timeout;
+    var stopped = false;
+    try {
+      var stopAttempt = (async function() {
+        var handle = session.queryInstance || state.handle;
+        if (!handle && session.abortController) session.abortController.abort();
+        if (!handle && state.starting) await state.starting;
+        handle = handle || session.queryInstance || state.handle;
+        if (handle) {
+          if (typeof handle.stopAndWait !== 'function') return false;
+          await handle.stopAndWait();
+          if (session.streamPromise) await session.streamPromise;
+        }
+        return true;
+      })();
+      session._responseRecoveryStopPending = stopAttempt;
+      stopAttempt.then(function(confirmed) {
+        if (confirmed && session._responseRecoveryStopPending === stopAttempt) session._responseRecoveryStopPending = null;
+      }, function() {});
+      stopped = await Promise.race([
+        stopAttempt,
+        new Promise(function(resolve) { timeout = schedule(function() { resolve(false); }, stopMs); }),
+      ]);
+    } catch (e) { stopped = false; }
+    if (timeout) unschedule(timeout);
+    if (!live(session, state)) { cancel(session, state); return; }
+    if (!stopped) {
+      finish(session, state, 'Claude could not be confirmed stopped. Automatic retry was cancelled to avoid running your request twice. Check your Claude connection before trying again.');
+      return;
+    }
+    if (state.retried || state.turns.length !== 1) {
+      finish(session, state, state.retried
+        ? 'Claude still has not responded after one automatic retry. Please send your message again or check your Claude connection.'
+        : 'Claude did not respond. Several messages were queued, so automatic replay was cancelled to avoid duplicating work. Please send the unanswered messages again.');
+      return;
+    }
+    state.retried = true;
+    state.stopping = false;
+    session.isProcessing = true;
+    ctx.changed();
+    ctx.record(session, { type: 'info', text: 'The previous attempt has stopped. Retrying your original message once.' });
+    ctx.send(session, { type: 'status', status: 'processing' });
+    arm(session, state);
+    var payload = state.turns[0];
+    await ctx.restart(session, payload, state);
+  }
+  return {
+    begin: begin, enqueue: enqueue, event: event, progress: progress, cancel: cancel,
+    current: function(session) { return states.get(session); },
+    valid: live,
+    stopping: function(session) { var state = states.get(session); return !!(state && state.stopping); },
+    dispose: function() { states.forEach(function(state) { clearTimer(state); }); states.clear(); },
+  };
+}
+module.exports = { attachResponseRecovery: attachResponseRecovery };

package/lib/yoke/claude-transcript-hygiene.js

@@ -0,0 +1,34 @@
+var CLAUDE_INTERRUPTED_TEXT = "[Request interrupted by user]";
+function extractClaudeUserText(event) {
+  var content = event && event.message && event.message.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  var parts = [];
+  for (var i = 0; i < content.length; i++) {
+    if (content[i] && content[i].type === "text" && typeof content[i].text === "string") {
+      parts.push(content[i].text);
+    }
+  }
+  return parts.join("");
+}
+
+// SDK capability probes create a real Claude transcript with a single "hi"
+// prompt. Newer Claude Code versions append an interruption record when Clay
+// aborts the probe, so that bookkeeping record must not make the transcript
+// look like a real two-turn conversation.
+function isClaudeWarmupTranscript(events) {
+  var promptCount = 0;
+  for (var i = 0; i < events.length; i++) {
+    var event = events[i];
+    if (!event || typeof event !== "object") continue;
+    if (event.type === "assistant") return false;
+    if (event.type !== "user" || !event.message || event.message.role !== "user") continue;
+    var text = extractClaudeUserText(event);
+    if (text === CLAUDE_INTERRUPTED_TEXT) continue;
+    if (text !== "hi") return false;
+    promptCount++;
+  }
+  return promptCount === 1;
+}
+
+module.exports = { extractClaudeUserText: extractClaudeUserText, isClaudeWarmupTranscript: isClaudeWarmupTranscript };

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/clay-skill-install.js

@@ -0,0 +1,33 @@
+// Runs under the requesting OS identity. The installer only sees a private staging project.
+var fs = require('fs');
+var path = require('path');
+var spawn = require('child_process').spawn;
+var storage = require('../clay-skill-storage');
+var base = process.argv[2];
+var name = process.argv[3];
+var url = process.argv[4];
+if (!storage.isClaySkill(name) || !/^https:\/\//i.test(url)) throw new Error('Invalid Clay skill install request');
+storage.directory(path.join(base, '.clay'));
+var stage = fs.mkdtempSync(path.join(base, '.clay', 'skill-install-'));
+var child = spawn(process.platform === 'win32' ? 'npx.cmd' : 'npx', ['skills', 'add', url, '--skill', name, '--yes', '--agent', 'claude-code'], { cwd: stage, stdio: 'inherit', env: process.env });
+function cleanup() { fs.rmSync(stage, { recursive: true, force: true }); }
+child.on('error', function (error) { console.error(error.message); cleanup(); process.exitCode = 1; });
+process.on('SIGTERM', function () { child.kill('SIGTERM'); });
+child.on('close', function (code) {
+  try {
+    if (code !== 0) throw new Error('Skill installer exited with code ' + code);
+    var candidates = ['.agents', '.claude'].map(function (vendor) { return path.join(stage, vendor, 'skills', name); });
+    var source = candidates.find(function (dir) { return fs.existsSync(path.join(dir, 'SKILL.md')); });
+    if (!source) throw new Error('Installer did not create the requested skill in the private staging project');
+    var root = storage.privateRoot(base); storage.directory(root);
+    var destination = path.join(root, name);
+    var pending = path.join(root, '.' + name + '-' + process.pid);
+    fs.cpSync(source, pending, { recursive: true, dereference: true });
+    if (fs.existsSync(destination)) {
+      var backups = path.join(base, '.clay', 'skill-backups'); storage.directory(backups);
+      fs.renameSync(destination, path.join(backups, name + '-' + Date.now()));
+    }
+    fs.renameSync(pending, destination);
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+  finally { cleanup(); }
+});

package/lib/yoke/cli-sessions.js

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

package/lib/yoke/codex-app-server.js

@@ -17,9 +17,9 @@ var { wrapSpawnAsUser } = require("../os-users");
 //
 // The bundled @openai/codex platform package is the default. Set the
 // CLAY_CODEX_PATH env var to an existing executable to run a different codex
-// build (local dev build, system install, pinned older release); the chosen
-// binary is logged on every resolution. An unset or non-existent
-// CLAY_CODEX_PATH silently falls back to the bundled resolution.
+// build (local dev build, system install, pinned older release). An unset
+// override uses bundled resolution; an explicitly invalid override fails
+// closed without selecting a different installation.
 
 var PLATFORM_PACKAGE_BY_TARGET = {
   "aarch64-apple-darwin": "@openai/codex-darwin-arm64",
@@ -45,14 +45,9 @@ function getTargetTriple() {
 }
 
 function findCodexPath() {
-  var override = process.env.CLAY_CODEX_PATH;
-  if (override) {
-    if (fs.existsSync(override)) {
-      console.log("[codex-app-server] Using CLAY_CODEX_PATH binary:", override);
-      return override;
-    }
-    console.warn("[codex-app-server] CLAY_CODEX_PATH does not exist, falling back to bundled codex:", override);
-  }
+  var discovery = require("./discovery");
+  var override = discovery.explicitEntry(process.env, "CLAY_CODEX_PATH", false);
+  if (override !== undefined) return override;
 
   var triple = getTargetTriple();
   if (!triple) throw new Error("Unsupported platform: " + process.platform + "/" + process.arch);
@@ -74,7 +69,7 @@ function findCodexPath() {
       path.join(vendorRoot, triple, "codex", binaryName),
     ];
     for (var i = 0; i < candidates.length; i++) {
-      if (fs.existsSync(candidates[i])) {
+      if (discovery.validEntry(candidates[i], false)) {
         console.log("[codex-app-server] Using bundled codex binary:", candidates[i]);
         return candidates[i];
       }

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 };