@jskit-ai/assistant-core 0.2.1 → 0.2.3

package/src/server/conversation/codexConversations.js

@@ -19,14 +19,41 @@ export function createCodexConversationCommands({
   interruptFailedCode,
   namespace,
   providerSessions,
-  sessionConnection,
   ensureSessionProvider,
+  borrowSessionProvider,
   steerFailedCode,
   turnOutcomes
 }) {
   const codexAppServerConversations = new Map();
   const codexAppServerConversationTurnStarts = new Map();
 
+  // Reads and Temporary chat commands borrow their provider instead of claiming
+  // it: the operation returns its borrow when it finishes, and an unused
+  // provider stops a short idle later.
+  function providerBorrow() {
+    return { release() {} };
+  }
+
+  // A persistent conversation holds its borrowed provider only while it
+  // observes native work running there: a turn, or an active goal.
+  function holdWhileActive(state) {
+    const active = state.persistent === true && Boolean(state.unsubscribe) &&
+      (codexAppServerConversationTurnIsActive(state.status) || state.goal?.status === "active");
+    if (active && !state.releaseProvider) {
+      state.releaseProvider = providerSessions.owner.holdProvider(state.provider);
+    } else if (!active && state.releaseProvider) {
+      const release = state.releaseProvider;
+      state.releaseProvider = null;
+      release();
+    }
+  }
+
+  function forgetObservation(state) {
+    state.unsubscribe?.();
+    state.unsubscribe = null;
+    holdWhileActive(state);
+  }
+
   function codexAppServerConversation(sessionId = "", conversationId = "") {
     return codexAppServerConversations.get(
       namespace(sessionId)
@@ -70,7 +97,7 @@ export function createCodexConversationCommands({
     const conversations = codexAppServerConversations.get(key) || new Map();
     let state = conversations.get(conversationId);
     if (state?.provider === provider && state.unsubscribe) return state;
-    state?.unsubscribe?.();
+    if (state) forgetObservation(state);
     state = { conversationId, provider, persistent: true, status: "ready", runId: "", error: "", turnOutcome: "" };
     state.unsubscribe = provider.subscribe((notification) => {
       if (codexAppServerNotificationThreadId(notification) !== conversationId) return;
@@ -105,6 +132,7 @@ export function createCodexConversationCommands({
           turnOutcome: completedOutcome
         }).catch(() => {});
       }
+      holdWhileActive(state);
     });
     conversations.set(conversationId, state);
     codexAppServerConversations.set(key, conversations);
@@ -139,6 +167,7 @@ export function createCodexConversationCommands({
     // Stop it once; browser reloads reuse the existing backend observer.
     if (previous?.provider !== context.provider && (codexAppServerConversationTurnIsActive(status) || goal?.status === "active")) {
       Object.assign(state, { runId, status: "inProgress", goal });
+      holdWhileActive(state);
       try {
         await context.provider.stopThreadForObservationLoss(conversationId, "");
       } catch (error) {
@@ -150,6 +179,7 @@ export function createCodexConversationCommands({
     }
     if (goal?.status === "active") status = "inProgress";
     Object.assign(state, { runId, status, goal });
+    holdWhileActive(state);
     const messages = [];
     for (const turn of turns) {
       const turnId = codexAppServerProviderTurnId(turn);
@@ -231,7 +261,7 @@ export function createCodexConversationCommands({
     return preparation.settings(config);
   }
 
-  async function acquireCodexAppServerConversationContext(sessionId, prepared, input = {}) {
+  async function acquireCodexAppServerConversationContext(sessionId, prepared, input = {}, borrow = null) {
     if (prepared.result) return prepared.result;
     const { context } = prepared;
     if (context.assistantScope) {
@@ -267,14 +297,21 @@ export function createCodexConversationCommands({
     assertAdmitted();
     const providerOptions = activeProvider ? null : await prepared.providerOptions;
     assertAdmitted();
-    const provider = activeProvider?.provider || await ensureSessionProvider(sessionId, providerOptions);
+    let provider = activeProvider?.provider;
+    // A Helper's provider keeps its own retained lifecycle.
+    if (!provider && borrow && !prepared.helperTurn) {
+      const borrowed = await borrowSessionProvider(sessionId, providerOptions);
+      borrow.release = borrowed.release;
+      provider = borrowed.provider;
+    }
+    provider ||= await ensureSessionProvider(sessionId, providerOptions);
     assertAdmitted();
     return prepared.project(provider, activeProvider?.providerOptions || providerOptions, helperRestore);
   }
 
-  async function codexAppServerConversationContext(sessionId, input, options) {
+  async function codexAppServerConversationContext(sessionId, input, options, borrow = null) {
     return acquireCodexAppServerConversationContext(sessionId,
-      await conversationPreparation.context(sessionId, input, options), input);
+      await conversationPreparation.context(sessionId, input, options), input, borrow);
   }
 
   async function codexAppServerEphemeralScopeContext(sessionId, input, scope) {
@@ -289,15 +326,20 @@ export function createCodexConversationCommands({
 
   async function createCodexAppServerConversation(sessionId, input = {}, options = {}) {
     return codexAppServerConversationResult(async () => {
-      const context = await codexAppServerConversationContext(sessionId, input, options);
-      if (context.ok === false) return context;
-      const execution = conversationPreparation.execution(sessionId, input, options, context, null, "create");
-      return createPreparedCodexAppServerConversation(sessionId, input, {
-        provider: context.provider,
-        executionProfile: execution.executionProfile,
-        helperIsolation: conversationPreparation.isolation,
-        threadPreparation: () => execution.threadPreparation
-      });
+      const borrow = input.persistent === true ? providerBorrow() : null;
+      try {
+        const context = await codexAppServerConversationContext(sessionId, input, options, borrow);
+        if (context.ok === false) return context;
+        const execution = conversationPreparation.execution(sessionId, input, options, context, null, "create");
+        return await createPreparedCodexAppServerConversation(sessionId, input, {
+          provider: context.provider,
+          executionProfile: execution.executionProfile,
+          helperIsolation: conversationPreparation.isolation,
+          threadPreparation: () => execution.threadPreparation
+        });
+      } finally {
+        borrow?.release();
+      }
     });
   }
 
@@ -401,35 +443,44 @@ export function createCodexConversationCommands({
           ok: false
         };
       }
-      const context = await codexAppServerConversationContext(sessionId, input, options);
-      if (context.ok === false) return context;
-      const conversationState = codexAppServerConversation(sessionId, conversationId);
-      const execution = conversationPreparation.execution(sessionId, input, options, context, conversationState, "start", { conversationId, prompt });
-      if (input.ephemeral === true && !conversationState) {
-        return {
-          ...conversationPreparation.expired(conversationId, input),
-          code: `${errorPrefix}temporary_conversation_expired`,
-          ok: false,
-        };
+      const borrow = input.persistent === true ? providerBorrow() : null;
+      try {
+        const context = await codexAppServerConversationContext(sessionId, input, options, borrow);
+        if (context.ok === false) return context;
+        // A persistent turn is observed on the provider it runs on, which its
+        // conversation then holds until the turn ends.
+        const conversationState = input.persistent === true
+          ? observeCodexConversation(sessionId, conversationId, context.provider)
+          : codexAppServerConversation(sessionId, conversationId);
+        const execution = conversationPreparation.execution(sessionId, input, options, context, conversationState, "start", { conversationId, prompt });
+        if (input.ephemeral === true && !conversationState) {
+          return {
+            ...conversationPreparation.expired(conversationId, input),
+            code: `${errorPrefix}temporary_conversation_expired`,
+            ok: false,
+          };
+        }
+        // Do not evaluate native preparation until the original duplicate/active
+        // checks and Helper isolation capability checks have run.
+        return await startPreparedCodexAppServerConversationTurn(sessionId, input, {
+          executionProfile: execution.executionProfile,
+          helperIsolation: conversationPreparation.isolation,
+          prepareTurn: execution.prepareTurn,
+          authorized: execution.authorized,
+          readOnly: execution.readOnly,
+          actorMetadata: execution.actorMetadata,
+          onEvent: execution.onEvent,
+          projectResult: execution.projectResult,
+          conversationId,
+          messageId,
+          prompt,
+          provider: context.provider,
+          conversationState,
+          threadPreparation: () => execution.threadPreparation
+        });
+      } finally {
+        borrow?.release();
       }
-      // Do not evaluate native preparation until the original duplicate/active
-      // checks and Helper isolation capability checks have run.
-      return startPreparedCodexAppServerConversationTurn(sessionId, input, {
-        executionProfile: execution.executionProfile,
-        helperIsolation: conversationPreparation.isolation,
-        prepareTurn: execution.prepareTurn,
-        authorized: execution.authorized,
-        readOnly: execution.readOnly,
-        actorMetadata: execution.actorMetadata,
-        onEvent: execution.onEvent,
-        projectResult: execution.projectResult,
-        conversationId,
-        messageId,
-        prompt,
-        provider: context.provider,
-        conversationState,
-        threadPreparation: () => execution.threadPreparation
-      });
     }));
   }
 
@@ -453,30 +504,42 @@ export function createCodexConversationCommands({
       if (input.persistent && conversationState?.persistent && conversationState.provider.isAvailable?.() &&
           !conversationState.provider.observationFailure && !conversationPreparation.admissionError(sessionId)) {
         // Poll the already observed native thread. Execution environment setup
-        // belongs to Send and reconnection, not every history read.
-        return readPreparedPersistentCodexConversation(sessionId, input, { provider: conversationState.provider });
+        // belongs to Send and reconnection, not every history read. The read
+        // holds that provider so its idle release cannot stop it mid-read.
+        const release = providerSessions.owner.holdProvider(conversationState.provider);
+        try {
+          return await readPreparedPersistentCodexConversation(sessionId, input, { provider: conversationState.provider });
+        } finally {
+          release();
+        }
       }
-      const context = await codexAppServerConversationContext(sessionId, input, options);
-      if (context.ok === false) {
-        return context;
+      // Reading history or status is not a use that keeps Codex running.
+      const borrow = providerBorrow();
+      try {
+        const context = await codexAppServerConversationContext(sessionId, input, options, borrow);
+        if (context.ok === false) {
+          return context;
+        }
+        if (input.persistent) return await readPreparedPersistentCodexConversation(sessionId, input, context);
+        const thread = await context.provider.readThread(conversationId);
+        const runId = normalizeCodexRunText(input.runId) || codexAppServerThreadTurnId(thread);
+        const status = codexAppServerThreadStatus(thread);
+        const text = runId
+          ? codexAppServerProviderThreadAssistantSegments(thread, runId)
+            .map((segment) => segment.text)
+            .join("\n\n")
+          : "";
+        return {
+          conversationId,
+          error: codexAppServerThreadError(thread),
+          ok: true,
+          runId,
+          status,
+          ...conversationPreparation.response(text)
+        };
+      } finally {
+        borrow.release();
       }
-      if (input.persistent) return readPreparedPersistentCodexConversation(sessionId, input, context);
-      const thread = await context.provider.readThread(conversationId);
-      const runId = normalizeCodexRunText(input.runId) || codexAppServerThreadTurnId(thread);
-      const status = codexAppServerThreadStatus(thread);
-      const text = runId
-        ? codexAppServerProviderThreadAssistantSegments(thread, runId)
-          .map((segment) => segment.text)
-          .join("\n\n")
-        : "";
-      return {
-        conversationId,
-        error: codexAppServerThreadError(thread),
-        ok: true,
-        runId,
-        status,
-        ...conversationPreparation.response(text)
-      };
     });
   }
 
@@ -500,17 +563,22 @@ export function createCodexConversationCommands({
         const result = await scoped.completion;
         return { ...result, conversationId, ok: true, runId };
       }
-      const context = await codexAppServerConversationContext(sessionId, input, {
-        assistantScope
-      });
-      if (context.ok === false) {
-        return context;
+      const borrow = input.persistent === true ? providerBorrow() : null;
+      try {
+        const context = await codexAppServerConversationContext(sessionId, input, {
+          assistantScope
+        }, borrow);
+        if (context.ok === false) {
+          return context;
+        }
+        const result = await waitForPreparedCodexAppServerConversationTurn(sessionId, input, {
+          provider: context.provider,
+          onEvent
+        });
+        return { ...result, ...conversationPreparation.response(result.rawText) };
+      } finally {
+        borrow?.release();
       }
-      const result = await waitForPreparedCodexAppServerConversationTurn(sessionId, input, {
-        provider: context.provider,
-        onEvent
-      });
-      return { ...result, ...conversationPreparation.response(result.rawText) };
     });
   }
 
@@ -536,14 +604,19 @@ export function createCodexConversationCommands({
       };
     }
     if (input.persistent) {
-      const context = await codexAppServerConversationContext(sessionId, input, options);
-      if (context.ok === false) return context;
-      return stopPersistentCodexConversation({
-        conversationId,
-        conversationState,
-        provider: context.provider,
-        turnOutcome
-      });
+      const borrow = providerBorrow();
+      try {
+        const context = await codexAppServerConversationContext(sessionId, input, options, borrow);
+        if (context.ok === false) return context;
+        return await stopPersistentCodexConversation({
+          conversationId,
+          conversationState,
+          provider: context.provider,
+          turnOutcome
+        });
+      } finally {
+        borrow.release();
+      }
     }
     const result = await interruptDetachedCodexAppServerConversationTurn(sessionId, {
       agentSettings: input.agentSettings,
@@ -557,12 +630,47 @@ export function createCodexConversationCommands({
     };
   }
 
+  // A scope's delete stops only what this server runs for it: its live providers,
+  // and a runtime whose earlier stop could not prove its exit. It never acquires
+  // a provider, which would start a Codex app-server only to stop it, so it needs
+  // no account, tool home or workdir. A runtime other providers share stays theirs.
+  async function stopCodexScopeRuntimes(sessionKey) {
+    const owner = providerSessions.owner;
+    const attempted = new Set([...owner.providers]
+      .filter(([providerKey]) => owner.providerOwners.get(providerKey)?.sessionKey === sessionKey)
+      .map(([, provider]) => provider));
+    const stopped = await owner.stopCachedProvidersForSession(sessionKey, { requireStopped: true });
+    const failed = [...stopped.failed];
+    const results = [...stopped.results];
+    for (const record of [...owner.ownedRuntimes.values()]) {
+      if (record.sessionKey !== sessionKey || attempted.has(record.provider) ||
+          owner.runtimeIsShared(record.providerKey, record.providerOptions)) continue;
+      try {
+        // Its provider is no longer cached, so the runtime's own options name its lock.
+        results.push(await owner.withLifecycle(() => owner.stopOwnedRuntime(record),
+          record.providerKey, record.providerOptions));
+      } catch (error) {
+        failed.push({ code: normalizeCodexRunText(error?.code), error: codexAppServerErrorMessage(error),
+          providerKey: record.providerKey, retryable: error?.retryable === true });
+      }
+    }
+    if (failed.length) {
+      const error = new Error(failed.map((failure) => failure.error).join(" "));
+      error.code = failed[0].code;
+      error.retryable = failed.every((failure) => failure.retryable);
+      error.details = { failed };
+      throw error;
+    }
+    return { ok: true, results, stopped: results.some((result) => result?.stopped === true) };
+  }
+
   async function deleteScopedCodexAppServerConversation(sessionId, input = {}, options = {}) {
     const conversationId = normalizeCodexRunText(input.conversationId);
     const sessionKey = namespace(sessionId);
     const conversations = codexAppServerConversations.get(sessionKey);
-    const conversationExpired = input.ephemeral === true && !conversations?.has(conversationId) &&
-      !(options.assistantScope && input.executionProfile);
+    // An ephemeral native thread lives only in the process that created it, so
+    // one this server no longer tracks has nothing left to delete.
+    const conversationExpired = input.ephemeral === true && !conversations?.has(conversationId);
     let result;
     if (conversationExpired) {
       result = {
@@ -577,23 +685,7 @@ export function createCodexConversationCommands({
         return { ...result, conversationId };
       }
     }
-    let providerExit = null;
-    if (options.assistantScope) {
-      const context = await codexAppServerEphemeralScopeContext(
-        sessionId,
-        input,
-        options.assistantScope
-      );
-      if (context.ok === false) {
-        return context;
-      }
-      const connection = sessionConnection(sessionId, context.providerOptions);
-      providerExit = await providerSessions.owner.stopProvider(connection.providerKey, context.providerOptions, {
-        preserveProcessExitProof: false,
-        requireStopped: true,
-        get runtimeHost() { return connection.runtimeHost; }
-      });
-    }
+    const providerExit = options.assistantScope ? await stopCodexScopeRuntimes(sessionKey) : null;
     return {
       ...result,
       conversationId,
@@ -602,19 +694,59 @@ export function createCodexConversationCommands({
     };
   }
 
+  // Close stops each persistent conversation through the provider that observes
+  // it. A closing session refuses a rebuilt context, and a new connection could
+  // not see the running turn anyway. One conversation's failure does not skip
+  // the others; it stays registered so that a retried close stops it.
+  async function stopObservedCodexConversation(state) {
+    const { provider } = state;
+    if (provider.observationFailure) {
+      await provider.failObservation(provider.observationFailure);
+      if (codexAppServerConversationTurnIsActive(state.status)) {
+        throw new Error("Codex's stop is not yet confirmed.");
+      }
+      return;
+    }
+    // A provider its owner has since closed observes nothing left to stop here:
+    // the owner stopped or detached its process, and reconnecting it would
+    // start a process nothing owns.
+    if (![...providerSessions.owner.providers].some(([, owned]) => owned === provider)) return;
+    // Closing is not the person stopping the turn; its status alone decides the outcome.
+    await stopPersistentCodexConversation({
+      conversationId: state.conversationId, conversationState: state, provider, turnOutcome: ""
+    });
+  }
+
   async function closeCodexAppServerConversations(sessionId) {
     const key = namespace(sessionId);
-    for (const state of codexAppServerConversations.get(key)?.values() || []) {
-      if (state.persistent) {
-        // Closing is not the person stopping the turn; its status alone decides the outcome.
-        await stopCodexAppServerConversation(sessionId, { conversationId: state.conversationId, persistent: true },
-          {}, { turnOutcome: "" });
-        state.unsubscribe?.();
-      } else {
+    const conversations = codexAppServerConversations.get(key);
+    const failed = [];
+    for (const state of [...(conversations?.values() || [])]) {
+      if (!state.persistent) {
         await deleteScopedCodexAppServerConversation(sessionId, { conversationId: state.conversationId }).catch(() => null);
+        conversations.delete(state.conversationId);
+        continue;
+      }
+      try {
+        await stopObservedCodexConversation(state);
+      } catch (error) {
+        failed.push({ conversationId: state.conversationId, error: codexAppServerErrorMessage(error) });
+        continue;
       }
+      forgetObservation(state);
+      conversations.delete(state.conversationId);
+    }
+    if (conversations && codexAppServerConversations.get(key) === conversations && !conversations.size) {
+      codexAppServerConversations.delete(key);
+    }
+    if (failed.length) {
+      const error = new Error(`Codex could not confirm that ${failed.length === 1 ? "a conversation" : `${failed.length} conversations`} stopped: ${
+        failed.map(({ conversationId, error: reason }) => `${conversationId} (${reason})`).join("; ")}. Retry closing the session.`);
+      error.code = `${errorPrefix}codex_conversation_close_failed`;
+      error.retryable = true;
+      error.details = { failed, sessionId: normalizeCodexRunText(sessionId) };
+      throw error;
     }
-    codexAppServerConversations.delete(key);
   }
 
   async function codexAppServerConversationControl(sessionId, input, {
@@ -626,10 +758,12 @@ export function createCodexConversationCommands({
       const prepared = conversationPreparation.control(sessionId, input, operation);
       if (prepared.result) return prepared.result;
       const { admission, threadId, turnId } = prepared;
+      // Stopping or deleting a thread is cleanup, not a use that keeps Codex running.
+      const borrow = providerBorrow();
       try {
         let context = null;
         try {
-          context = await codexAppServerConversationContext(sessionId, input, { assistantScope, runtime, session });
+          context = await codexAppServerConversationContext(sessionId, input, { assistantScope, runtime, session }, borrow);
         } catch (error) {
           const unavailable = prepared.unavailable();
           if (unavailable) return unavailable;
@@ -664,6 +798,7 @@ export function createCodexConversationCommands({
         }
         return await dispatch({ provider: context.provider, threadId, turnId });
       } finally {
+        borrow.release();
         admission.release();
       }
     });
@@ -942,6 +1077,7 @@ export function createCodexConversationCommands({
           status: "failed",
           watcher: null
         });
+        holdWhileActive(conversationState);
       }
       throw error;
     }
@@ -1011,7 +1147,10 @@ export function createCodexConversationCommands({
       });
       void conversationState.completion.catch(() => null);
     }
-    if (input.persistent && conversationState) Object.assign(conversationState, { runId, status, messageId });
+    if (input.persistent && conversationState) {
+      Object.assign(conversationState, { runId, status, messageId });
+      holdWhileActive(conversationState);
+    }
     return { conversationId, messageId, ok: true, runId, status };
   }
 
@@ -1039,6 +1178,7 @@ export function createCodexConversationCommands({
       conversationState.status = "interrupted";
       conversationState.watcher?.failNow(new Error("Temporary AI turn was stopped."));
       conversationState.watcher = null;
+      holdWhileActive(conversationState);
     }
     return result;
   }
@@ -1069,8 +1209,9 @@ export function createCodexConversationCommands({
     });
     if (result.ok !== false && conversation) {
       const { conversationId, sessionKey, conversations } = conversation;
-      conversations?.get(conversationId)?.watcher?.failNow(new Error("Temporary AI conversation was closed."));
-      conversations?.get(conversationId)?.unsubscribe?.();
+      const state = conversations?.get(conversationId);
+      state?.watcher?.failNow(new Error("Temporary AI conversation was closed."));
+      if (state) forgetObservation(state);
       conversations?.delete(conversationId);
       if (conversations?.size === 0) {
         codexAppServerConversations.delete(sessionKey);
@@ -1103,6 +1244,7 @@ export function createCodexConversationCommands({
       if (conversationState.goal?.status === "active") conversationState.goal = { ...conversationState.goal, status: "paused" };
       conversationState.watcher?.failNow(new Error("Temporary AI turn was stopped."));
       conversationState.watcher = null;
+      holdWhileActive(conversationState);
     }
     return { ok: true, conversationId, status: "interrupted" };
   }

package/src/server/conversation/codexEvents.js

@@ -241,18 +241,31 @@ function codexAppServerErrorText(value = null, seen = new Set()) {
   return [...new Set(messages)].join(" ");
 }
 
+// A running app-server keeps the credentials it started with. After a sign-out
+// or account switch, OpenAI's rejection ends its turns with ChatGPT's refresh
+// failure or an API key's raw 401; another provider's 401 keeps its own text.
+const CODEX_SIGNED_OUT_MESSAGE = "Codex (OpenAI) isn't connected. Sign in to Codex, then send your message again.";
+const CODEX_SIGNED_OUT_ERRORS = [
+  /\bcould not be refreshed because you have since logged out or signed in to another account\b/u,
+  /^unexpected status 401 Unauthorized\b.*\burl: https:\/\/(?:api\.openai\.com|chatgpt\.com)\//su
+];
+
+function codexAppServerSignedOutText(text = "") {
+  return CODEX_SIGNED_OUT_ERRORS.some((pattern) => pattern.test(text)) ? CODEX_SIGNED_OUT_MESSAGE : text;
+}
+
 function codexAppServerNotificationError(notification = {}) {
   const params = codexAppServerNotificationParams(notification);
   const status = isRecord(params.status) ? params.status : {};
   const turn = isRecord(params.turn) ? params.turn : {};
-  return normalizeNullableText(
+  return codexAppServerSignedOutText(normalizeNullableText(
     codexAppServerErrorText(params.error) ||
     params.message ||
     codexAppServerErrorText(status.error) ||
     status.message ||
     codexAppServerErrorText(turn.error) ||
     turn.message
-  );
+  ));
 }
 
 function codexAppServerNotificationUsageLimitExceeded(notification = {}) {
@@ -795,7 +808,7 @@ function codexAppServerProviderTurnText(thread = null, turnId = "") {
 }
 
 function codexAppServerProviderTurnError(turn = {}) {
-  return codexAppServerErrorText(turn.error || turn.status?.error || turn.state?.error);
+  return codexAppServerSignedOutText(codexAppServerErrorText(turn.error || turn.status?.error || turn.state?.error));
 }
 
 export {

package/src/server/conversation/codexHelperThreadRecovery.js

@@ -211,13 +211,22 @@ export function createCodexHelperThreadRecovery(lifecycle, {
 
   async function restoreCodexAppServerHelperThreads(projectRuntimeRoot = "", context = {}) {
     const previous = codexAppServerHelperThreadRestores.get(projectRuntimeRoot) || Promise.resolve();
+    // Every failure, including an unreadable ledger or a refused host notice,
+    // is reported in the result. Callers that require restoration assert it;
+    // cleanup and reconciliation continue with the records that did restore.
     const restore = previous.catch(() => null).then(async () => {
       const ledger = codexAppServerHelperThreadLedger(projectRuntimeRoot);
-      const listed = await ledger.readAll();
-      const failed = listed.failures.map((failure) => ({
+      const failed = [];
+      let listed = { failures: [], records: [] };
+      try {
+        listed = await ledger.readAll();
+      } catch (error) {
+        failed.push(codexAppServerHelperFailure({ projectRuntimeRoot }, error));
+      }
+      failed.push(...listed.failures.map((failure) => ({
         ...failure,
         projectRuntimeRoot
-      }));
+      })));
       const normalizedSessionId = normalizeText(context.sessionId);
       const records = listed.records.filter((record) => {
         return !normalizedSessionId || record.sessionId === normalizedSessionId;
@@ -238,7 +247,11 @@ export function createCodexHelperThreadRecovery(lifecycle, {
           failed.push(codexAppServerHelperFailure(record, error));
         }
       }
-      await context.publish({ records, failed, retiredBySession, normalizedSessionId });
+      try {
+        await context.publish({ records, failed, retiredBySession, normalizedSessionId });
+      } catch (error) {
+        failed.push(codexAppServerHelperFailure({ projectRuntimeRoot }, error));
+      }
       return {
         failed,
         ok: failed.length === 0,

package/src/server/conversation/codexHelperThreads.js

@@ -578,8 +578,17 @@ export function createCodexHelperThreadLifecycle({
     if (result.ok !== false) {
       return result;
     }
+    // Name the first failing record and its cause; details keep every failure.
+    const [first, ...others] = Array.isArray(result.failed) ? result.failed : [];
+    const sessionId = normalizeText(first?.sessionId);
+    const threadId = normalizeText(first?.threadId);
+    const subject = sessionId
+      ? `session ${sessionId}${threadId ? `, thread ${threadId}` : ""}`
+      : "the project's saved records";
+    const cause = first ? ` For ${subject}: ${normalizeText(first.error) || "restoration failed."}` : "";
+    const more = others.length ? ` (${others.length} more)` : "";
     throw codexAppServerHelperOwnershipError(
-      `${applicationName} could not reconcile persisted low-cost assistant thread ownership.`,
+      `${applicationName} could not reconcile persisted low-cost assistant thread ownership.${cause}${more}`,
       {
         failed: result.failed,
         retryable: result.failed?.some((failure) => failure.retryable !== false) !== false,