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

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");
@@ -527,7 +528,7 @@ function flattenEvent(raw) {
   // --- rate_limit_event ---
   if (raw.type === "rate_limit_event" && raw.rate_limit_info) {
     base.yokeType = "rate_limit";
-    base.rateLimitInfo = raw.rate_limit_info;
+    base.rateLimitInfo = Object.assign({}, raw.rate_limit_info, { isUsingOverage: raw.rate_limit_info.isUsingOverage === true || raw.rate_limit_info.overageInUse === true });
     return base;
   }
 
@@ -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;
           });
         },
@@ -700,6 +704,15 @@ function createQueryHandle(rawQuery, messageQueue, abortController) {
       return Promise.resolve(null);
     },
 
+    // Account plan usage through the SDK's usage call, which the SDK marks
+    // experimental: guarded by capability, resolves null when absent, and the
+    // caller validates the shape. Transcript scanning is skipped.
+    getAccountUsage: function() {
+      var method = rawQuery && rawQuery.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET;
+      if (typeof method === "function") return Promise.resolve(method.call(rawQuery, { skipBehaviors: true }));
+      return Promise.resolve(null);
+    },
+
     supportedModels: function() {
       if (rawQuery && typeof rawQuery.supportedModels === "function") {
         return rawQuery.supportedModels();
@@ -715,6 +728,11 @@ function createQueryHandle(rawQuery, messageQueue, abortController) {
       }
     },
 
+    stopAndWait: function() {
+      handle.abort();
+      return stopped;
+    },
+
     close: function() {
       closed = true;
       removeAbort();
@@ -818,9 +836,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,8 +876,16 @@ 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() {
     console.log("[PERF] spawnWorker: socket listen ready +" + (Date.now() - spawnT0) + "ms");
@@ -892,6 +916,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 +937,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 +1113,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 +1333,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 +1342,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
@@ -1451,6 +1491,9 @@ function createWorkerQueryHandle(worker, canUseTool, onElicitation, callMcpTool,
       return iterEnded ? Promise.resolve(null) : contextRequests.request(options);
     },
 
+    // The OS-isolated worker protocol has no account usage request.
+    getAccountUsage: function() { return Promise.resolve(null); },
+
     supportedModels: function() {
       return Promise.resolve([]);
     },
@@ -1472,6 +1515,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
@@ -1507,43 +1555,7 @@ function createWorkerQueryHandle(worker, canUseTool, onElicitation, callMcpTool,
 
 // --- Adapter factory ---
 
-function resolveClaudeBinaryPath() {
-  // 1. Explicit env var override
-  if (process.env.CLAUDE_CODE_PATH && fs.existsSync(process.env.CLAUDE_CODE_PATH)) {
-    return process.env.CLAUDE_CODE_PATH;
-  }
-
-  // 2. `which claude` in the daemon's PATH
-  try {
-    var result = require("child_process").execSync("which claude", { encoding: "utf8", timeout: 5000 }).trim();
-    if (result && fs.existsSync(result)) return result;
-  } catch (e) {}
-
-  // 3. Common per-user and system locations (best-effort fallback for the daemon user)
-  var home = process.env.HOME || "";
-  var candidates = [];
-  if (home) {
-    candidates.push(home + "/.npm-global/bin/claude");
-    candidates.push(home + "/.local/bin/claude");
-    candidates.push(home + "/.volta/bin/claude");
-    candidates.push(home + "/.bun/bin/claude");
-    candidates.push(home + "/bin/claude");
-  }
-  candidates.push("/usr/local/bin/claude");
-  candidates.push("/usr/bin/claude");
-  candidates.push("/opt/homebrew/bin/claude");
-  for (var i = 0; i < candidates.length; i++) {
-    try { if (fs.existsSync(candidates[i])) return candidates[i]; } catch (e) {}
-  }
-
-  // 4. Bundled CLI entry from the SDK's peer
-  try {
-    var resolved = require.resolve("@anthropic-ai/claude-code/cli.js");
-    if (resolved && fs.existsSync(resolved)) return resolved;
-  } catch (e) {}
-
-  return null;
-}
+var resolveClaudeBinaryPath = require("../providers/claude-executable").resolve;
 
 function createClaudeAdapter(opts) {
   var _cwd = (opts && opts.cwd) || process.cwd();
@@ -1556,6 +1568,7 @@ function createClaudeAdapter(opts) {
 
   var adapter = {
     vendor: "claude",
+    queryContract: require("./claude-query-contract"),
     userInputCapability: { mode: "native", native: true, transport: "AskUserQuestion/onElicitation" },
 
     // Path to worker script (sdk-bridge uses this to spawn worker processes)
@@ -1642,7 +1655,7 @@ function createClaudeAdapter(opts) {
 
             try {
               var models = await stream.supportedModels();
-              result.models = models || [];
+              result.models = require("../providers/claude-model-descriptions").list(models);
               _cachedModels = result.models;
             } catch (e) {
               // supportedModels may fail, models list will be empty
@@ -1909,7 +1922,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).
@@ -1954,7 +1970,7 @@ function createClaudeAdapter(opts) {
           warmupDone = true;
           var r = msg.result || {};
           resolve({
-            models: r.models || [],
+            models: require("../providers/claude-model-descriptions").list(r.models),
             defaultModel: r.model || "",
             skills: r.skills || [],
             slashCommands: r.slashCommands || [],
@@ -2071,7 +2087,7 @@ function createClaudeAdapter(opts) {
 
             try {
               var models = await stream.supportedModels();
-              result.models = models || [];
+              result.models = require("../providers/claude-model-descriptions").list(models);
               _cachedModels = result.models;
             } catch (e) {
               // supportedModels may fail, models list will be empty
@@ -2122,7 +2138,7 @@ function createClaudeAdapter(opts) {
           warmupDone = true;
           var r = msg.result || {};
           resolve({
-            models: r.models || [],
+            models: require("../providers/claude-model-descriptions").list(r.models),
             defaultModel: r.model || "",
             skills: r.skills || [],
             slashCommands: r.slashCommands || [],

package/lib/yoke/adapters/codex-query-contract.js

@@ -0,0 +1,25 @@
+// Codex restores dynamic definitions from the original thread catalog.
+// Keep persisted legacy field names here so old conversations remain readable.
+var fields = {
+  schedules: "codexDynamicToolCatalogVersion",
+  questions: "codexUserInputToolCatalogVersion",
+  browser: "codexSharedBrowserToolCatalogVersion",
+  issues: "codexIssuesToolCatalogVersion",
+  knowledge: "codexYouToolCatalogVersion",
+  linear: "codexLinearToolCatalogVersion",
+  notes: "codexNotesToolCatalogVersion",
+};
+module.exports = {
+  toolTransport: "dynamic",
+  catalogLifetime: "conversation",
+  externalToolTransport: "dynamic",
+  defaultUserInputMode: "fallback",
+  questionGuidance: require("../user-input-guidance").codexQuestionGuidance,
+  catalogVersion: function (session, family) { return Number(session[fields[family]] || 0); },
+  recordCatalog: function (session, versions) {
+    Object.keys(versions).forEach(function (family) {
+      if (fields[family]) session[fields[family]] = versions[family];
+    });
+  },
+  staleCatalogReason: "This Codex conversation predates Clay's scheduled-task tool catalog. Start a new conversation to use the assisted interview; manual task creation remains available here.",
+};

package/lib/yoke/adapters/codex.js

@@ -17,6 +17,7 @@ var createTurnStop = require("../codex-turn-stop").createTurnStop;
 var idleRecovery = require("../codex-idle-recovery");
 var modelCatalog = require("../codex-model-catalog");
 var normalizeQuotaSnapshot = require("../codex-rate-limits").normalizeSnapshot;
+var dynamicToolNames = require("../codex-dynamic-tool-names");
 
 // --- Reasoning defaults ---
 // Reasoning summaries are the only readable thinking channel Codex offers:
@@ -33,7 +34,7 @@ var normalizeQuotaSnapshot = require("../codex-rate-limits").normalizeSnapshot;
 var CODEX_REASONING_DEFAULTS = {
   model_reasoning_summary: "detailed",
 };
-var DEFAULT_CODEX_MODEL = "gpt-6-astra";
+var DEFAULT_CODEX_MODEL = modelCatalog.DEFAULT_MODEL;
 var CODEX_QUERY_BOUND_TOOL_CAPABILITY = { mode: "dynamic", resume: "session-mcp-recovery" };
 var CODEX_NOTE_TOOLS = {
   list_notes: true,
@@ -622,6 +623,8 @@ function flattenEvent(notification, state) {
     // Dynamic tools are supplied by Clay for a specific thread, such as the
     // Driver's pair-session controls.
     if (item.type === "dynamicToolCall" || item.type === "dynamic_tool_call") {
+      // Activity shows the original Clay name, not the Codex wire alias.
+      var dynamicDisplayName = state.dynamicToolCatalog ? state.dynamicToolCatalog.displayName(item.tool) : item.tool;
       if (!state.toolBlocks[item.id]) {
         state.blockCounter++;
         state.toolBlocks[item.id] = "blk_" + state.blockCounter;
@@ -630,13 +633,13 @@ function flattenEvent(notification, state) {
           yokeType: "tool_start",
           blockId: dynamicBlockId,
           toolId: item.id,
-          toolName: item.tool || "session_tool",
+          toolName: dynamicDisplayName || "session_tool",
         });
         events.push({
           yokeType: "tool_executing",
           blockId: dynamicBlockId,
           toolId: item.id,
-          toolName: item.tool || "session_tool",
+          toolName: dynamicDisplayName || "session_tool",
           input: item.arguments || {},
         });
       }
@@ -968,6 +971,15 @@ function createCodexQueryHandle(appServer, queryOpts) {
     // server request and waits for the client to execute and answer it.
     if (method === "item/tool/call") {
       var dynamicParams = msg.params || {};
+      var resolvedDynamicTool = (state.dynamicToolCatalog || dynamicToolNames.createCatalog([])).resolve(dynamicParams.tool, dynamicParams.namespace);
+      if (resolvedDynamicTool.error) {
+        appServer.respond(msg.id, {
+          contentItems: [{ type: "inputText", text: "Error: " + resolvedDynamicTool.error }],
+          success: false,
+        });
+        return;
+      }
+      var dynamicToolName = resolvedDynamicTool.name;
       if (!callDynamicTool) {
         appServer.respond(msg.id, {
           contentItems: [{ type: "inputText", text: "Session tool handler is unavailable" }],
@@ -976,7 +988,7 @@ function createCodexQueryHandle(appServer, queryOpts) {
         return;
       }
       function executeDynamicTool() {
-        return Promise.resolve(callDynamicTool(dynamicParams.tool, dynamicParams.arguments || {})).then(function (result) {
+        return Promise.resolve(callDynamicTool(dynamicToolName, dynamicParams.arguments || {})).then(function (result) {
           var content = result && Array.isArray(result.content) ? result.content : [];
           var contentItems = content.map(function (item) {
             return { type: "inputText", text: item && item.text ? item.text : JSON.stringify(item) };
@@ -987,7 +999,7 @@ function createCodexQueryHandle(appServer, queryOpts) {
           appServer.respond(msg.id, { contentItems: contentItems, success: !(result && result.isError) });
         });
       }
-      var permissionToolName = canonicalDynamicPermissionToolName(dynamicParams.tool);
+      var permissionToolName = canonicalDynamicPermissionToolName(dynamicToolName);
       var permission = canUseTool
         ? Promise.resolve(canUseTool(permissionToolName, dynamicParams.arguments || {}, {
           toolUseID: dynamicParams.callId || String(msg.id),
@@ -1158,13 +1170,15 @@ function createCodexQueryHandle(appServer, queryOpts) {
       if (queryOpts.webSearchMode) {
         threadParams.webSearchMode = queryOpts.webSearchMode;
       }
-      if (Array.isArray(queryOpts.dynamicTools) && queryOpts.dynamicTools.length > 0) {
-        threadParams.dynamicTools = queryOpts.dynamicTools.map(function (tool) {
+      // Built on resume too: the persisted catalog uses the same aliases.
+      state.dynamicToolCatalog = dynamicToolNames.createCatalog(Array.isArray(queryOpts.dynamicTools) ? queryOpts.dynamicTools : []);
+      if (state.dynamicToolCatalog.advertised.length > 0) {
+        threadParams.dynamicTools = state.dynamicToolCatalog.advertised.map(function (entry) {
           return {
             type: "function",
-            name: tool.name,
-            description: tool.description || tool.name,
-            inputSchema: dynamicInputSchema(tool.inputSchema),
+            name: entry.name,
+            description: entry.def.description || entry.def.name,
+            inputSchema: dynamicInputSchema(entry.def.inputSchema),
           };
         });
       }
@@ -1343,6 +1357,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 +1477,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,106 +1569,10 @@ 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,
-      defaultModel: DEFAULT_CODEX_MODEL,
+      defaultModel: modelCatalog.defaultModel(_cachedModels),
       skills: skillNames || [],
       slashCommands: skillNames || [],
       fastModeState: null,
@@ -1764,6 +1696,7 @@ function createCodexAdapter(opts) {
   var adapter = {
     vendor: "codex",
     queryBoundToolCapability: CODEX_QUERY_BOUND_TOOL_CAPABILITY,
+    queryContract: require("./codex-query-contract"),
     userInputCapability: { mode: "native", native: true, transport: "item/tool/requestUserInput" },
 
     init: function(initOpts) {
@@ -1777,12 +1710,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 +1898,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 +1913,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;
@@ -2009,7 +1957,7 @@ function createCodexAdapter(opts) {
         throw new Error("[yoke/codex] Adapter not initialized. Call init() first.");
       }
 
-      var model = queryOpts.model || DEFAULT_CODEX_MODEL;
+      var model = queryOpts.model || modelCatalog.defaultModel(_cachedModels);
       var ac = queryOpts.abortController || new AbortController();
       var activeEntry = {
         abort: function() {
@@ -2102,6 +2050,25 @@ function createCodexAdapter(opts) {
       return { handle: handle, backendPersistence: "ephemeral" };
     },
 
+    // Reads the account's own quota through the already-running app-server;
+    // it never starts a runtime and never starts a turn. Routed to the mapped
+    // OS user's runtime exactly like the other per-owner operations.
+    readAccountRateLimits: async function(opts) {
+      var requestedLinuxUser = opts && opts.linuxUser;
+      if (requestedLinuxUser) {
+        // Throws on a runtime bound to a different OS user; never answers from another identity.
+        var userRuntime = getUserRuntime(requestedLinuxUser);
+        if (userRuntime !== adapter) return userRuntime.readAccountRateLimits(withoutLinuxUser(opts));
+      }
+      if (_requiresLinuxUser) throw new Error("Codex requires a mapped Linux user while OS-user isolation is enabled");
+      if (!_appServer || !_appServer.started) {
+        var idle = new Error("Codex has not started in this project yet; open a Codex session to read account usage.");
+        idle.failureKind = "runtime_idle";
+        throw idle;
+      }
+      return _appServer.send("account/rateLimits/read", { excludeResetCreditDetails: true }, 15000);
+    },
+
     // --- Title generation ---
     generateTitle: async function(messages, opts) {
       var requestedLinuxUser = opts && opts.linuxUser;
@@ -2174,12 +2141,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; });
     },